diff options
Diffstat (limited to 'src/charon')
101 files changed, 3449 insertions, 46383 deletions
diff --git a/src/charon/Makefile.am b/src/charon/Makefile.am index 9522b6e6d..b66f23773 100644 --- a/src/charon/Makefile.am +++ b/src/charon/Makefile.am @@ -17,65 +17,90 @@ ipsec_PROGRAMS = charon charon_SOURCES = \ bus/bus.c bus/bus.h \ -bus/listeners/sys_logger.c bus/listeners/sys_logger.h \ bus/listeners/file_logger.c bus/listeners/file_logger.h \ -config/connections/connection.c config/connections/connection.h \ -config/connections/local_connection_store.c config/connections/local_connection_store.h config/connections/connection_store.h \ -config/policies/policy.c config/policies/policy.h \ -config/policies/local_policy_store.c config/policies/policy_store.h config/policies/local_policy_store.h \ +bus/listeners/sys_logger.c bus/listeners/sys_logger.h \ +config/backends/backend.h \ +config/backends/local_backend.c config/backends/local_backend.h \ +config/cfg_store.c config/cfg_store.h \ +config/child_cfg.c config/child_cfg.h \ +config/configuration.c config/configuration.h \ config/credentials/local_credential_store.c config/credentials/local_credential_store.h \ +config/ike_cfg.c config/ike_cfg.h \ +config/peer_cfg.c config/peer_cfg.h \ +config/proposal.c config/proposal.h \ config/traffic_selector.c config/traffic_selector.h \ -config/proposal.c config/proposal.h config/configuration.c config/configuration.h \ -sa/authenticators/eap_authenticator.h sa/authenticators/eap_authenticator.c \ -sa/authenticators/eap/eap_method.h sa/authenticators/eap/eap_method.c \ -sa/child_sa.c sa/child_sa.h sa/ike_sa.c sa/ike_sa.h sa/ike_sa_manager.c sa/ike_sa_manager.h \ -sa/ike_sa_id.c sa/ike_sa_id.h sa/tasks/task.c sa/tasks/task.h \ -sa/tasks/ike_init.c sa/tasks/ike_init.h \ -sa/tasks/ike_natd.c sa/tasks/ike_natd.h \ +control/controller.c control/controller.h \ +control/stroke_interface.c control/stroke_interface.h \ +daemon.c daemon.h \ +encoding/generator.c encoding/generator.h \ +encoding/message.c encoding/message.h \ +encoding/parser.c encoding/parser.h \ +encoding/payloads/auth_payload.c encoding/payloads/auth_payload.h \ +encoding/payloads/cert_payload.c encoding/payloads/cert_payload.h \ +encoding/payloads/certreq_payload.c encoding/payloads/certreq_payload.h \ +encoding/payloads/configuration_attribute.c encoding/payloads/configuration_attribute.h \ +encoding/payloads/cp_payload.c encoding/payloads/cp_payload.h \ +encoding/payloads/delete_payload.c encoding/payloads/delete_payload.h \ +encoding/payloads/eap_payload.c encoding/payloads/eap_payload.h \ +encoding/payloads/encodings.c encoding/payloads/encodings.h \ +encoding/payloads/encryption_payload.c encoding/payloads/encryption_payload.h \ +encoding/payloads/id_payload.c encoding/payloads/id_payload.h \ +encoding/payloads/ike_header.c encoding/payloads/ike_header.h \ +encoding/payloads/ke_payload.c encoding/payloads/ke_payload.h \ +encoding/payloads/nonce_payload.c encoding/payloads/nonce_payload.h \ +encoding/payloads/notify_payload.c encoding/payloads/notify_payload.h \ +encoding/payloads/payload.c encoding/payloads/payload.h \ +encoding/payloads/proposal_substructure.c encoding/payloads/proposal_substructure.h \ +encoding/payloads/sa_payload.c encoding/payloads/sa_payload.h \ +encoding/payloads/traffic_selector_substructure.c encoding/payloads/traffic_selector_substructure.h \ +encoding/payloads/transform_attribute.c encoding/payloads/transform_attribute.h \ +encoding/payloads/transform_substructure.c encoding/payloads/transform_substructure.h \ +encoding/payloads/ts_payload.c encoding/payloads/ts_payload.h \ +encoding/payloads/unknown_payload.c encoding/payloads/unknown_payload.h \ +encoding/payloads/vendor_id_payload.c encoding/payloads/vendor_id_payload.h \ +kernel/kernel_interface.c kernel/kernel_interface.h \ +network/packet.c network/packet.h \ +network/receiver.c network/receiver.h \ +network/sender.c network/sender.h \ +network/socket.c network/socket.h \ +processing/event_queue.c processing/event_queue.h \ +processing/job_queue.c processing/job_queue.h \ +processing/jobs/acquire_job.c processing/jobs/acquire_job.h \ +processing/jobs/delete_child_sa_job.c processing/jobs/delete_child_sa_job.h \ +processing/jobs/delete_ike_sa_job.c processing/jobs/delete_ike_sa_job.h \ +processing/jobs/initiate_job.c processing/jobs/initiate_job.h \ +processing/jobs/job.c processing/jobs/job.h \ +processing/jobs/process_message_job.c processing/jobs/process_message_job.h \ +processing/jobs/rekey_child_sa_job.c processing/jobs/rekey_child_sa_job.h \ +processing/jobs/rekey_ike_sa_job.c processing/jobs/rekey_ike_sa_job.h \ +processing/jobs/retransmit_job.c processing/jobs/retransmit_job.h \ +processing/jobs/route_job.c processing/jobs/route_job.h \ +processing/jobs/send_dpd_job.c processing/jobs/send_dpd_job.h \ +processing/jobs/send_keepalive_job.c processing/jobs/send_keepalive_job.h \ +processing/scheduler.c processing/scheduler.h \ +processing/thread_pool.c processing/thread_pool.h \ +sa/authenticators/authenticator.c sa/authenticators/authenticator.h \ +sa/authenticators/eap_authenticator.c sa/authenticators/eap_authenticator.h \ +sa/authenticators/eap/eap_method.c sa/authenticators/eap/eap_method.h \ +sa/authenticators/psk_authenticator.c sa/authenticators/psk_authenticator.h \ +sa/authenticators/rsa_authenticator.c sa/authenticators/rsa_authenticator.h \ +sa/child_sa.c sa/child_sa.h \ +sa/ike_sa.c sa/ike_sa.h \ +sa/ike_sa_id.c sa/ike_sa_id.h \ +sa/ike_sa_manager.c sa/ike_sa_manager.h \ +sa/task_manager.c sa/task_manager.h \ +sa/tasks/child_create.c sa/tasks/child_create.h \ +sa/tasks/child_delete.c sa/tasks/child_delete.h \ +sa/tasks/child_rekey.c sa/tasks/child_rekey.h \ sa/tasks/ike_auth.c sa/tasks/ike_auth.h \ -sa/tasks/ike_config.c sa/tasks/ike_config.h \ sa/tasks/ike_cert.c sa/tasks/ike_cert.h \ -sa/tasks/ike_rekey.c sa/tasks/ike_rekey.h \ +sa/tasks/ike_config.c sa/tasks/ike_config.h \ sa/tasks/ike_delete.c sa/tasks/ike_delete.h \ sa/tasks/ike_dpd.c sa/tasks/ike_dpd.h \ -sa/tasks/child_create.c sa/tasks/child_create.h \ -sa/tasks/child_delete.c sa/tasks/child_delete.h \ -sa/tasks/child_rekey.c sa/tasks/child_rekey.h \ -sa/authenticators/authenticator.c sa/authenticators/authenticator.h \ -sa/authenticators/rsa_authenticator.c sa/authenticators/rsa_authenticator.h \ -sa/authenticators/psk_authenticator.c sa/authenticators/psk_authenticator.h \ -sa/task_manager.c sa/task_manager.h encoding/payloads/encryption_payload.c \ -encoding/payloads/cert_payload.c encoding/payloads/payload.h encoding/payloads/traffic_selector_substructure.c \ -encoding/payloads/configuration_attribute.h encoding/payloads/proposal_substructure.h \ -encoding/payloads/transform_attribute.c encoding/payloads/transform_attribute.h \ -encoding/payloads/configuration_attribute.c encoding/payloads/transform_substructure.c \ -encoding/payloads/encryption_payload.h encoding/payloads/auth_payload.c encoding/payloads/ike_header.c \ -encoding/payloads/transform_substructure.h encoding/payloads/nonce_payload.c encoding/payloads/cert_payload.h \ -encoding/payloads/eap_payload.c encoding/payloads/ike_header.h encoding/payloads/auth_payload.h \ -encoding/payloads/ts_payload.c encoding/payloads/traffic_selector_substructure.h encoding/payloads/nonce_payload.h \ -encoding/payloads/notify_payload.c encoding/payloads/eap_payload.h encoding/payloads/notify_payload.h \ -encoding/payloads/ts_payload.h encoding/payloads/id_payload.c encoding/payloads/ke_payload.c \ -encoding/payloads/unknown_payload.c encoding/payloads/encodings.c encoding/payloads/id_payload.h \ -encoding/payloads/cp_payload.c encoding/payloads/delete_payload.c encoding/payloads/sa_payload.c \ -encoding/payloads/ke_payload.h encoding/payloads/unknown_payload.h encoding/payloads/encodings.h \ -encoding/payloads/certreq_payload.c encoding/payloads/cp_payload.h encoding/payloads/delete_payload.h \ -encoding/payloads/sa_payload.h encoding/payloads/vendor_id_payload.c encoding/payloads/certreq_payload.h \ -encoding/payloads/vendor_id_payload.h encoding/payloads/proposal_substructure.c encoding/payloads/payload.c \ -encoding/parser.h encoding/message.c encoding/generator.c encoding/message.h encoding/generator.h \ -encoding/parser.c daemon.c daemon.h network/packet.c \ -network/socket.c network/packet.h network/socket.h queues/jobs/job.h queues/jobs/job.c \ -queues/jobs/retransmit_job.h queues/jobs/initiate_job.h \ -queues/jobs/process_message_job.h queues/jobs/process_message_job.c \ -queues/jobs/delete_ike_sa_job.c queues/jobs/delete_ike_sa_job.h \ -queues/jobs/retransmit_job.c queues/jobs/initiate_job.c \ -queues/jobs/send_keepalive_job.c queues/jobs/send_keepalive_job.h \ -queues/jobs/rekey_child_sa_job.c queues/jobs/rekey_child_sa_job.h queues/jobs/delete_child_sa_job.c queues/jobs/delete_child_sa_job.h \ -queues/jobs/send_dpd_job.c queues/jobs/send_dpd_job.h queues/jobs/route_job.c queues/jobs/route_job.h \ -queues/jobs/acquire_job.c queues/jobs/acquire_job.h queues/jobs/rekey_ike_sa_job.c queues/jobs/rekey_ike_sa_job.h \ -queues/job_queue.c queues/event_queue.c queues/job_queue.h queues/event_queue.h \ -threads/kernel_interface.c threads/thread_pool.c threads/scheduler.c threads/sender.c \ -threads/sender.h threads/kernel_interface.h threads/scheduler.h threads/receiver.c threads/stroke_interface.c \ -threads/thread_pool.h threads/receiver.h threads/stroke_interface.h +sa/tasks/ike_init.c sa/tasks/ike_init.h \ +sa/tasks/ike_natd.c sa/tasks/ike_natd.h \ +sa/tasks/ike_rekey.c sa/tasks/ike_rekey.h \ +sa/tasks/task.c sa/tasks/task.h INCLUDES = -I$(top_srcdir)/src/libstrongswan -I$(top_srcdir)/src/charon -I$(top_srcdir)/src/stroke AM_CFLAGS = -rdynamic -DIPSEC_CONFDIR=\"${confdir}\" -DIPSEC_PIDDIR=\"${piddir}\" -DIPSEC_EAPDIR=\"${eapdir}\" diff --git a/src/charon/config/backends/backend.h b/src/charon/config/backends/backend.h new file mode 100644 index 000000000..a054a7221 --- /dev/null +++ b/src/charon/config/backends/backend.h @@ -0,0 +1,77 @@ +/** + * @file backend.h + * + * @brief Interface backend_t. + * + */ + +/* + * Copyright (C) 2006 Martin Willi + * Hochschule fuer Technik Rapperswil + * + * This program is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License as published by the + * Free Software Foundation; either version 2 of the License, or (at your + * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>. + * + * This program is distributed in the hope that it will be useful, but + * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY + * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * for more details. + */ + +#ifndef BACKEND_H_ +#define BACKEND_H_ + +typedef struct backend_t backend_t; + +#include <library.h> +#include <config/ike_cfg.h> +#include <config/peer_cfg.h> +#include <utils/linked_list.h> + + +/** + * @brief The interface for a configuration backend. + * + * @b Constructors: + * - implementations constructor, such as local_backend_create() + * + * @ingroup backends + */ +struct backend_t { + + /** + * @brief Get an ike_cfg identified by two hosts. + * + * @param this calling object + * @param my_host address of own host + * @param other_host address of remote host + * @return matching ike_config, or NULL if none found + */ + ike_cfg_t *(*get_ike_cfg)(backend_t *this, + host_t *my_host, host_t *other_host); + + /** + * @brief Get a peer_cfg identified by two IDs. + * + * @param this calling object + * @param my_id own ID + * @param other_id peers ID + * @return matching peer_config, or NULL if none found + */ + peer_cfg_t *(*get_peer_cfg)(backend_t *this, + identification_t *my_id, + identification_t *other_id); + + /** + * @brief Get a peer_cfg identified by its name. + * + * @param this calling object + * @param name configs name + * @return matching peer_config, or NULL if none found + */ + peer_cfg_t *(*get_peer_cfg_by_name)(backend_t *this, char *name); +}; + +#endif /* BACKEND_H_ */ diff --git a/src/charon/config/backends/local_backend.c b/src/charon/config/backends/local_backend.c new file mode 100644 index 000000000..534c71c97 --- /dev/null +++ b/src/charon/config/backends/local_backend.c @@ -0,0 +1,231 @@ +/** + * @file local_backend.c + * + * @brief Implementation of local_backend_t. + * + */ + +/* + * Copyright (C) 2006 Martin Willi + * Hochschule fuer Technik Rapperswil + * + * This program is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License as published by the + * Free Software Foundation; either version 2 of the License, or (at your + * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>. + * + * This program is distributed in the hope that it will be useful, but + * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY + * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * for more details. + */ + +#include <string.h> + +#include "local_backend.h" + +#include <daemon.h> +#include <utils/linked_list.h> + + +typedef struct private_local_backend_t private_local_backend_t; + +/** + * Private data of an local_backend_t object + */ +struct private_local_backend_t { + + /** + * Public part + */ + local_backend_t public; + + /** + * list of configs + */ + linked_list_t *cfgs; + + /** + * Mutex to exclusivly access list + */ + pthread_mutex_t mutex; +}; + +/** + * implements cfg_store_t.get_ike_cfg. + */ +static ike_cfg_t *get_ike_cfg(private_local_backend_t *this, + host_t *my_host, host_t *other_host) +{ + peer_cfg_t *peer; + ike_cfg_t *current, *found = NULL; + iterator_t *iterator; + host_t *my_candidate, *other_candidate; + enum { + MATCH_NONE = 0x00, + MATCH_ANY = 0x01, + MATCH_ME = 0x04, + MATCH_OTHER = 0x08, + } prio, best = MATCH_ANY; + + DBG2(DBG_CFG, "looking for a config for %H...%H", + my_host, other_host); + + iterator = this->cfgs->create_iterator_locked(this->cfgs, &this->mutex); + while (iterator->iterate(iterator, (void**)&peer)) + { + prio = MATCH_NONE; + current = peer->get_ike_cfg(peer); + my_candidate = current->get_my_host(current); + other_candidate = current->get_other_host(current); + + if (my_candidate->ip_equals(my_candidate, my_host)) + { + prio += MATCH_ME; + } + else if (my_candidate->is_anyaddr(my_candidate)) + { + prio += MATCH_ANY; + } + + if (other_candidate->ip_equals(other_candidate, other_host)) + { + prio += MATCH_OTHER; + } + else if (other_candidate->is_anyaddr(other_candidate)) + { + prio += MATCH_ANY; + } + + DBG2(DBG_CFG, " candidate '%s': %H...%H, prio %d", + peer->get_name(peer), my_candidate, other_candidate, prio); + + /* we require at least two MATCH_ANY */ + if (prio > best) + { + best = prio; + found = current; + } + } + if (found) + { + found->get_ref(found); + } + iterator->destroy(iterator); + return found; +} + +/** + * implements cfg_store_t.get_peer. + */ +static peer_cfg_t *get_peer_cfg(private_local_backend_t *this, + identification_t *my_id, + identification_t *other_id) +{ + peer_cfg_t *current, *found = NULL; + iterator_t *iterator; + identification_t *my_candidate, *other_candidate; + int wc1, wc2, total, best = MAX_WILDCARDS; + + DBG2(DBG_CFG, "looking for a config for %D...%D", my_id, other_id); + + iterator = this->cfgs->create_iterator_locked(this->cfgs, &this->mutex); + while (iterator->iterate(iterator, (void**)¤t)) + { + my_candidate = current->get_my_id(current); + other_candidate = current->get_other_id(current); + + if (my_candidate->matches(my_candidate, my_id, &wc1) && + other_id->matches(other_id, other_candidate, &wc2)) + { + total = wc1 + wc2; + + DBG2(DBG_CFG, " candidate '%s': %D...%D, wildcards %d", + current->get_name(current), my_candidate, other_candidate, + total); + + if (total < best) + { + found = current; + best = total; + } + } + } + if (found) + { + found->get_ref(found); + } + iterator->destroy(iterator); + return found; +} + +/** + * implements cfg_store_t.get_peer_by_name. + */ +static peer_cfg_t *get_peer_cfg_by_name(private_local_backend_t *this, + char *name) +{ + iterator_t *iterator; + peer_cfg_t *current, *found = NULL; + + iterator = this->cfgs->create_iterator(this->cfgs, TRUE); + while (iterator->iterate(iterator, (void**)¤t)) + { + if (streq(current->get_name(current), name)) + { + found = current; + found->get_ref(found); + break; + } + } + iterator->destroy(iterator); + return found; +} + +/** + * Implementation of local_backend_t.create_peer_cfg_iterator. + */ +static iterator_t* create_peer_cfg_iterator(private_local_backend_t *this) +{ + return this->cfgs->create_iterator_locked(this->cfgs, &this->mutex); +} + +/** + * Implementation of local_backend_t.add_peer_cfg. + */ +static void add_peer_cfg(private_local_backend_t *this, peer_cfg_t *config) +{ + pthread_mutex_lock(&this->mutex); + this->cfgs->insert_last(this->cfgs, config); + pthread_mutex_unlock(&this->mutex); +} + +/** + * Implementation of local_backend_t.destroy. + */ +static void destroy(private_local_backend_t *this) +{ + this->cfgs->destroy_offset(this->cfgs, offsetof(peer_cfg_t, destroy)); + free(this); +} + +/** + * Described in header. + */ +local_backend_t *local_backend_create(void) +{ + private_local_backend_t *this = malloc_thing(private_local_backend_t); + + this->public.backend.get_ike_cfg = (ike_cfg_t*(*)(backend_t*, host_t *, host_t *))get_ike_cfg; + this->public.backend.get_peer_cfg = (peer_cfg_t*(*)(backend_t*, identification_t *, identification_t *))get_peer_cfg; + this->public.backend.get_peer_cfg_by_name = (peer_cfg_t*(*)(backend_t*, char *))get_peer_cfg_by_name; + this->public.create_peer_cfg_iterator = (iterator_t*(*)(local_backend_t*))create_peer_cfg_iterator; + this->public.add_peer_cfg = (void(*)(local_backend_t*, peer_cfg_t *))add_peer_cfg; + this->public.destroy = (void(*)(local_backend_t*))destroy; + + /* private variables */ + this->cfgs = linked_list_create(); + pthread_mutex_init(&this->mutex, NULL); + + return (&this->public); +} diff --git a/src/charon/config/backends/local_backend.h b/src/charon/config/backends/local_backend.h new file mode 100644 index 000000000..041725ae4 --- /dev/null +++ b/src/charon/config/backends/local_backend.h @@ -0,0 +1,82 @@ +/** + * @file local_backend.h + * + * @brief Interface of local_backend_t. + * + */ + +/* + * Copyright (C) 2007 Martin Willi + * Hochschule fuer Technik Rapperswil + * + * This program is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License as published by the + * Free Software Foundation; either version 2 of the License, or (at your + * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>. + * + * This program is distributed in the hope that it will be useful, but + * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY + * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * for more details. + */ + +#ifndef LOCAL_BACKEND_H_ +#define LOCAL_BACKEND_H_ + +typedef struct local_backend_t local_backend_t; + +#include <library.h> +#include <config/backends/backend.h> + +/** + * @brief An in-memory backend to store configuration information. + * + * The local_backend_t stores the configuration in a simple list. Additional + * to the backend_t functionality, it adds the modification (add/remove). + * + * @b Constructors: + * - local_backend_create() + * + * @ingroup backends + */ +struct local_backend_t { + + /** + * Implements backend_t interface + */ + backend_t backend; + + /** + * @brief Add a peer_config to the backend. + * + * @param this calling object + * @param config peer_config to add to the backend + */ + void (*add_peer_cfg)(local_backend_t *this, peer_cfg_t *config); + + /** + * @brief Create an iterator over all peer configs. + * + * @param this calling object + * @return iterator over peer configs + */ + iterator_t* (*create_peer_cfg_iterator)(local_backend_t *this); + + /** + * @brief Destroy a local backend. + * + * @param this calling object + */ + void (*destroy)(local_backend_t *this); +}; + +/** + * @brief Creates a local_backend_t instance. + * + * @return local_backend instance. + * + * @ingroup config + */ +local_backend_t *local_backend_create(void); + +#endif /* LOCAL_BACKEND_H_ */ diff --git a/src/charon/config/cfg_store.c b/src/charon/config/cfg_store.c new file mode 100644 index 000000000..e06780a94 --- /dev/null +++ b/src/charon/config/cfg_store.c @@ -0,0 +1,164 @@ +/** + * @file cfg_store.c + * + * @brief Implementation of cfg_store_t. + * + */ + +/* + * Copyright (C) 2007 Martin Willi + * Hochschule fuer Technik Rapperswil + * + * This program is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License as published by the + * Free Software Foundation; either version 2 of the License, or (at your + * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>. + * + * This program is distributed in the hope that it will be useful, but + * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY + * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * for more details. + */ + +#include <pthread.h> + +#include "cfg_store.h" + +#include <library.h> +#include <utils/linked_list.h> + + +typedef struct private_cfg_store_t private_cfg_store_t; + +/** + * Private data of an cfg_store_t object. + */ +struct private_cfg_store_t { + + /** + * Public part of cfg_store_t object. + */ + cfg_store_t public; + + /** + * list of registered backends + */ + linked_list_t *backends; + + /** + * mutex to lock backend list + */ + pthread_mutex_t mutex; +}; + +/** + * implements cfg_store_t.get_ike. + */ +static ike_cfg_t *get_ike_cfg(private_cfg_store_t *this, + host_t *my_host, host_t *other_host) +{ + backend_t *backend; + ike_cfg_t *config = NULL; + iterator_t *iterator = this->backends->create_iterator_locked( + this->backends, &this->mutex); + while (config == NULL && iterator->iterate(iterator, (void**)&backend)) + { + config = backend->get_ike_cfg(backend, my_host, other_host); + } + iterator->destroy(iterator); + return config; +} + +/** + * implements cfg_store_t.get_peer. + */ +static peer_cfg_t *get_peer_cfg(private_cfg_store_t *this, + identification_t *my_id, + identification_t *other_id) +{ + backend_t *backend; + peer_cfg_t *config = NULL; + iterator_t *iterator = this->backends->create_iterator_locked( + this->backends, &this->mutex); + while (config == NULL && iterator->iterate(iterator, (void**)&backend)) + { + config = backend->get_peer_cfg(backend, my_id, other_id); + } + iterator->destroy(iterator); + return config; +} + +/** + * implements cfg_store_t.get_peer_by_name. + */ +static peer_cfg_t *get_peer_cfg_by_name(private_cfg_store_t *this, char *name) +{ + backend_t *backend; + peer_cfg_t *config = NULL; + iterator_t *iterator = this->backends->create_iterator_locked( + this->backends, &this->mutex); + while (config == NULL && iterator->iterate(iterator, (void**)&backend)) + { + config = backend->get_peer_cfg_by_name(backend, name); + } + iterator->destroy(iterator); + return config; +} + +/** + * implements cfg_store_t.register_backend. + */ +static void register_backend(private_cfg_store_t *this, backend_t *backend) +{ + pthread_mutex_lock(&this->mutex); + this->backends->insert_last(this->backends, backend); + pthread_mutex_unlock(&this->mutex); +} + +/** + * implements cfg_store_t.unregister_backend. + */ +static void unregister_backend(private_cfg_store_t *this, backend_t *backend) +{ + backend_t *current; + iterator_t *iterator = this->backends->create_iterator_locked( + this->backends, &this->mutex); + while (iterator->iterate(iterator, (void**)¤t)) + { + if (backend == current) + { + iterator->remove(iterator); + break; + } + } + iterator->destroy(iterator); +} + +/** + * Implementation of cfg_store_t.destroy. + */ +static void destroy(private_cfg_store_t *this) +{ + this->backends->destroy(this->backends); + free(this); +} + +/* + * Described in header-file + */ +cfg_store_t *cfg_store_create() +{ + private_cfg_store_t *this = malloc_thing(private_cfg_store_t); + + this->public.get_ike_cfg = (ike_cfg_t*(*)(cfg_store_t*, host_t *, host_t *))get_ike_cfg; + this->public.get_peer_cfg = (peer_cfg_t*(*)(cfg_store_t*, identification_t *, identification_t *))get_peer_cfg; + this->public.get_peer_cfg_by_name = (peer_cfg_t*(*)(cfg_store_t*, char *name))get_peer_cfg_by_name; + this->public.register_backend = (void(*)(cfg_store_t*, backend_t *))register_backend; + this->public.unregister_backend = (void(*)(cfg_store_t*, backend_t *))unregister_backend; + this->public.destroy = (void(*)(cfg_store_t*))destroy; + + this->backends = linked_list_create(); + pthread_mutex_init(&this->mutex, NULL); + + return &this->public; +} diff --git a/src/charon/config/cfg_store.h b/src/charon/config/cfg_store.h new file mode 100644 index 000000000..0a0b5f3e1 --- /dev/null +++ b/src/charon/config/cfg_store.h @@ -0,0 +1,135 @@ +/** + * @file cfg_store.h + * + * @brief Interface cfg_store_t. + * + */ + +/* + * Copyright (C) 2007 Martin Willi + * Hochschule fuer Technik Rapperswil + * + * This program is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License as published by the + * Free Software Foundation; either version 2 of the License, or (at your + * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>. + * + * This program is distributed in the hope that it will be useful, but + * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY + * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * for more details. + */ + +#ifndef CFG_STORE_H_ +#define CFG_STORE_H_ + +typedef struct cfg_store_t cfg_store_t; + +#include <library.h> +#include <utils/host.h> +#include <utils/identification.h> +#include <config/ike_cfg.h> +#include <config/peer_cfg.h> +#include <config/backends/backend.h> + + +/** + * @brief A multiplexer to use multiple cfg_store backends. + * + * Charon allows the use of multiple cfg_store backends simultaneously. To + * access all this backends by a single call, this class wraps multiple + * backends behind a single object. + * Backends may be registered and unregister at runtime dynamically. + * + * +---------+ +---------+ +--------------+ | + * | | | | +--------------+ | | + * | |----->| config | +--------------+ |-+ <==|==> IPC + * | | | |------>| backends |-+ | + * | daemon |----->| | +--------------+ | + * | core | +---------+ | + * | | | + * | | +---------+ +--------------+ | + * | |<-----| | +--------------+ | | + * | | | control-| +--------------+ |-+ <==|==> IPC + * | |<-----| ler |------>| controllers |-+ | + * | | | | +--------------+ | + * +---------+ +---------+ | + * + * The daemon core only knows the simple and single cfg_store interface. + * The cfg_store wraps two kind of objects, backends and trustchains. + * If the daemon needs something, it asks the cfg_store. cfg_store + * asks all of its backends if they can fullfil the request. + * + * + * @b Constructors: + * - stroke_create() + * + * @ingroup config + */ +struct cfg_store_t { + + /** + * @brief Get an ike_config identified by two hosts. + * + * @param this calling object + * @param my_host address of own host + * @param other_host address of remote host + * @return matching ike_config, or NULL if none found + */ + ike_cfg_t *(*get_ike_cfg)(cfg_store_t *this, + host_t *my_host, host_t *other_host); + + /** + * @brief Get a peer_config identified by two IDs. + * + * @param this calling object + * @param my_id own ID + * @param other_id peers ID + * @return matching peer_config, or NULL if none found + */ + peer_cfg_t *(*get_peer_cfg)(cfg_store_t *this, identification_t *my_id, + identification_t *other_id); + + /** + * @brief Get a peer_config identified by its name. + * + * @param this calling object + * @param name name of the peer config + * @return matching peer_config, or NULL if none found + */ + peer_cfg_t *(*get_peer_cfg_by_name)(cfg_store_t *this, char *name); + + /** + * @brief Register a backend to be queried by the calls above. + * + * The backend first added is the most preferred. + * + * @param this calling object + */ + void (*register_backend) (cfg_store_t *this, backend_t *backend); + + /** + * @brief Unregister a backend. + * + * @param this calling object + */ + void (*unregister_backend) (cfg_store_t *this, backend_t *backend); + + /** + * @brief Destroys a cfg_store_t object. + * + * @param this calling object + */ + void (*destroy) (cfg_store_t *this); +}; + +/** + * @brief Create a new instance of the store. + * + * @return cfg_store instance + * + * @ingroup config + */ +cfg_store_t *cfg_store_create(void); + +#endif /*CFG_STORE_H_*/ diff --git a/src/charon/config/child_cfg.c b/src/charon/config/child_cfg.c new file mode 100644 index 000000000..2f5376753 --- /dev/null +++ b/src/charon/config/child_cfg.c @@ -0,0 +1,397 @@ +/** + * @file child_cfg.c + * + * @brief Implementation of child_cfg_t. + * + */ + +/* + * Copyright (C) 2005-2007 Martin Willi + * Copyright (C) 2005 Jan Hutter + * Hochschule fuer Technik Rapperswil + * + * This program is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License as published by the + * Free Software Foundation; either version 2 of the License, or (at your + * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>. + * + * This program is distributed in the hope that it will be useful, but + * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY + * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * for more details. + */ + + +#include "child_cfg.h" + +#include <daemon.h> + +ENUM(mode_names, MODE_TRANSPORT, MODE_BEET, + "TRANSPORT", + "TUNNEL", + "2", + "3", + "BEET", +); + +typedef struct private_child_cfg_t private_child_cfg_t; + +/** + * Private data of an child_cfg_t object + */ +struct private_child_cfg_t { + + /** + * Public part + */ + child_cfg_t public; + + /** + * Number of references hold by others to this child_cfg + */ + refcount_t refcount; + + /** + * Name of the child_cfg, used to query it + */ + char *name; + + /** + * list for all proposals + */ + linked_list_t *proposals; + + /** + * list for traffic selectors for my site + */ + linked_list_t *my_ts; + + /** + * list for traffic selectors for others site + */ + linked_list_t *other_ts; + + /** + * updown script + */ + char *updown; + + /** + * allow host access + */ + bool hostaccess; + + /** + * Mode to propose for a initiated CHILD: tunnel/transport + */ + mode_t mode; + + /** + * Time before an SA gets invalid + */ + u_int32_t lifetime; + + /** + * Time before an SA gets rekeyed + */ + u_int32_t rekeytime; + + /** + * Time, which specifies the range of a random value + * substracted from rekeytime. + */ + u_int32_t jitter; +}; + +/** + * Implementation of child_cfg_t.get_name + */ +static char *get_name(private_child_cfg_t *this) +{ + return this->name; +} + +/** + * Implementation of child_cfg_t.add_proposal + */ +static void add_proposal(private_child_cfg_t *this, proposal_t *proposal) +{ + this->proposals->insert_last(this->proposals, proposal); +} + +/** + * Implementation of child_cfg_t.get_proposals + */ +static linked_list_t* get_proposals(private_child_cfg_t *this) +{ + iterator_t *iterator; + proposal_t *current; + linked_list_t *proposals = linked_list_create(); + + iterator = this->proposals->create_iterator(this->proposals, TRUE); + while (iterator->iterate(iterator, (void**)¤t)) + { + current = current->clone(current); + proposals->insert_last(proposals, current); + } + iterator->destroy(iterator); + + return proposals; +} + +/** + * Implementation of child_cfg_t.get_name + */ +static proposal_t* select_proposal(private_child_cfg_t*this, linked_list_t *proposals) +{ + iterator_t *stored_iter, *supplied_iter; + proposal_t *stored, *supplied, *selected = NULL; + + stored_iter = this->proposals->create_iterator(this->proposals, TRUE); + supplied_iter = proposals->create_iterator(proposals, TRUE); + + /* compare all stored proposals with all supplied. Stored ones are preferred. */ + while (stored_iter->iterate(stored_iter, (void**)&stored)) + { + supplied_iter->reset(supplied_iter); + while (supplied_iter->iterate(supplied_iter, (void**)&supplied)) + { + selected = stored->select(stored, supplied); + if (selected) + { + break; + } + } + if (selected) + { + break; + } + } + stored_iter->destroy(stored_iter); + supplied_iter->destroy(supplied_iter); + return selected; +} + +/** + * Implementation of child_cfg_t.get_name + */ +static void add_traffic_selector(private_child_cfg_t *this, bool local, + traffic_selector_t *ts) +{ + if (local) + { + this->my_ts->insert_last(this->my_ts, ts); + } + else + { + this->other_ts->insert_last(this->other_ts, ts); + } +} + +/** + * Implementation of child_cfg_t.get_name + */ +static linked_list_t* get_traffic_selectors(private_child_cfg_t *this, bool local, + linked_list_t *supplied, + host_t *host) +{ + iterator_t *i1, *i2; + traffic_selector_t *ts1, *ts2, *selected; + linked_list_t *result = linked_list_create(); + + if (local) + { + i1 = this->my_ts->create_iterator(this->my_ts, TRUE); + } + else + { + i1 = this->other_ts->create_iterator(this->other_ts, FALSE); + } + + /* no list supplied, just fetch the stored traffic selectors */ + if (supplied == NULL) + { + while (i1->iterate(i1, (void**)&ts1)) + { + /* we make a copy of the TS, this allows us to update dynamic TS' */ + ts1 = ts1->clone(ts1); + if (host) + { + ts1->set_address(ts1, host); + } + result->insert_last(result, ts1); + } + i1->destroy(i1); + } + else + { + DBG2(DBG_CFG, "selecting traffic selectors"); + i2 = supplied->create_iterator(supplied, TRUE); + /* iterate over all stored selectors */ + while (i1->iterate(i1, (void**)&ts1)) + { + /* we make a copy of the TS, as we have to update dynamic TS' */ + ts1 = ts1->clone(ts1); + if (host) + { + ts1->set_address(ts1, host); + } + + i2->reset(i2); + /* iterate over all supplied traffic selectors */ + while (i2->iterate(i2, (void**)&ts2)) + { + DBG2(DBG_CFG, "stored %R <=> %R received", ts1, ts2); + selected = ts1->get_subset(ts1, ts2); + if (selected) + { + result->insert_last(result, selected); + DBG2(DBG_CFG, "found traffic selector for %s: %R", + local ? "us" : "other", selected); + } + } + ts1->destroy(ts1); + } + i1->destroy(i1); + i2->destroy(i2); + } + + /* remove any redundant traffic selectors in the list */ + i1 = result->create_iterator(result, TRUE); + i2 = result->create_iterator(result, TRUE); + while (i1->iterate(i1, (void**)&ts1)) + { + while (i2->iterate(i2, (void**)&ts2)) + { + if (ts1 != ts2) + { + if (ts2->is_contained_in(ts2, ts1)) + { + i2->remove(i2); + ts2->destroy(ts2); + i1->reset(i1); + break; + } + if (ts1->is_contained_in(ts1, ts2)) + { + i1->remove(i1); + ts1->destroy(ts1); + i2->reset(i2); + break; + } + } + } + } + i1->destroy(i1); + i2->destroy(i2); + + return result; +} + +/** + * Implementation of child_cfg_t.get_name + */ +static char* get_updown(private_child_cfg_t *this) +{ + return this->updown; +} + +/** + * Implementation of child_cfg_t.get_name + */ +static bool get_hostaccess(private_child_cfg_t *this) +{ + return this->hostaccess; +} + +/** + * Implementation of child_cfg_t.get_name + */ +static u_int32_t get_lifetime(private_child_cfg_t *this, bool rekey) +{ + if (rekey) + { + if (this->jitter == 0) + { + return this->rekeytime; + } + return this->rekeytime - (random() % this->jitter); + } + return this->lifetime; +} + +/** + * Implementation of child_cfg_t.get_name + */ +static mode_t get_mode(private_child_cfg_t *this) +{ + return this->mode; +} + +/** + * Implementation of child_cfg_t.get_name + */ +static void get_ref(private_child_cfg_t *this) +{ + ref_get(&this->refcount); +} + +/** + * Implements child_cfg_t.destroy. + */ +static void destroy(private_child_cfg_t *this) +{ + if (ref_put(&this->refcount)) + { + this->proposals->destroy_offset(this->proposals, offsetof(proposal_t, destroy)); + this->my_ts->destroy_offset(this->my_ts, offsetof(traffic_selector_t, destroy)); + this->other_ts->destroy_offset(this->other_ts, offsetof(traffic_selector_t, destroy)); + if (this->updown) + { + free(this->updown); + } + free(this->name); + free(this); + } +} + +/* + * Described in header-file + */ +child_cfg_t *child_cfg_create(char *name, u_int32_t lifetime, + u_int32_t rekeytime, u_int32_t jitter, + char *updown, bool hostaccess, mode_t mode) +{ + private_child_cfg_t *this = malloc_thing(private_child_cfg_t); + + /* public functions */ + this->public.get_name = (char* (*) (child_cfg_t*))get_name; + this->public.add_traffic_selector = (void (*)(child_cfg_t*,bool,traffic_selector_t*))add_traffic_selector; + this->public.get_traffic_selectors = (linked_list_t*(*)(child_cfg_t*,bool,linked_list_t*,host_t*))get_traffic_selectors; + this->public.add_proposal = (void (*) (child_cfg_t*,proposal_t*))add_proposal; + this->public.get_proposals = (linked_list_t* (*) (child_cfg_t*))get_proposals; + this->public.select_proposal = (proposal_t* (*) (child_cfg_t*,linked_list_t*))select_proposal; + this->public.get_updown = (char* (*) (child_cfg_t*))get_updown; + this->public.get_hostaccess = (bool (*) (child_cfg_t*))get_hostaccess; + this->public.get_mode = (mode_t (*) (child_cfg_t *))get_mode; + this->public.get_lifetime = (u_int32_t (*) (child_cfg_t *,bool))get_lifetime; + this->public.get_ref = (void (*) (child_cfg_t*))get_ref; + this->public.destroy = (void (*) (child_cfg_t*))destroy; + + /* apply init values */ + this->name = strdup(name); + this->lifetime = lifetime; + this->rekeytime = rekeytime; + this->jitter = jitter; + this->updown = updown ? strdup(updown) : NULL; + this->hostaccess = hostaccess; + this->mode = mode; + + /* initialize private members*/ + this->refcount = 1; + this->proposals = linked_list_create(); + this->my_ts = linked_list_create(); + this->other_ts = linked_list_create(); + + return &this->public; +} diff --git a/src/charon/config/child_cfg.h b/src/charon/config/child_cfg.h new file mode 100644 index 000000000..eab30122a --- /dev/null +++ b/src/charon/config/child_cfg.h @@ -0,0 +1,239 @@ +/** + * @file child_cfg.h + * + * @brief Interface of child_cfg_t. + * + */ + +/* + * Copyright (C) 2005-2007 Martin Willi + * Copyright (C) 2005 Jan Hutter + * Hochschule fuer Technik Rapperswil + * + * This program is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License as published by the + * Free Software Foundation; either version 2 of the License, or (at your + * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>. + * + * This program is distributed in the hope that it will be useful, but + * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY + * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * for more details. + */ + +#ifndef CHILD_CFG_H_ +#define CHILD_CFG_H_ + +typedef enum mode_t mode_t; +typedef struct child_cfg_t child_cfg_t; + +#include <library.h> +#include <config/proposal.h> +#include <config/traffic_selector.h> + +/** + * @brief Mode of an CHILD_SA. + * + * These are equal to those defined in XFRM, so don't change. + * + * @ingroup child_cfg + */ +enum mode_t { + /** transport mode, no inner address */ + MODE_TRANSPORT = 0, + /** tunnel mode, inner and outer addresses */ + MODE_TUNNEL = 1, + /** BEET mode, tunnel mode but fixed, bound inner addresses */ + MODE_BEET = 4, +}; + +/** + * enum names for mode_t. + */ +extern enum_name_t *mode_names; + +/** + * @brief A child_cfg_t defines the config template for a CHILD_SA. + * + * After creation, proposals and traffic selectors may be added to the config. + * A child_cfg object is referenced multiple times, and is not thread save. + * Reading from the object is save, adding things is not allowed when other + * threads may access the object. + * A reference counter handles the number of references hold to this config. + * + * @b Constructors: + * - child_cfg_create() + * + * @ingroup child_cfg + */ +struct child_cfg_t { + + /** + * @brief Get the name of the child_cfg. + * + * @param this calling object + * @return child_cfg's name + */ + char *(*get_name) (child_cfg_t *this); + + /** + * @brief Add a proposal to the list. + * + * The proposals are stored by priority, first added + * is the most prefered. + * After add, proposal is owned by child_cfg. + * + * @param this calling object + * @param proposal proposal to add + */ + void (*add_proposal) (child_cfg_t *this, proposal_t *proposal); + + /** + * @brief Get the list of proposals for the CHILD_SA. + * + * Resulting list and all of its proposals must be freed after use. + * + * @param this calling object + * @return list of proposals + */ + linked_list_t* (*get_proposals)(child_cfg_t *this); + + /** + * @brief Select a proposal from a supplied list. + * + * Returned propsal is newly created and must be destroyed after usage. + * + * @param this calling object + * @param proposals list from from wich proposals are selected + * @return selected proposal, or NULL if nothing matches + */ + proposal_t* (*select_proposal)(child_cfg_t*this, linked_list_t *proposals); + + /** + * @brief Add a traffic selector to the config. + * + * Use the "local" parameter to add it for the local or the remote side. + * After add, traffic selector is owned by child_cfg. + * + * @param this calling object + * @param local TRUE for local side, FALSE for remote + * @param ts traffic_selector to add + */ + void (*add_traffic_selector)(child_cfg_t *this, bool local, + traffic_selector_t *ts); + + /** + * @brief Get a list of traffic selectors to use for the CHILD_SA. + * + * The config contains two set of traffic selectors, one for the local + * side, one for the remote side. + * If a list with traffic selectors is supplied, these are used to narrow + * down the traffic selector list to the greatest common divisor. + * Some traffic selector may be "dymamic", meaning they are narrowed down + * to a specific address (host-to-host or virtual-IP setups). Use + * the "host" parameter to narrow such traffic selectors to that address. + * Resulted list and its traffic selectors must be destroyed after use. + * + * @param this calling object + * @param local TRUE for TS on local side, FALSE for remote + * @param supplied list with TS to select from, or NULL + * @param host address to use for narrowing "dynamic" TS', or NULL + * @return list containing the traffic selectors + */ + linked_list_t *(*get_traffic_selectors)(child_cfg_t *this, bool local, + linked_list_t *supplied, + host_t *host); + + /** + * @brief Get the updown script to run for the CHILD_SA. + * + * @param this calling object + * @return path to updown script + */ + char* (*get_updown)(child_cfg_t *this); + + /** + * @brief Should we allow access to the local host (gateway)? + * + * @param this calling object + * @return value of hostaccess flag + */ + bool (*get_hostaccess) (child_cfg_t *this); + + /** + * @brief Get the lifetime of a CHILD_SA. + * + * If "rekey" is set to TRUE, a lifetime is returned before the first + * rekeying should be started. If it is FALSE, the actual lifetime is + * returned when the CHILD_SA must be deleted. + * The rekey time automatically contains a jitter to avoid simlutaneous + * rekeying. + * + * @param this child_cfg + * @param rekey TRUE to get rekey time + * @return lifetime in seconds + */ + u_int32_t (*get_lifetime) (child_cfg_t *this, bool rekey); + + /** + * @brief Get the mode to use for the CHILD_SA. + * + * The mode is either tunnel, transport or BEET. The peer must agree + * on the method, fallback is tunnel mode. + * + * @param this child_cfg + * @return lifetime in seconds + */ + mode_t (*get_mode) (child_cfg_t *this); + + /** + * @brief Get a new reference. + * + * Get a new reference to this child_cfg by increasing + * it's internal reference counter. + * Do not call get_ref or any other function until you + * already have a reference. Otherwise the object may get + * destroyed while calling get_ref(), + * + * @param this calling object + */ + void (*get_ref) (child_cfg_t *this); + + /** + * @brief Destroys the child_cfg object. + * + * Decrements the internal reference counter and + * destroys the child_cfg when it reaches zero. + * + * @param this calling object + */ + void (*destroy) (child_cfg_t *this); +}; + +/** + * @brief Create a configuration template for CHILD_SA setup. + * + * The "name" string gets cloned. + * Lifetimes are in seconds. To prevent to peers to start rekeying at the + * same time, a jitter may be specified. Rekeying of an SA starts at + * (rekeytime - random(0, jitter)). You should specify + * lifetime > rekeytime > jitter. + * After a call to create, a reference is obtained (refcount = 1). + * + * @param name name of the child_cfg + * @param lifetime lifetime after CHILD_SA expires and gets deleted + * @param rekeytime time when rekeying should be initiated + * @param jitter range of randomization time to remove from rekeytime + * @param updown updown script to execute on up/down event + * @param hostaccess TRUE to allow access to the local host + * @param mode mode to propose for CHILD_SA, transport, tunnel or BEET + * @return child_cfg_t object + * + * @ingroup child_cfg + */ +child_cfg_t *child_cfg_create(char *name, u_int32_t lifetime, + u_int32_t rekeytime, u_int32_t jitter, + char *updown, bool hostaccess, + mode_t mode); + +#endif /* CHILD_CFG_H_ */ diff --git a/src/charon/config/connections/connection.c b/src/charon/config/connections/connection.c deleted file mode 100644 index ffe508992..000000000 --- a/src/charon/config/connections/connection.c +++ /dev/null @@ -1,404 +0,0 @@ -/** - * @file connection.c - * - * @brief Implementation of connection_t. - * - */ - -/* - * Copyright (C) 2005-2006 Martin Willi - * Copyright (C) 2005 Jan Hutter - * Hochschule fuer Technik Rapperswil - * - * This program is free software; you can redistribute it and/or modify it - * under the terms of the GNU General Public License as published by the - * Free Software Foundation; either version 2 of the License, or (at your - * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>. - * - * This program is distributed in the hope that it will be useful, but - * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY - * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License - * for more details. - */ - -#include <string.h> - -#include <config/connections/connection.h> -#include <utils/linked_list.h> - -ENUM(cert_policy_names, CERT_ALWAYS_SEND, CERT_NEVER_SEND, - "CERT_ALWAYS_SEND", - "CERT_SEND_IF_ASKED", - "CERT_NEVER_SEND" -); - -typedef struct private_connection_t private_connection_t; - -/** - * Private data of an connection_t object - */ -struct private_connection_t { - - /** - * Public part - */ - connection_t public; - - /** - * Number of references hold by others to this connection - */ - refcount_t refcount; - - /** - * Name of the connection - */ - char *name; - - /** - * Does charon handle this connection? Or can he ignore it? - */ - bool ikev2; - - /** - * should we send a certificate request? - */ - cert_policy_t certreq_policy; - - /** - * should we send a certificates? - */ - cert_policy_t cert_policy; - - /** - * ID of us - */ - identification_t *my_id; - - /** - * Host information of my host. - */ - host_t *my_host; - - /** - * Host information of other host. - */ - host_t *other_host; - - /** - * Interval to send DPD liveness checks on inactivity - */ - u_int32_t dpd_delay; - - /** - * Number of retransmission sequences to send bevore giving up - */ - u_int32_t keyingtries; - - /** - * Supported proposals - */ - linked_list_t *proposals; - - /** - * Time before an SA gets invalid - */ - u_int32_t soft_lifetime; - - /** - * Time before an SA gets rekeyed - */ - u_int32_t hard_lifetime; - - /** - * Use full reauthentication instead of rekeying - */ - bool reauth; - - /** - * Time, which specifies the range of a random value - * substracted from soft_lifetime. - */ - u_int32_t jitter; -}; - -/** - * Implementation of connection_t.get_name. - */ -static char *get_name (private_connection_t *this) -{ - return this->name; -} - -/** - * Implementation of connection_t.is_ikev2. - */ -static bool is_ikev2 (private_connection_t *this) -{ - return this->ikev2; -} - -/** - * Implementation of connection_t.get_certreq_policy. - */ -static cert_policy_t get_certreq_policy (private_connection_t *this) -{ - return this->certreq_policy; -} - -/** - * Implementation of connection_t.get_cert_policy. - */ -static cert_policy_t get_cert_policy (private_connection_t *this) -{ - return this->cert_policy; -} - -/** - * Implementation of connection_t.get_my_host. - */ -static host_t *get_my_host (private_connection_t *this) -{ - return this->my_host; -} - -/** - * Implementation of connection_t.get_other_host. - */ -static host_t *get_other_host (private_connection_t *this) -{ - return this->other_host; -} - -/** - * Implementation of connection_t.get_proposals. - */ -static linked_list_t* get_proposals(private_connection_t *this) -{ - iterator_t *iterator; - proposal_t *current; - linked_list_t *proposals = linked_list_create(); - - iterator = this->proposals->create_iterator(this->proposals, TRUE); - while (iterator->iterate(iterator, (void**)¤t)) - { - current = current->clone(current); - proposals->insert_last(proposals, (void*)current); - } - iterator->destroy(iterator); - - return proposals; -} - -/** - * Implementation of connection_t.select_proposal. - */ -static proposal_t *select_proposal(private_connection_t *this, linked_list_t *proposals) -{ - iterator_t *stored_iter, *supplied_iter; - proposal_t *stored, *supplied, *selected; - - stored_iter = this->proposals->create_iterator(this->proposals, TRUE); - supplied_iter = proposals->create_iterator(proposals, TRUE); - - /* compare all stored proposals with all supplied. Stored ones are preferred. */ - while (stored_iter->iterate(stored_iter, (void**)&stored)) - { - supplied_iter->reset(supplied_iter); - - while (supplied_iter->iterate(supplied_iter, (void**)&supplied)) - { - selected = stored->select(stored, supplied); - if (selected) - { - /* they match, return */ - stored_iter->destroy(stored_iter); - supplied_iter->destroy(supplied_iter); - return selected; - } - } - } - /* no proposal match :-(, will result in a NO_PROPOSAL_CHOSEN... */ - stored_iter->destroy(stored_iter); - supplied_iter->destroy(supplied_iter); - - return NULL; -} - -/** - * Implementation of connection_t.add_proposal. - */ -static void add_proposal(private_connection_t *this, proposal_t *proposal) -{ - this->proposals->insert_last(this->proposals, proposal); -} - -/** - * Implementation of connection_t.get_dpd_delay. - */ -static u_int32_t get_dpd_delay(private_connection_t *this) -{ - return this->dpd_delay; -} - -/** - * Implementation of connection_t.get_keyingtries. - */ -static u_int32_t get_keyingtries(private_connection_t *this) -{ - return this->keyingtries; -} - -/** - * Implementation of connection_t.get_dh_group. - */ -static diffie_hellman_group_t get_dh_group(private_connection_t *this) -{ - iterator_t *iterator; - proposal_t *proposal; - algorithm_t *algo; - diffie_hellman_group_t dh_group = MODP_NONE; - - iterator = this->proposals->create_iterator(this->proposals, TRUE); - while (iterator->iterate(iterator, (void**)&proposal)) - { - if (proposal->get_algorithm(proposal, DIFFIE_HELLMAN_GROUP, &algo)) - { - dh_group = algo->algorithm; - break; - } - } - iterator->destroy(iterator); - return dh_group; -} - -/** - * Implementation of connection_t.check_dh_group. - */ -static bool check_dh_group(private_connection_t *this, diffie_hellman_group_t dh_group) -{ - iterator_t *prop_iter, *alg_iter; - proposal_t *proposal; - algorithm_t *algo; - - prop_iter = this->proposals->create_iterator(this->proposals, TRUE); - while (prop_iter->iterate(prop_iter, (void**)&proposal)) - { - alg_iter = proposal->create_algorithm_iterator(proposal, DIFFIE_HELLMAN_GROUP); - while (alg_iter->iterate(alg_iter, (void**)&algo)) - { - if (algo->algorithm == dh_group) - { - prop_iter->destroy(prop_iter); - alg_iter->destroy(alg_iter); - return TRUE; - } - } - alg_iter->destroy(alg_iter); - } - prop_iter->destroy(prop_iter); - return FALSE; -} -/** - * Implementation of connection_t.get_soft_lifetime - */ -static u_int32_t get_soft_lifetime(private_connection_t *this) -{ - if (this->jitter == 0) - { - return this->soft_lifetime ; - } - return this->soft_lifetime - (random() % this->jitter); -} - -/** - * Implementation of connection_t.get_hard_lifetime. - */ -static u_int32_t get_hard_lifetime(private_connection_t *this) -{ - return this->hard_lifetime; -} - -/** - * Implementation of connection_t.get_reauth. - */ -static bool get_reauth(private_connection_t *this) -{ - return this->reauth; -} - -/** - * Implementation of connection_t.get_ref. - */ -static void get_ref(private_connection_t *this) -{ - ref_get(&this->refcount); -} - -/** - * Implementation of connection_t.destroy. - */ -static void destroy(private_connection_t *this) -{ - if (ref_put(&this->refcount)) - { - this->proposals->destroy_offset(this->proposals, offsetof(proposal_t, destroy)); - this->my_host->destroy(this->my_host); - this->other_host->destroy(this->other_host); - free(this->name); - free(this); - } -} - -/** - * Described in header. - */ -connection_t * connection_create(char *name, bool ikev2, - cert_policy_t cert_policy, - cert_policy_t certreq_policy, - host_t *my_host, host_t *other_host, - u_int32_t dpd_delay, bool reauth, - u_int32_t keyingtries, - u_int32_t hard_lifetime, - u_int32_t soft_lifetime, u_int32_t jitter) -{ - private_connection_t *this = malloc_thing(private_connection_t); - - /* public functions */ - this->public.get_name = (char*(*)(connection_t*))get_name; - this->public.is_ikev2 = (bool(*)(connection_t*))is_ikev2; - this->public.get_cert_policy = (cert_policy_t(*)(connection_t*))get_cert_policy; - this->public.get_certreq_policy = (cert_policy_t(*)(connection_t*))get_certreq_policy; - this->public.get_my_host = (host_t*(*)(connection_t*))get_my_host; - this->public.get_other_host = (host_t*(*)(connection_t*))get_other_host; - this->public.get_proposals = (linked_list_t*(*)(connection_t*))get_proposals; - this->public.select_proposal = (proposal_t*(*)(connection_t*,linked_list_t*))select_proposal; - this->public.add_proposal = (void(*)(connection_t*, proposal_t*)) add_proposal; - this->public.get_dpd_delay = (u_int32_t(*)(connection_t*)) get_dpd_delay; - this->public.get_reauth = (bool(*)(connection_t*)) get_reauth; - this->public.get_keyingtries = (u_int32_t(*)(connection_t*)) get_keyingtries; - this->public.get_dh_group = (diffie_hellman_group_t(*)(connection_t*)) get_dh_group; - this->public.check_dh_group = (bool(*)(connection_t*,diffie_hellman_group_t)) check_dh_group; - this->public.get_soft_lifetime = (u_int32_t (*) (connection_t *))get_soft_lifetime; - this->public.get_hard_lifetime = (u_int32_t (*) (connection_t *))get_hard_lifetime; - this->public.get_ref = (void(*)(connection_t*))get_ref; - this->public.destroy = (void(*)(connection_t*))destroy; - - /* private variables */ - this->refcount = 1; - this->name = strdup(name); - this->ikev2 = ikev2; - this->cert_policy = cert_policy; - this->certreq_policy = certreq_policy; - this->my_host = my_host; - this->other_host = other_host; - this->dpd_delay = dpd_delay; - this->reauth = reauth; - this->keyingtries = keyingtries; - this->hard_lifetime = hard_lifetime; - this->soft_lifetime = soft_lifetime; - this->jitter = jitter; - - this->proposals = linked_list_create(); - - return &this->public; -} diff --git a/src/charon/config/connections/connection.h b/src/charon/config/connections/connection.h deleted file mode 100644 index d0788876f..000000000 --- a/src/charon/config/connections/connection.h +++ /dev/null @@ -1,292 +0,0 @@ -/** - * @file connection.h - * - * @brief Interface of connection_t. - * - */ - -/* - * Copyright (C) 2005-2006 Martin Willi - * Copyright (C) 2005 Jan Hutter - * Hochschule fuer Technik Rapperswil - * - * This program is free software; you can redistribute it and/or modify it - * under the terms of the GNU General Public License as published by the - * Free Software Foundation; either version 2 of the License, or (at your - * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>. - * - * This program is distributed in the hope that it will be useful, but - * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY - * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License - * for more details. - */ - -#ifndef CONNECTION_H_ -#define CONNECTION_H_ - -typedef enum cert_policy_t cert_policy_t; -typedef struct connection_t connection_t; - -#include <library.h> -#include <utils/host.h> -#include <utils/linked_list.h> -#include <utils/identification.h> -#include <config/proposal.h> -#include <crypto/diffie_hellman.h> - - -/** - * Certificate sending policy. This is also used for certificate - * requests when using this definition for the other peer. If - * it is CERT_NEVER_SEND, a certreq is omitted, otherwise its - * included. - * - * @ingroup config - * - * @warning These definitions must be the same as in pluto/starter, - * as they are sent over the stroke socket. - */ -enum cert_policy_t { - /** always send certificates, even when not requested */ - CERT_ALWAYS_SEND = 0, - /** send certificate upon cert request */ - CERT_SEND_IF_ASKED = 1, - /** never send a certificate, even when requested */ - CERT_NEVER_SEND = 2, -}; - -/** - * enum strings for cert_policy_t - * - * @ingroup config - */ -extern enum_name_t *cert_policy_names; - -/** - * @brief A connection_t defines the rules to set up an IKE_SA. - * - * @b Constructors: - * - connection_create() - * - * @ingroup config - */ -struct connection_t { - - /** - * @brief Get my address as host_t object. - * - * Object is NOT getting cloned. - * - * @param this calling object - * @return host information as host_t object - */ - host_t *(*get_my_host) (connection_t *this); - - /** - * @brief Get others address as host_t object. - * - * Object is NOT getting cloned. - * - * @param this calling object - * @return host information as host_t object - */ - host_t *(*get_other_host) (connection_t *this); - - /** - * @brief Returns a list of all supported proposals. - * - * Returned list and its proposals must be destroyed after usage. - * - * @param this calling object - * @return list containing all the proposals - */ - linked_list_t *(*get_proposals) (connection_t *this); - - /** - * @brief Adds a proposal to the list. - * - * The first added proposal has the highest priority, the last - * added the lowest. - * - * @param this calling object - * @param proposal proposal to add - */ - void (*add_proposal) (connection_t *this, proposal_t *proposal); - - /** - * @brief Select a proposed from suggested proposals. - * - * Returned proposal must be destroyed after usage. - * - * @param this calling object - * @param proposals list of proposals to select from - * @return selected proposal, or NULL if none matches. - */ - proposal_t *(*select_proposal) (connection_t *this, linked_list_t *proposals); - - /** - * @brief Get the DPD check interval. - * - * @param this calling object - * @return dpd_delay in seconds - */ - u_int32_t (*get_dpd_delay) (connection_t *this); - - /** - * @brief Should a full reauthentication be done instead of rekeying? - * - * @param this calling object - * @return TRUE to use full reauthentication - */ - bool (*get_reauth) (connection_t *this); - - /** - * @brief Get the max number of retransmission sequences. - * - * @param this calling object - * @return max number of retransmission sequences - */ - u_int32_t (*get_keyingtries) (connection_t *this); - - /** - * @brief Get the connection name. - * - * Name must not be freed, since it points to - * internal data. - * - * @param this calling object - * @return name of the connection - */ - char* (*get_name) (connection_t *this); - - /** - * @brief Check if the connection is marked as an IKEv2 connection. - * - * Since all connections (IKEv1+2) are loaded, but charon handles - * only those marked with IKEv2, this flag can tell us if we must - * ignore a connection on initiaton. Then pluto will do it for us. - * - * @param this calling object - * @return - TRUE, if this is an IKEv2 connection - */ - bool (*is_ikev2) (connection_t *this); - - /** - * @brief Should be sent a certificate request for this connection? - * - * A certificate request contains serials of our trusted CA certificates. - * This flag says if such a request is sent on connection setup to - * the peer. It should be omitted when CERT_SEND_NEVER, sended otherwise. - * - * @param this calling object - * @return certificate request sending policy - */ - cert_policy_t (*get_certreq_policy) (connection_t *this); - - /** - * @brief Should be sent a certificate for this connection? - * - * Return the policy used to send the certificate. - * - * @param this calling object - * @return certificate sending policy - */ - cert_policy_t (*get_cert_policy) (connection_t *this); - - /** - * @brief Get the DH group to use for connection initialization. - * - * @param this calling object - * @return dh group to use for initialization - */ - diffie_hellman_group_t (*get_dh_group) (connection_t *this); - - /** - * @brief Check if a suggested dh group is acceptable. - * - * If we guess a wrong DH group for IKE_SA_INIT, the other - * peer will send us a offer. But is this acceptable for us? - * - * @param this calling object - * @return TRUE if group acceptable - */ - bool (*check_dh_group) (connection_t *this, diffie_hellman_group_t dh_group); - - /** - * @brief Get the lifetime of a connection, before IKE_SA rekeying starts. - * - * A call to this function automatically adds a jitter to - * avoid simultanous rekeying. - * - * @param this calling object - * @return lifetime in seconds - */ - u_int32_t (*get_soft_lifetime) (connection_t *this); - - /** - * @brief Get the lifetime of a connection, before IKE_SA gets deleted. - * - * @param this calling object - * @return lifetime in seconds - */ - u_int32_t (*get_hard_lifetime) (connection_t *this); - - /** - * @brief Get a new reference to this connection. - * - * Get a new reference to this connection by increasing - * it's internal reference counter. - * Do not call get_ref or any other function until you - * already have a reference. Otherwise the object may get - * destroyed while calling get_ref(), - * - * @param this calling object - */ - void (*get_ref) (connection_t *this); - - /** - * @brief Destroys a connection_t object. - * - * Decrements the internal reference counter and - * destroys the connection when it reaches zero. - * - * @param this calling object - */ - void (*destroy) (connection_t *this); -}; - -/** - * @brief Creates a connection_t object. - * - * Supplied hosts become owned by connection, so - * do not modify or destroy them after a call to - * connection_create(). Name gets cloned internally. - * The retrasmit sequence number says how fast we give up when the peer - * does not respond. A high value may bridge-over temporary connection - * problems, a small value can detect dead peers faster. - * - * @param name connection identifier - * @param ikev2 TRUE if this is an IKEv2 connection - * @param cert_policy certificate send policy - * @param cert_req_policy certificate request send policy - * @param my_host host_t representing local address - * @param other_host host_t representing remote address - * @param dpd_delay interval of DPD liveness checks - * @param reauth use full reauthentication instead of rekeying - * @param keyingtries number of retransmit sequences to use - * @param hard_lifetime lifetime before deleting an IKE_SA - * @param soft_lifetime lifetime before rekeying an IKE_SA - * @param jitter range of randomization time - * @return connection_t object. - * - * @ingroup config - */ -connection_t * connection_create(char *name, bool ikev2, - cert_policy_t cert_pol, cert_policy_t req_pol, - host_t *my_host, host_t *other_host, - u_int32_t dpd_delay, bool reauth, - u_int32_t keyingtries, - u_int32_t hard_lifetime, u_int32_t soft_lifetime, - u_int32_t jitter); - -#endif /* CONNECTION_H_ */ diff --git a/src/charon/config/connections/connection_store.h b/src/charon/config/connections/connection_store.h deleted file mode 100755 index 70f209d3b..000000000 --- a/src/charon/config/connections/connection_store.h +++ /dev/null @@ -1,118 +0,0 @@ -/** - * @file connection_store.h - * - * @brief Interface connection_store_t. - * - */ - -/* - * Copyright (C) 2006 Martin Willi - * Hochschule fuer Technik Rapperswil - * - * This program is free software; you can redistribute it and/or modify it - * under the terms of the GNU General Public License as published by the - * Free Software Foundation; either version 2 of the License, or (at your - * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>. - * - * This program is distributed in the hope that it will be useful, but - * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY - * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License - * for more details. - */ - -#ifndef CONNECTION_STORE_H_ -#define CONNECTION_STORE_H_ - -typedef struct connection_store_t connection_store_t; - -#include <library.h> -#include <config/connections/connection.h> -#include <utils/iterator.h> - -/** - * @brief The interface for a store of connection_t's. - * - * @b Constructors: - * - stroke_create() - * - * @ingroup config - */ -struct connection_store_t { - - /** - * @brief Returns a connection definition identified by two hosts. - * - * This call is usefull to get a connection identified by addresses. - * It may be used after kernel request for traffic protection. - * The returned connection gets created/cloned and therefore must - * be destroyed after usage. - * - * @param this calling object - * @param my_id own address of connection - * @param other_id others address of connection - * @return - * - connection_t, if found - * - NULL otherwise - */ - connection_t *(*get_connection_by_hosts)(connection_store_t *this, - host_t *my_host, host_t *other_host); - - /** - * @brief Returns a connection identified by its name. - * - * This call is usefull to get a connection identified its - * name, as on an connection setup. - * - * @param this calling object - * @param name name of the connection to get - * @return - * - connection_t, if found - * - NULL otherwise - */ - connection_t *(*get_connection_by_name) (connection_store_t *this, char *name); - - /** - * @brief Add a connection to the store. - * - * After a successful call, the connection is owned by the store and may - * not be manipulated nor destroyed. - * - * @param this calling object - * @param connection connection to add - * @return - * - SUCCESS, or - * - FAILED - */ - status_t (*add_connection) (connection_store_t *this, connection_t *connection); - - /** - * @brief Delete a connection from the store. - * - * Remove a connection from the connection store, identified - * by the connections name. - * - * @param this calling object - * @param name name of the connection to delete - * @return - * - SUCCESS, or - * - NOT_FOUND - */ - status_t (*delete_connection) (connection_store_t *this, char *name); - - /** - * @brief Get an iterator for the stored connections. - * - * @param this calling object - * @return iterator over all stored connections - */ - iterator_t* (*create_iterator) (connection_store_t *this); - - /** - * @brief Destroys a connection_store_t object. - * - * @param this calling object - */ - void (*destroy) (connection_store_t *this); -}; - -#endif /* CONNECTION_STORE_H_ */ diff --git a/src/charon/config/connections/local_connection_store.c b/src/charon/config/connections/local_connection_store.c deleted file mode 100644 index df4ec230a..000000000 --- a/src/charon/config/connections/local_connection_store.c +++ /dev/null @@ -1,237 +0,0 @@ -/** - * @file local_connection_store.c - * - * @brief Implementation of local_connection_store_t. - * - */ - -/* - * Copyright (C) 2006 Martin Willi - * Hochschule fuer Technik Rapperswil - * - * This program is free software; you can redistribute it and/or modify it - * under the terms of the GNU General Public License as published by the - * Free Software Foundation; either version 2 of the License, or (at your - * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>. - * - * This program is distributed in the hope that it will be useful, but - * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY - * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License - * for more details. - */ - -#include <string.h> - -#include "local_connection_store.h" - -#include <daemon.h> -#include <utils/linked_list.h> - - -typedef struct private_local_connection_store_t private_local_connection_store_t; - -/** - * Private data of an local_connection_store_t object - */ -struct private_local_connection_store_t { - - /** - * Public part - */ - local_connection_store_t public; - - /** - * stored connection - */ - linked_list_t *connections; - - /** - * Mutex to exclusivly access connection list - */ - pthread_mutex_t mutex; -}; - - -/** - * Implementation of connection_store_t.get_connection_by_hosts. - */ -static connection_t *get_connection_by_hosts(private_local_connection_store_t *this, host_t *my_host, host_t *other_host) -{ - typedef enum { - PRIO_UNDEFINED= 0x00, - PRIO_ADDR_ANY= 0x01, - PRIO_ADDR_MATCH= 0x02 - } prio_t; - - prio_t best_prio = PRIO_UNDEFINED; - - iterator_t *iterator; - connection_t *candidate; - connection_t *found = NULL; - - DBG2(DBG_CFG, "looking for connection for host pair %H...%H", - my_host, other_host); - - pthread_mutex_lock(&(this->mutex)); - iterator = this->connections->create_iterator(this->connections, TRUE); - /* determine closest matching connection */ - while (iterator->iterate(iterator, (void**)&candidate)) - { - host_t *candidate_my_host; - host_t *candidate_other_host; - - candidate_my_host = candidate->get_my_host(candidate); - candidate_other_host = candidate->get_other_host(candidate); - - /* my_host addresses must match*/ - if (my_host->ip_equals(my_host, candidate_my_host)) - { - prio_t prio = PRIO_UNDEFINED; - - /* exact match of peer host address or wildcard address? */ - if (other_host->ip_equals(other_host, candidate_other_host)) - { - prio |= PRIO_ADDR_MATCH; - } - else if (candidate_other_host->is_anyaddr(candidate_other_host)) - { - prio |= PRIO_ADDR_ANY; - } - - DBG2(DBG_CFG, "candidate connection \"%s\": %H...%H (prio=%d)", - candidate->get_name(candidate), - candidate_my_host, candidate_other_host, prio); - - if (prio > best_prio) - { - found = candidate; - best_prio = prio; - } - } - } - iterator->destroy(iterator); - - if (found) - { - DBG2(DBG_CFG, "found matching connection \"%s\": %H...%H (prio=%d)", - found->get_name(found), found->get_my_host(found), - found->get_other_host(found), best_prio); - - /* give out a new reference to it */ - found->get_ref(found); - } - pthread_mutex_unlock(&(this->mutex)); - return found; -} - -/** - * Implementation of connection_store_t.get_connection_by_name. - */ -static connection_t *get_connection_by_name(private_local_connection_store_t *this, char *name) -{ - iterator_t *iterator; - connection_t *current, *found = NULL; - - pthread_mutex_lock(&(this->mutex)); - iterator = this->connections->create_iterator(this->connections, TRUE); - while (iterator->iterate(iterator, (void**)¤t)) - { - if (strcmp(name, current->get_name(current)) == 0) - { - found = current; - break; - } - } - iterator->destroy(iterator); - pthread_mutex_unlock(&(this->mutex)); - - if (found) - { - /* get a new reference for it */ - found->get_ref(found); - } - return found; -} - -/** - * Implementation of connection_store_t.delete_connection. - */ -static status_t delete_connection(private_local_connection_store_t *this, char *name) -{ - iterator_t *iterator; - connection_t *current; - bool found = FALSE; - - pthread_mutex_lock(&(this->mutex)); - iterator = this->connections->create_iterator(this->connections, TRUE); - while (iterator->iterate(iterator, (void **)¤t)) - { - if (strcmp(current->get_name(current), name) == 0) - { - /* remove connection from list, and destroy it */ - iterator->remove(iterator); - current->destroy(current); - found = TRUE; - break; - } - } - iterator->destroy(iterator); - pthread_mutex_unlock(&(this->mutex)); - if (found) - { - return SUCCESS; - } - return NOT_FOUND; -} - -/** - * Implementation of connection_store_t.add_connection. - */ -static status_t add_connection(private_local_connection_store_t *this, connection_t *connection) -{ - pthread_mutex_lock(&(this->mutex)); - this->connections->insert_last(this->connections, connection); - pthread_mutex_unlock(&(this->mutex)); - return SUCCESS; -} - -/** - * Implementation of connection_store_t.create_iterator. - */ -static iterator_t* create_iterator(private_local_connection_store_t *this) -{ - return this->connections->create_iterator_locked(this->connections, - &this->mutex); -} - -/** - * Implementation of connection_store_t.destroy. - */ -static void destroy (private_local_connection_store_t *this) -{ - pthread_mutex_lock(&(this->mutex)); - this->connections->destroy_offset(this->connections, offsetof(connection_t, destroy)); - pthread_mutex_unlock(&(this->mutex)); - free(this); -} - -/** - * Described in header. - */ -local_connection_store_t * local_connection_store_create(void) -{ - private_local_connection_store_t *this = malloc_thing(private_local_connection_store_t); - - this->public.connection_store.get_connection_by_hosts = (connection_t*(*)(connection_store_t*,host_t*,host_t*))get_connection_by_hosts; - this->public.connection_store.get_connection_by_name = (connection_t*(*)(connection_store_t*,char*))get_connection_by_name; - this->public.connection_store.delete_connection = (status_t(*)(connection_store_t*,char*))delete_connection; - this->public.connection_store.add_connection = (status_t(*)(connection_store_t*,connection_t*))add_connection; - this->public.connection_store.create_iterator = (iterator_t*(*)(connection_store_t*))create_iterator; - this->public.connection_store.destroy = (void(*)(connection_store_t*))destroy; - - /* private variables */ - this->connections = linked_list_create(); - pthread_mutex_init(&(this->mutex), NULL); - - return (&this->public); -} diff --git a/src/charon/config/connections/local_connection_store.h b/src/charon/config/connections/local_connection_store.h deleted file mode 100644 index e78ed809a..000000000 --- a/src/charon/config/connections/local_connection_store.h +++ /dev/null @@ -1,62 +0,0 @@ -/** - * @file local_connection_store.h - * - * @brief Interface of local_connection_store_t. - * - */ - -/* - * Copyright (C) 2006 Martin Willi - * Hochschule fuer Technik Rapperswil - * - * This program is free software; you can redistribute it and/or modify it - * under the terms of the GNU General Public License as published by the - * Free Software Foundation; either version 2 of the License, or (at your - * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>. - * - * This program is distributed in the hope that it will be useful, but - * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY - * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License - * for more details. - */ - -#ifndef LOCAL_CONNECTION_H_ -#define LOCAL_CONNECTION_H_ - -typedef struct local_connection_store_t local_connection_store_t; - -#include <library.h> -#include <config/connections/connection_store.h> - -/** - * @brief A connection_store_t implementation using a simple connection list. - * - * The local_connection_store_t class implements the connection_store_t interface - * as simple as possible. connection_t's are stored in an in-memory list. - * - * @b Constructors: - * - local_connection_store_create() - * - * @todo Make thread-save first - * @todo Add remove_connection method - * - * @ingroup config - */ -struct local_connection_store_t { - - /** - * Implements connection_store_t interface - */ - connection_store_t connection_store; -}; - -/** - * @brief Creates a local_connection_store_t instance. - * - * @return connection store instance. - * - * @ingroup config - */ -local_connection_store_t * local_connection_store_create(void); - -#endif /* LOCAL_CONNECTION_H_ */ diff --git a/src/charon/config/ike_cfg.c b/src/charon/config/ike_cfg.c new file mode 100644 index 000000000..61e62115d --- /dev/null +++ b/src/charon/config/ike_cfg.c @@ -0,0 +1,259 @@ +/** + * @file ike_cfg.c + * + * @brief Implementation of ike_cfg_t. + * + */ + +/* + * Copyright (C) 2005-2007 Martin Willi + * Copyright (C) 2005 Jan Hutter + * Hochschule fuer Technik Rapperswil + * + * This program is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License as published by the + * Free Software Foundation; either version 2 of the License, or (at your + * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>. + * + * This program is distributed in the hope that it will be useful, but + * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY + * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * for more details. + */ + +#include "ike_cfg.h" + +#include <string.h> + + +typedef struct private_ike_cfg_t private_ike_cfg_t; + +/** + * Private data of an ike_cfg_t object + */ +struct private_ike_cfg_t { + + /** + * Public part + */ + ike_cfg_t public; + + /** + * Number of references hold by others to this ike_cfg + */ + refcount_t refcount; + + /** + * Address of local host + */ + host_t *my_host; + + /** + * Address of remote host + */ + host_t *other_host; + + /** + * should we send a certificate request? + */ + bool certreq; + + /** + * List of proposals to use + */ + linked_list_t *proposals; +}; + +/** + * Implementation of ike_cfg_t.certreq. + */ +static bool send_certreq(private_ike_cfg_t *this) +{ + return this->certreq; +} + +/** + * Implementation of ike_cfg_t.get_my_host. + */ +static host_t *get_my_host (private_ike_cfg_t *this) +{ + return this->my_host; +} + +/** + * Implementation of ike_cfg_t.get_other_host. + */ +static host_t *get_other_host (private_ike_cfg_t *this) +{ + return this->other_host; +} + +/** + * Implementation of ike_cfg_t.add_proposal. + */ +static void add_proposal(private_ike_cfg_t *this, proposal_t *proposal) +{ + this->proposals->insert_last(this->proposals, proposal); +} + +/** + * Implementation of ike_cfg_t.get_proposals. + */ +static linked_list_t* get_proposals(private_ike_cfg_t *this) +{ + iterator_t *iterator; + proposal_t *current; + linked_list_t *proposals = linked_list_create(); + + iterator = this->proposals->create_iterator(this->proposals, TRUE); + while (iterator->iterate(iterator, (void**)¤t)) + { + current = current->clone(current); + proposals->insert_last(proposals, (void*)current); + } + iterator->destroy(iterator); + + return proposals; +} + +/** + * Implementation of ike_cfg_t.select_proposal. + */ +static proposal_t *select_proposal(private_ike_cfg_t *this, + linked_list_t *proposals) +{ + iterator_t *stored_iter, *supplied_iter; + proposal_t *stored, *supplied, *selected; + + stored_iter = this->proposals->create_iterator(this->proposals, TRUE); + supplied_iter = proposals->create_iterator(proposals, TRUE); + + /* compare all stored proposals with all supplied. Stored ones are preferred.*/ + while (stored_iter->iterate(stored_iter, (void**)&stored)) + { + supplied_iter->reset(supplied_iter); + + while (supplied_iter->iterate(supplied_iter, (void**)&supplied)) + { + selected = stored->select(stored, supplied); + if (selected) + { + /* they match, return */ + stored_iter->destroy(stored_iter); + supplied_iter->destroy(supplied_iter); + return selected; + } + } + } + /* no proposal match :-(, will result in a NO_PROPOSAL_CHOSEN... */ + stored_iter->destroy(stored_iter); + supplied_iter->destroy(supplied_iter); + + return NULL; +} + +/** + * Implementation of ike_cfg_t.get_dh_group. + */ +static diffie_hellman_group_t get_dh_group(private_ike_cfg_t *this) +{ + iterator_t *iterator; + proposal_t *proposal; + algorithm_t *algo; + diffie_hellman_group_t dh_group = MODP_NONE; + + iterator = this->proposals->create_iterator(this->proposals, TRUE); + while (iterator->iterate(iterator, (void**)&proposal)) + { + if (proposal->get_algorithm(proposal, DIFFIE_HELLMAN_GROUP, &algo)) + { + dh_group = algo->algorithm; + break; + } + } + iterator->destroy(iterator); + return dh_group; +} + +/** + * Implementation of ike_cfg_t.check_dh_group. + */ +static bool check_dh_group(private_ike_cfg_t *this, + diffie_hellman_group_t dh_group) +{ + iterator_t *prop_iter, *alg_iter; + proposal_t *proposal; + algorithm_t *algo; + + prop_iter = this->proposals->create_iterator(this->proposals, TRUE); + while (prop_iter->iterate(prop_iter, (void**)&proposal)) + { + alg_iter = proposal->create_algorithm_iterator(proposal, + DIFFIE_HELLMAN_GROUP); + while (alg_iter->iterate(alg_iter, (void**)&algo)) + { + if (algo->algorithm == dh_group) + { + prop_iter->destroy(prop_iter); + alg_iter->destroy(alg_iter); + return TRUE; + } + } + alg_iter->destroy(alg_iter); + } + prop_iter->destroy(prop_iter); + return FALSE; +} + +/** + * Implementation of ike_cfg_t.get_ref. + */ +static void get_ref(private_ike_cfg_t *this) +{ + ref_get(&this->refcount); +} + +/** + * Implementation of ike_cfg_t.destroy. + */ +static void destroy(private_ike_cfg_t *this) +{ + if (ref_put(&this->refcount)) + { + this->proposals->destroy_offset(this->proposals, + offsetof(proposal_t, destroy)); + this->my_host->destroy(this->my_host); + this->other_host->destroy(this->other_host); + free(this); + } +} + +/** + * Described in header. + */ +ike_cfg_t *ike_cfg_create(bool certreq, host_t *my_host, host_t *other_host) +{ + private_ike_cfg_t *this = malloc_thing(private_ike_cfg_t); + + /* public functions */ + this->public.send_certreq = (bool(*)(ike_cfg_t*))send_certreq; + this->public.get_my_host = (host_t*(*)(ike_cfg_t*))get_my_host; + this->public.get_other_host = (host_t*(*)(ike_cfg_t*))get_other_host; + this->public.add_proposal = (void(*)(ike_cfg_t*, proposal_t*)) add_proposal; + this->public.get_proposals = (linked_list_t*(*)(ike_cfg_t*))get_proposals; + this->public.select_proposal = (proposal_t*(*)(ike_cfg_t*,linked_list_t*))select_proposal; + this->public.get_dh_group = (diffie_hellman_group_t(*)(ike_cfg_t*)) get_dh_group; + this->public.check_dh_group = (bool(*)(ike_cfg_t*,diffie_hellman_group_t)) check_dh_group; + this->public.get_ref = (void(*)(ike_cfg_t*))get_ref; + this->public.destroy = (void(*)(ike_cfg_t*))destroy; + + /* private variables */ + this->refcount = 1; + this->certreq = certreq; + this->my_host = my_host; + this->other_host = other_host; + + this->proposals = linked_list_create(); + + return &this->public; +} diff --git a/src/charon/config/ike_cfg.h b/src/charon/config/ike_cfg.h new file mode 100644 index 000000000..f8f5a3500 --- /dev/null +++ b/src/charon/config/ike_cfg.h @@ -0,0 +1,160 @@ +/** + * @file ike_cfg.h + * + * @brief Interface of ike_cfg_t. + * + */ + +/* + * Copyright (C) 2005-2007 Martin Willi + * Copyright (C) 2005 Jan Hutter + * Hochschule fuer Technik Rapperswil + * + * This program is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License as published by the + * Free Software Foundation; either version 2 of the License, or (at your + * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>. + * + * This program is distributed in the hope that it will be useful, but + * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY + * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * for more details. + */ + +#ifndef IKE_CFG_H_ +#define IKE_CFG_H_ + +typedef struct ike_cfg_t ike_cfg_t; + +#include <library.h> +#include <utils/host.h> +#include <utils/linked_list.h> +#include <utils/identification.h> +#include <config/proposal.h> +#include <crypto/diffie_hellman.h> + +/** + * @brief An ike_cfg_t defines the rules to set up an IKE_SA. + * + * @b Constructors: + * - ike_cfg_create() + * + * @ingroup ike_cfg + */ +struct ike_cfg_t { + + /** + * @brief Get own address. + * + * @param this calling object + * @return host information as host_t object + */ + host_t* (*get_my_host) (ike_cfg_t *this); + + /** + * @brief Get peers address. + * + * @param this calling object + * @return host information as host_t object + */ + host_t* (*get_other_host) (ike_cfg_t *this); + + /** + * @brief Adds a proposal to the list. + * + * The first added proposal has the highest priority, the last + * added the lowest. + * + * @param this calling object + * @param proposal proposal to add + */ + void (*add_proposal) (ike_cfg_t *this, proposal_t *proposal); + + /** + * @brief Returns a list of all supported proposals. + * + * Returned list and its proposals must be destroyed after use. + * + * @param this calling object + * @return list containing all the proposals + */ + linked_list_t* (*get_proposals) (ike_cfg_t *this); + + /** + * @brief Select a proposed from suggested proposals. + * + * Returned proposal must be destroyed after use. + * + * @param this calling object + * @param proposals list of proposals to select from + * @return selected proposal, or NULL if none matches. + */ + proposal_t *(*select_proposal) (ike_cfg_t *this, linked_list_t *proposals); + + /** + * @brief Should we send a certificate request in IKE_SA_INIT? + * + * @param this calling object + * @return certificate request sending policy + */ + bool (*send_certreq) (ike_cfg_t *this); + + /** + * @brief Get the DH group to use for IKE_SA setup. + * + * @param this calling object + * @return dh group to use for initialization + */ + diffie_hellman_group_t (*get_dh_group)(ike_cfg_t *this); + + /** + * @brief Check if a suggested DH group is acceptable. + * + * If we guess a wrong DH group for IKE_SA_INIT, the other + * peer will send us a offer. But is this acceptable for us? + * + * @param this calling object + * @return TRUE if group acceptable + */ + bool (*check_dh_group) (ike_cfg_t *this, diffie_hellman_group_t dh_group); + + /** + * @brief Get a new reference to this ike_cfg. + * + * Get a new reference to this ike_cfg by increasing + * it's internal reference counter. + * Do not call get_ref or any other function until you + * already have a reference. Otherwise the object may get + * destroyed while calling get_ref(), + * + * @param this calling object + */ + void (*get_ref) (ike_cfg_t *this); + + /** + * @brief Destroys a ike_cfg_t object. + * + * Decrements the internal reference counter and + * destroys the ike_cfg when it reaches zero. + * + * @param this calling object + */ + void (*destroy) (ike_cfg_t *this); +}; + +/** + * @brief Creates a ike_cfg_t object. + * + * Supplied hosts become owned by ike_cfg, the name gets cloned. + * + * @param name ike_cfg identifier + * @param certreq TRUE to send a certificate request + * @param my_host host_t representing local address + * @param other_host host_t representing remote address + * @return ike_cfg_t object. + * + * @ingroup config + */ +ike_cfg_t *ike_cfg_create(bool certreq, host_t *my_host, host_t *other_host); + +#endif /* IKE_CFG_H_ */ diff --git a/src/charon/config/peer_cfg.c b/src/charon/config/peer_cfg.c new file mode 100644 index 000000000..453fce555 --- /dev/null +++ b/src/charon/config/peer_cfg.c @@ -0,0 +1,470 @@ +/** + * @file peer_cfg.c + * + * @brief Implementation of peer_cfg_t. + * + */ + +/* + * Copyright (C) 2005-2007 Martin Willi + * Copyright (C) 2005 Jan Hutter + * Hochschule fuer Technik Rapperswil + * + * This program is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License as published by the + * Free Software Foundation; either version 2 of the License, or (at your + * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>. + * + * This program is distributed in the hope that it will be useful, but + * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY + * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * for more details. + */ + +#include <string.h> +#include <pthread.h> + +#include "peer_cfg.h" + +#include <utils/linked_list.h> +#include <utils/identification.h> + +ENUM(cert_policy_names, CERT_ALWAYS_SEND, CERT_NEVER_SEND, + "CERT_ALWAYS_SEND", + "CERT_SEND_IF_ASKED", + "CERT_NEVER_SEND" +); + +ENUM(dpd_action_names, DPD_NONE, DPD_RESTART, + "DPD_NONE", + "DPD_CLEAR", + "DPD_ROUTE", + "DPD_RESTART" +); + +typedef struct private_peer_cfg_t private_peer_cfg_t; + +/** + * Private data of an peer_cfg_t object + */ +struct private_peer_cfg_t { + + /** + * Public part + */ + peer_cfg_t public; + + /** + * Number of references hold by others to this peer_cfg + */ + refcount_t refcount; + + /** + * Name of the peer_cfg, used to query it + */ + char *name; + + /** + * IKE version to use for initiation + */ + u_int ike_version; + + /** + * IKE config associated to this peer config + */ + ike_cfg_t *ike_cfg; + + /** + * list of child configs associated to this peer config + */ + linked_list_t *child_cfgs; + + /** + * mutex to lock access to list of child_cfgs + */ + pthread_mutex_t mutex; + + /** + * id to use to identify us + */ + identification_t *my_id; + + /** + * allowed id for other + */ + identification_t *other_id; + + /** + * we have a cert issued by this CA + */ + identification_t *my_ca; + + /** + * we require the other end to have a cert issued by this CA + */ + identification_t *other_ca; + + /** + * should we send a certificate + */ + cert_policy_t cert_policy; + + /** + * Method to use for own authentication data + */ + auth_method_t auth_method; + + /** + * EAP type to use for peer authentication + */ + eap_type_t eap_type; + + /** + * number of tries after giving up if peer does not respond + */ + u_int32_t keyingtries; + + /** + * user reauthentication instead of rekeying + */ + bool use_reauth; + + /** + * Time before an SA gets invalid + */ + u_int32_t lifetime; + + /** + * Time before an SA gets rekeyed + */ + u_int32_t rekeytime; + + /** + * Time, which specifies the range of a random value + * substracted from lifetime. + */ + u_int32_t jitter; + + /** + * What to do with an SA when other peer seams to be dead? + */ + bool dpd_delay; + + /** + * What to do with CHILDren when other peer seams to be dead? + */ + bool dpd_action; + + /** + * virtual IP to use locally + */ + host_t *my_virtual_ip; + + /** + * virtual IP to use remotly + */ + host_t *other_virtual_ip; +}; + +/** + * Implementation of peer_cfg_t.get_name + */ +static char *get_name(private_peer_cfg_t *this) +{ + return this->name; +} + +/** + * Implementation of peer_cfg_t.get_ike_version + */ +static u_int get_ike_version(private_peer_cfg_t *this) +{ + return this->ike_version; +} + +/** + * Implementation of peer_cfg_t.get_ike_cfg + */ +static ike_cfg_t* get_ike_cfg(private_peer_cfg_t *this) +{ + return this->ike_cfg; +} + +/** + * Implementation of peer_cfg_t.add_child_cfg. + */ +static void add_child_cfg(private_peer_cfg_t *this, child_cfg_t *child_cfg) +{ + pthread_mutex_lock(&this->mutex); + this->child_cfgs->insert_last(this->child_cfgs, child_cfg); + pthread_mutex_unlock(&this->mutex); +} + +/** + * Implementation of peer_cfg_t.create_child_cfg_iterator. + */ +static iterator_t* create_child_cfg_iterator(private_peer_cfg_t *this) +{ + return this->child_cfgs->create_iterator_locked(this->child_cfgs, + &this->mutex); +} + +/** + * Check if child_cfg contains traffic selectors + */ +static bool contains_ts(child_cfg_t *child, bool mine, linked_list_t *ts, + host_t *host) +{ + linked_list_t *selected; + bool contains = FALSE; + + selected = child->get_traffic_selectors(child, mine, ts, host); + contains = selected->get_count(selected); + selected->destroy_offset(selected, offsetof(traffic_selector_t, destroy)); + return contains; +} + +/** + * Implementation of peer_cfg_t.select_child_cfg + */ +static child_cfg_t* select_child_cfg(private_peer_cfg_t *this, + linked_list_t *my_ts, + linked_list_t *other_ts, + host_t *my_host, host_t *other_host) +{ + child_cfg_t *current, *found = NULL; + iterator_t *iterator; + + iterator = create_child_cfg_iterator(this); + while (iterator->iterate(iterator, (void**)¤t)) + { + if (contains_ts(current, TRUE, my_ts, my_host) && + contains_ts(current, FALSE, other_ts, other_host)) + { + found = current; + found->get_ref(found); + break; + } + } + iterator->destroy(iterator); + return found; +} + +/** + * Implementation of peer_cfg_t.get_my_id + */ +static identification_t *get_my_id(private_peer_cfg_t *this) +{ + return this->my_id; +} + +/** + * Implementation of peer_cfg_t.get_other_id + */ +static identification_t *get_other_id(private_peer_cfg_t *this) +{ + return this->other_id; +} + +/** + * Implementation of peer_cfg_t.get_my_ca + */ +static identification_t *get_my_ca(private_peer_cfg_t *this) +{ + return this->my_ca; +} + +static identification_t *get_other_ca(private_peer_cfg_t *this) +{ + return this->other_ca; +} + +/** + * Implementation of peer_cfg_t.get_cert_policy. + */ +static cert_policy_t get_cert_policy(private_peer_cfg_t *this) +{ + return this->cert_policy; +} + +/** + * Implementation of connection_t.auth_method_t. + */ +static auth_method_t get_auth_method(private_peer_cfg_t *this) +{ + return this->auth_method; +} + +/** + * Implementation of connection_t.get_eap_type. + */ +static eap_type_t get_eap_type(private_peer_cfg_t *this) +{ + return this->eap_type; +} + +/** + * Implementation of connection_t.get_keyingtries. + */ +static u_int32_t get_keyingtries(private_peer_cfg_t *this) +{ + return this->keyingtries; +} + +/** + * Implementation of peer_cfg_t.get_soft_lifetime + */ +static u_int32_t get_lifetime(private_peer_cfg_t *this, bool rekey) +{ + if (rekey) + { + if (this->jitter == 0) + { + return this->rekeytime; + } + return this->rekeytime - (random() % this->jitter); + } + return this->lifetime; +} + +/** + * Implementation of peer_cfg_t.use_reauth. + */ +static bool use_reauth(private_peer_cfg_t *this, bool rekey) +{ + return this->use_reauth; +} + +/** + * Implements peer_cfg_t.get_dpd_delay + */ +static u_int32_t get_dpd_delay(private_peer_cfg_t *this) +{ + return this->dpd_action; +} + +/** + * Implements peer_cfg_t.get_dpd_action + */ +static dpd_action_t get_dpd_action(private_peer_cfg_t *this) +{ + return this->dpd_action; +} + +/** + * Implementation of peer_cfg_t.get_virtual_ip. + */ +static host_t* get_virtual_ip(private_peer_cfg_t *this, host_t *suggestion) +{ + if (suggestion == NULL) + { + if (this->my_virtual_ip) + { + return this->my_virtual_ip->clone(this->my_virtual_ip); + } + return NULL; + } + if (this->other_virtual_ip) + { + return this->other_virtual_ip->clone(this->other_virtual_ip); + } + if (suggestion->is_anyaddr(suggestion)) + { + return NULL; + } + return suggestion->clone(suggestion); +} + +/** + * Implements peer_cfg_t.get_ref. + */ +static void get_ref(private_peer_cfg_t *this) +{ + ref_get(&this->refcount); +} + +/** + * Implements peer_cfg_t.destroy. + */ +static void destroy(private_peer_cfg_t *this) +{ + if (ref_put(&this->refcount)) + { + this->ike_cfg->destroy(this->ike_cfg); + this->child_cfgs->destroy_offset(this->child_cfgs, offsetof(child_cfg_t, destroy)); + this->my_id->destroy(this->my_id); + this->other_id->destroy(this->other_id); + DESTROY_IF(this->my_ca); + DESTROY_IF(this->other_ca); + + DESTROY_IF(this->my_virtual_ip); + DESTROY_IF(this->other_virtual_ip); + free(this->name); + free(this); + } +} + +/* + * Described in header-file + */ +peer_cfg_t *peer_cfg_create(char *name, u_int ike_version, ike_cfg_t *ike_cfg, + identification_t *my_id, identification_t *other_id, + identification_t *my_ca, identification_t *other_ca, + cert_policy_t cert_policy, auth_method_t auth_method, + eap_type_t eap_type, u_int32_t keyingtries, + u_int32_t lifetime, u_int32_t rekeytime, + u_int32_t jitter, bool reauth, + u_int32_t dpd_delay, dpd_action_t dpd_action, + host_t *my_virtual_ip, host_t *other_virtual_ip) +{ + private_peer_cfg_t *this = malloc_thing(private_peer_cfg_t); + + /* public functions */ + this->public.get_name = (char* (*) (peer_cfg_t *))get_name; + this->public.get_ike_version = (u_int(*) (peer_cfg_t *))get_ike_version; + this->public.get_ike_cfg = (ike_cfg_t* (*) (peer_cfg_t *))get_ike_cfg; + this->public.add_child_cfg = (void (*) (peer_cfg_t *, child_cfg_t*))add_child_cfg; + this->public.create_child_cfg_iterator = (iterator_t* (*) (peer_cfg_t *))create_child_cfg_iterator; + this->public.select_child_cfg = (child_cfg_t* (*) (peer_cfg_t *,linked_list_t*,linked_list_t*,host_t*,host_t*))select_child_cfg; + this->public.get_my_id = (identification_t* (*)(peer_cfg_t*))get_my_id; + this->public.get_other_id = (identification_t* (*)(peer_cfg_t *))get_other_id; + this->public.get_my_ca = (identification_t* (*)(peer_cfg_t *))get_my_ca; + this->public.get_other_ca = (identification_t* (*)(peer_cfg_t *))get_other_ca; + this->public.get_cert_policy = (cert_policy_t (*) (peer_cfg_t *))get_cert_policy; + this->public.get_auth_method = (auth_method_t (*) (peer_cfg_t *))get_auth_method; + this->public.get_eap_type = (eap_type_t (*) (peer_cfg_t *))get_eap_type; + this->public.get_keyingtries = (u_int32_t (*) (peer_cfg_t *))get_keyingtries; + this->public.get_lifetime = (u_int32_t (*) (peer_cfg_t *, bool rekey))get_lifetime; + this->public.use_reauth = (bool (*) (peer_cfg_t *))use_reauth; + this->public.get_dpd_delay = (u_int32_t (*) (peer_cfg_t *))get_dpd_delay; + this->public.get_dpd_action = (dpd_action_t (*) (peer_cfg_t *))get_dpd_action; + this->public.get_virtual_ip = (host_t* (*) (peer_cfg_t *, host_t *))get_virtual_ip; + this->public.get_ref = (void(*)(peer_cfg_t *))get_ref; + this->public.destroy = (void(*)(peer_cfg_t *))destroy; + + /* apply init values */ + this->name = strdup(name); + this->ike_version = ike_version; + this->ike_cfg = ike_cfg; + this->child_cfgs = linked_list_create(); + pthread_mutex_init(&this->mutex, NULL); + this->my_id = my_id; + this->other_id = other_id; + this->my_ca = my_ca; + this->other_ca = other_ca; + this->cert_policy = cert_policy; + this->auth_method = auth_method; + this->eap_type = eap_type; + this->keyingtries = keyingtries; + this->lifetime = lifetime; + this->rekeytime = rekeytime; + this->jitter = jitter; + this->use_reauth = reauth; + this->dpd_delay = dpd_delay; + this->dpd_action = dpd_action; + this->my_virtual_ip = my_virtual_ip; + this->other_virtual_ip = other_virtual_ip; + this->refcount = 1; + + return &this->public; +} diff --git a/src/charon/config/peer_cfg.h b/src/charon/config/peer_cfg.h new file mode 100644 index 000000000..b0e3c8a3a --- /dev/null +++ b/src/charon/config/peer_cfg.h @@ -0,0 +1,345 @@ +/** + * @file peer_cfg.h + * + * @brief Interface of peer_cfg_t. + * + */ + +/* + * Copyright (C) 2005-2007 Martin Willi + * Copyright (C) 2005 Jan Hutter + * Hochschule fuer Technik Rapperswil + * + * This program is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License as published by the + * Free Software Foundation; either version 2 of the License, or (at your + * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>. + * + * This program is distributed in the hope that it will be useful, but + * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY + * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * for more details. + */ + +#ifndef PEER_CFG_H_ +#define PEER_CFG_H_ + +typedef enum dpd_action_t dpd_action_t; +typedef enum cert_policy_t cert_policy_t; +typedef struct peer_cfg_t peer_cfg_t; + +#include <library.h> +#include <utils/identification.h> +#include <config/traffic_selector.h> +#include <config/proposal.h> +#include <config/ike_cfg.h> +#include <config/child_cfg.h> +#include <sa/authenticators/authenticator.h> +#include <sa/authenticators/eap/eap_method.h> + +/** + * Certificate sending policy. This is also used for certificate + * requests when using this definition for the other peer. If + * it is CERT_NEVER_SEND, a certreq is omitted, otherwise its + * included. + * + * @ingroup config + * + * @warning These definitions must be the same as in pluto/starter, + * as they are sent over the stroke socket. + */ +enum cert_policy_t { + /** always send certificates, even when not requested */ + CERT_ALWAYS_SEND = 0, + /** send certificate upon cert request */ + CERT_SEND_IF_ASKED = 1, + /** never send a certificate, even when requested */ + CERT_NEVER_SEND = 2, +}; + +/** + * enum strings for cert_policy_t + * + * @ingroup config + */ +extern enum_name_t *cert_policy_names; + +/** + * @brief Actions to take when a peer does not respond (dead peer detected). + * + * These values are the same as in pluto/starter, so do not modify them! + * + * @ingroup peer_cfg + */ +enum dpd_action_t { + /** DPD disabled */ + DPD_NONE, + /** remove CHILD_SAs without replacement */ + DPD_CLEAR, + /** route the CHILD_SAs to resetup when needed */ + DPD_ROUTE, + /** restart CHILD_SAs in a new IKE_SA, immediately */ + DPD_RESTART, +}; + +/** + * enum names for dpd_action_t. + */ +extern enum_name_t *dpd_action_names; + +/** + * @brief Configuration of a peer, specified by IDs. + * + * @b Constructors: + * - peer_cfg_create() + * + * @ingroup peer_cfg + */ +struct peer_cfg_t { + + /** + * @brief Get the name of the peer_cfg. + * + * Returned object is not getting cloned. + * + * @param this calling object + * @return peer_cfg's name + */ + char* (*get_name) (peer_cfg_t *this); + + /** + * @brief Get the IKE version to use for initiating. + * + * @param this calling object + * @return IKE major version + */ + u_int (*get_ike_version)(peer_cfg_t *this); + + /** + * @brief Get the IKE config to use for initiaton. + * + * @param this calling object + * @return the IKE config to use + */ + ike_cfg_t* (*get_ike_cfg) (peer_cfg_t *this); + + /** + * @brief Attach a CHILD config. + * + * @param this calling object + * @param child_cfg CHILD config to add + */ + void (*add_child_cfg) (peer_cfg_t *this, child_cfg_t *child_cfg); + + /** + * @brief Create an iterator for all attached CHILD configs. + * + * @param this calling object + * @return an iterator over all CHILD configs. + */ + iterator_t* (*create_child_cfg_iterator) (peer_cfg_t *this); + + /** + * @brief Select a CHILD config from traffic selectors. + * + * @param this calling object + * @param my_ts TS for local side + * @param other_ts TS for remote side + * @param my_host host to narrow down dynamic TS for local side + * @param other_host host to narrow down dynamic TS for remote side + * @return selected CHILD config, or NULL if no match found + */ + child_cfg_t* (*select_child_cfg) (peer_cfg_t *this, linked_list_t *my_ts, + linked_list_t *other_ts, host_t *my_host, + host_t *other_host); + + /** + * @brief Get own ID. + * + * @param this calling object + * @return own id + */ + identification_t* (*get_my_id)(peer_cfg_t *this); + + /** + * @brief Get peers ID. + * + * @param this calling object + * @return other id + */ + identification_t* (*get_other_id)(peer_cfg_t *this); + + /** + * @brief Get own CA. + * + * @param this calling object + * @return own ca + */ + identification_t* (*get_my_ca)(peer_cfg_t *this); + + /** + * @brief Get peers CA. + * + * @param this calling object + * @return other ca + */ + identification_t* (*get_other_ca)(peer_cfg_t *this); + + /** + * @brief Should be sent a certificate for this connection? + * + * @param this calling object + * @return certificate sending policy + */ + cert_policy_t (*get_cert_policy) (peer_cfg_t *this); + + /** + * @brief Get the authentication method to use to authenticate us. + * + * @param this calling object + * @return authentication method + */ + auth_method_t (*get_auth_method) (peer_cfg_t *this); + + /** + * @brief Get the EAP type to use for peer authentication. + * + * @param this calling object + * @return authentication method + */ + eap_type_t (*get_eap_type) (peer_cfg_t *this); + + /** + * @brief Get the max number of retries after timeout. + * + * @param this calling object + * @return max number retries + */ + u_int32_t (*get_keyingtries) (peer_cfg_t *this); + + /** + * @brief Get the lifetime of a IKE_SA. + * + * If "rekey" is set to TRUE, a lifetime is returned before the first + * rekeying should be started. If it is FALSE, the actual lifetime is + * returned when the IKE_SA must be deleted. + * The rekey time automatically contains a jitter to avoid simlutaneous + * rekeying. + * + * @param this child_config + * @param rekey TRUE to get rekey time + * @return lifetime in seconds + */ + u_int32_t (*get_lifetime) (peer_cfg_t *this, bool rekey); + + /** + * @brief Should a full reauthentication be done instead of rekeying? + * + * @param this calling object + * @return TRUE to use full reauthentication + */ + bool (*use_reauth) (peer_cfg_t *this); + + /** + * @brief Get the DPD check interval. + * + * @param this calling object + * @return dpd_delay in seconds + */ + u_int32_t (*get_dpd_delay) (peer_cfg_t *this); + + /** + * @brief What should be done with a CHILD_SA, when other peer does not respond. + * + * @param this calling object + * @return dpd action + */ + dpd_action_t (*get_dpd_action) (peer_cfg_t *this); + + /** + * @brief Get a virtual IP for the local or the remote host. + * + * By supplying NULL as IP, an IP for the local host is requested. It + * may be %any or specific. + * By supplying %any as host, an IP from the pool is selected to be + * served to the peer. + * If a specified host is supplied, it is checked if this address + * is acceptable to serve to the peer. If so, it is returned. Otherwise, + * an alternative IP is returned. + * In any mode, this call may return NULL indicating virtual IP should + * not be used. + * + * @param this peer_cfg + * @param suggestion NULL, %any or specific, see description + * @return clone of an IP to use, or NULL + */ + host_t* (*get_virtual_ip) (peer_cfg_t *this, host_t *suggestion); + + /** + * @brief Get a new reference. + * + * Get a new reference to this peer_cfg by increasing + * it's internal reference counter. + * Do not call get_ref or any other function until you + * already have a reference. Otherwise the object may get + * destroyed while calling get_ref(), + * + * @param this calling object + */ + void (*get_ref) (peer_cfg_t *this); + + /** + * @brief Destroys the peer_cfg object. + * + * Decrements the internal reference counter and + * destroys the peer_cfg when it reaches zero. + * + * @param this calling object + */ + void (*destroy) (peer_cfg_t *this); +}; + +/** + * @brief Create a configuration object for IKE_AUTH and later. + * + * name-string gets cloned, ID's not. + * Virtual IPs are used if they are != NULL. A %any host means the virtual + * IP should be obtained from the other peer. + * Lifetimes are in seconds. To prevent to peers to start rekeying at the + * same time, a jitter may be specified. Rekeying of an SA starts at + * (rekeylifetime - random(0, jitter)). + * + * @param name name of the peer_cfg + * @param ike_version which IKE version we sould use for this peer + * @param ike_cfg IKE config to use when acting as initiator + * @param my_id identification_t for ourselves + * @param other_id identification_t for the remote guy + * @param my_ca CA to use for us + * @param other_ca CA to use for other + * @param cert_policy should we send a certificate payload? + * @param auth_method auth method to use to authenticate us + * @param eap_type EAP type to use for peer authentication + * @param keyingtries how many keying tries should be done before giving up + * @param lifetime lifetime before deleting an SA + * @param rekeytime lifetime before rekeying an SA + * @param jitter range of random to substract from rekeytime + * @param use_reauth sould be done reauthentication instead of rekeying? + * @param dpd_delay after how many seconds of inactivity to check DPD + * @param dpd_action what to do with CHILD_SAs when detected a dead peer + * @param my_virtual_ip virtual IP for local host, or NULL + * @param other_virtual_ip virtual IP for remote host, or NULL + * @return peer_cfg_t object + * + * @ingroup config + */ +peer_cfg_t *peer_cfg_create(char *name, u_int ikev_version, ike_cfg_t *ike_cfg, + identification_t *my_id, identification_t *other_id, + identification_t *my_ca, identification_t *other_ca, + cert_policy_t cert_policy, auth_method_t auth_method, + eap_type_t eap_type, u_int32_t keyingtries, + u_int32_t lifetime, u_int32_t rekeytime, + u_int32_t jitter, bool use_reauth, + u_int32_t dpd_delay, dpd_action_t dpd_action, + host_t *my_virtual_ip, host_t *other_virtual_ip); + +#endif /* PEER_CFG_H_ */ diff --git a/src/charon/config/policies/local_policy_store.c b/src/charon/config/policies/local_policy_store.c deleted file mode 100644 index dd22b43a0..000000000 --- a/src/charon/config/policies/local_policy_store.c +++ /dev/null @@ -1,282 +0,0 @@ -/** - * @file local_policy_store.c - * - * @brief Implementation of local_policy_store_t. - * - */ - -/* - * Copyright (C) 2006 Martin Willi - * Hochschule fuer Technik Rapperswil - * - * This program is free software; you can redistribute it and/or modify it - * under the terms of the GNU General Public License as published by the - * Free Software Foundation; either version 2 of the License, or (at your - * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>. - * - * This program is distributed in the hope that it will be useful, but - * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY - * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License - * for more details. - */ - -#include <string.h> - -#include "local_policy_store.h" - -#include <daemon.h> -#include <utils/linked_list.h> - - -typedef struct private_local_policy_store_t private_local_policy_store_t; - -/** - * Private data of an local_policy_store_t object - */ -struct private_local_policy_store_t { - - /** - * Public part - */ - local_policy_store_t public; - - /** - * list of policy_t's - */ - linked_list_t *policies; - - /** - * Mutex to exclusivly access list - */ - pthread_mutex_t mutex; -}; - -/** - * Implementation of policy_store_t.add_policy. - */ -static void add_policy(private_local_policy_store_t *this, policy_t *policy) -{ - pthread_mutex_lock(&(this->mutex)); - this->policies->insert_last(this->policies, (void*)policy); - pthread_mutex_unlock(&(this->mutex)); -} - -/** - * Check if a policy contains traffic selectors - */ -static bool contains_traffic_selectors(policy_t *policy, bool mine, - linked_list_t *ts, host_t *host) -{ - linked_list_t *selected; - bool contains = FALSE; - - if (mine) - { - selected = policy->select_my_traffic_selectors(policy, ts, host); - } - else - { - selected = policy->select_other_traffic_selectors(policy, ts, host); - } - if (selected->get_count(selected)) - { - contains = TRUE; - } - selected->destroy_offset(selected, offsetof(traffic_selector_t, destroy)); - return contains; -} - -/** - * Implementation of policy_store_t.get_policy. - */ -static policy_t *get_policy(private_local_policy_store_t *this, - identification_t *my_id, identification_t *other_id, - linked_list_t *my_ts, linked_list_t *other_ts, - host_t *my_host, host_t *other_host) -{ - typedef enum { - PRIO_UNDEFINED = 0x00, - PRIO_TS_MISMATCH = 0x01, - PRIO_ID_ANY = 0x02, - PRIO_ID_MATCH = PRIO_ID_ANY + MAX_WILDCARDS, - } prio_t; - - prio_t best_prio = PRIO_UNDEFINED; - - iterator_t *iterator; - policy_t *candidate; - policy_t *found = NULL; - traffic_selector_t *ts; - - DBG1(DBG_CFG, "searching policy for '%D'...'%D'", my_id, other_id); - iterator = my_ts->create_iterator(my_ts, TRUE); - while (iterator->iterate(iterator, (void**)&ts)) - { - DBG1(DBG_CFG, " local TS: %R", ts); - } - iterator->destroy(iterator); - iterator = other_ts->create_iterator(other_ts, TRUE); - while (iterator->iterate(iterator, (void**)&ts)) - { - DBG1(DBG_CFG, " remote TS: %R", ts); - } - iterator->destroy(iterator); - - pthread_mutex_lock(&(this->mutex)); - iterator = this->policies->create_iterator(this->policies, TRUE); - - /* determine closest matching policy */ - while (iterator->iterate(iterator, (void**)&candidate)) - { - identification_t *candidate_my_id; - identification_t *candidate_other_id; - int wildcards; - - candidate_my_id = candidate->get_my_id(candidate); - candidate_other_id = candidate->get_other_id(candidate); - - /* my_id is either %any or if set must match exactly */ - if (candidate_my_id->matches(candidate_my_id, my_id, &wildcards)) - { - prio_t prio = PRIO_UNDEFINED; - - /* wildcard match for other_id */ - if (!other_id->matches(other_id, candidate_other_id, &wildcards)) - { - continue; - } - prio = PRIO_ID_MATCH - wildcards; - - /* only accept if traffic selectors match */ - if (!contains_traffic_selectors(candidate, TRUE, my_ts, my_host) || - !contains_traffic_selectors(candidate, FALSE, other_ts, other_host)) - { - DBG2(DBG_CFG, "candidate '%s' inacceptable due traffic " - "selector mismatch", candidate->get_name(candidate)); - prio = PRIO_TS_MISMATCH; - } - - DBG2(DBG_CFG, "candidate policy '%s': '%D'...'%D' (prio=%d)", - candidate->get_name(candidate), - candidate_my_id, candidate_other_id, prio); - - if (prio > best_prio) - { - found = candidate; - best_prio = prio; - } - } - } - iterator->destroy(iterator); - - if (found) - { - DBG1(DBG_CFG, "found matching policy '%s': '%D'...'%D' (prio=%d)", - found->get_name(found), found->get_my_id(found), - found->get_other_id(found), best_prio); - /* give out a new reference to it */ - found->get_ref(found); - } - pthread_mutex_unlock(&(this->mutex)); - return found; -} - -/** - * Implementation of policy_store_t.get_policy_by_name. - */ -static policy_t *get_policy_by_name(private_local_policy_store_t *this, char *name) -{ - iterator_t *iterator; - policy_t *current, *found = NULL; - - DBG2(DBG_CFG, "looking for policy '%s'", name); - - pthread_mutex_lock(&(this->mutex)); - iterator = this->policies->create_iterator(this->policies, TRUE); - while (iterator->iterate(iterator, (void **)¤t)) - { - if (strcmp(current->get_name(current), name) == 0) - { - found = current; - } - } - iterator->destroy(iterator); - pthread_mutex_unlock(&(this->mutex)); - - /* give out a new reference */ - found->get_ref(found); - return found; -} - -/** - * Implementation of policy_store_t.delete_policy. - */ -static status_t delete_policy(private_local_policy_store_t *this, char *name) -{ - iterator_t *iterator; - policy_t *current; - bool found = FALSE; - - pthread_mutex_lock(&(this->mutex)); - iterator = this->policies->create_iterator(this->policies, TRUE); - while (iterator->iterate(iterator, (void **)¤t)) - { - if (strcmp(current->get_name(current), name) == 0) - { - /* remove policy from list, and destroy it */ - iterator->remove(iterator); - current->destroy(current); - found = TRUE; - /* we do not break here, as there may be multipe policies */ - } - } - iterator->destroy(iterator); - pthread_mutex_unlock(&(this->mutex)); - if (found) - { - return SUCCESS; - } - return NOT_FOUND; -} - -/** - * Implementation of policy_store_t.create_iterator. - */ -static iterator_t* create_iterator(private_local_policy_store_t *this) -{ - return this->policies->create_iterator_locked(this->policies, - &this->mutex); -} - -/** - * Implementation of policy_store_t.destroy. - */ -static void destroy(private_local_policy_store_t *this) -{ - pthread_mutex_lock(&(this->mutex)); - this->policies->destroy_offset(this->policies, offsetof(policy_t, destroy)); - pthread_mutex_unlock(&(this->mutex)); - free(this); -} - -/** - * Described in header. - */ -local_policy_store_t *local_policy_store_create(void) -{ - private_local_policy_store_t *this = malloc_thing(private_local_policy_store_t); - - this->public.policy_store.add_policy = (void (*) (policy_store_t*,policy_t*))add_policy; - this->public.policy_store.get_policy = (policy_t* (*) (policy_store_t*,identification_t*,identification_t*, - linked_list_t*,linked_list_t*,host_t*,host_t*))get_policy; - this->public.policy_store.get_policy_by_name = (policy_t* (*) (policy_store_t*,char*))get_policy_by_name; - this->public.policy_store.delete_policy = (status_t (*) (policy_store_t*,char*))delete_policy; - this->public.policy_store.create_iterator = (iterator_t* (*) (policy_store_t*))create_iterator; - this->public.policy_store.destroy = (void (*) (policy_store_t*))destroy; - - /* private variables */ - this->policies = linked_list_create(); - pthread_mutex_init(&(this->mutex), NULL); - - return (&this->public); -} diff --git a/src/charon/config/policies/local_policy_store.h b/src/charon/config/policies/local_policy_store.h deleted file mode 100644 index 01d5d2d60..000000000 --- a/src/charon/config/policies/local_policy_store.h +++ /dev/null @@ -1,60 +0,0 @@ -/** - * @file local_policy_store.h - * - * @brief Interface of local_policy_store_t. - * - */ - -/* - * Copyright (C) 2006 Martin Willi - * Hochschule fuer Technik Rapperswil - * - * This program is free software; you can redistribute it and/or modify it - * under the terms of the GNU General Public License as published by the - * Free Software Foundation; either version 2 of the License, or (at your - * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>. - * - * This program is distributed in the hope that it will be useful, but - * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY - * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License - * for more details. - */ - -#ifndef LOCAL_POLICY_STORE_H_ -#define LOCAL_POLICY_STORE_H_ - -typedef struct local_policy_store_t local_policy_store_t; - -#include <library.h> -#include <config/policies/policy_store.h> - - -/** - * @brief A policy_store_t implementation using a simple policy lists. - * - * The local_policy_store_t class implements the policy_store_t interface - * as simple as possible. The policies are stored in a in-memory list. - * - * @b Constructors: - * - local_policy_store_create() - * - * @ingroup config - */ -struct local_policy_store_t { - - /** - * Implements policy_store_t interface - */ - policy_store_t policy_store; -}; - -/** - * @brief Creates a local_policy_store_t instance. - * - * @return policy store instance. - * - * @ingroup config - */ -local_policy_store_t *local_policy_store_create(void); - -#endif /* LOCAL_POLICY_STORE_H_ */ diff --git a/src/charon/config/policies/policy.c b/src/charon/config/policies/policy.c deleted file mode 100644 index 363d1609f..000000000 --- a/src/charon/config/policies/policy.c +++ /dev/null @@ -1,635 +0,0 @@ -/** - * @file policy.c - * - * @brief Implementation of policy_t. - * - */ - -/* - * Copyright (C) 2005-2006 Martin Willi - * Copyright (C) 2005 Jan Hutter - * Hochschule fuer Technik Rapperswil - * - * This program is free software; you can redistribute it and/or modify it - * under the terms of the GNU General Public License as published by the - * Free Software Foundation; either version 2 of the License, or (at your - * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>. - * - * This program is distributed in the hope that it will be useful, but - * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY - * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License - * for more details. - */ - -#include <time.h> -#include <string.h> -#include <unistd.h> - -#include "policy.h" - -#include <daemon.h> -#include <utils/linked_list.h> -#include <utils/identification.h> - -ENUM(dpd_action_names, DPD_NONE, DPD_RESTART, - "DPD_NONE", - "DPD_CLEAR", - "DPD_ROUTE", - "DPD_RESTART" -); - -ENUM(mode_names, MODE_TRANSPORT, MODE_BEET, - "TRANSPORT", - "TUNNEL", - "2", - "3", - "BEET" -); - -typedef struct private_policy_t private_policy_t; - -/** - * Private data of an policy_t object - */ -struct private_policy_t { - - /** - * Public part - */ - policy_t public; - - /** - * Number of references hold by others to this policy - */ - refcount_t refcount; - - /** - * Name of the policy, used to query it - */ - char *name; - - /** - * id to use to identify us - */ - identification_t *my_id; - - /** - * allowed id for other - */ - identification_t *other_id; - - /** - * virtual IP to use locally - */ - host_t *my_virtual_ip; - - /** - * virtual IP to use remotly - */ - host_t *other_virtual_ip; - - /** - * Method to use for own authentication data - */ - auth_method_t auth_method; - - /** - * EAP type to use for peer authentication - */ - eap_type_t eap_type; - - /** - * we have a cert issued by this CA - */ - identification_t *my_ca; - - /** - * we require the other end to have a cert issued by this CA - */ - identification_t *other_ca; - - /** - * updown script - */ - char *updown; - - /** - * allow host access - */ - bool hostaccess; - - /** - * list for all proposals - */ - linked_list_t *proposals; - - /** - * list for traffic selectors for my site - */ - linked_list_t *my_ts; - - /** - * list for traffic selectors for others site - */ - linked_list_t *other_ts; - - /** - * Time before an SA gets invalid - */ - u_int32_t soft_lifetime; - - /** - * Time before an SA gets rekeyed - */ - u_int32_t hard_lifetime; - - /** - * Time, which specifies the range of a random value - * substracted from soft_lifetime. - */ - u_int32_t jitter; - - /** - * What to do with an SA when other peer seams to be dead? - */ - bool dpd_action; - - /** - * Mode to propose for a initiated CHILD: tunnel/transport - */ - mode_t mode; -}; - -/** - * Implementation of policy_t.get_name - */ -static char *get_name(private_policy_t *this) -{ - return this->name; -} - -/** - * Implementation of policy_t.get_my_id - */ -static identification_t *get_my_id(private_policy_t *this) -{ - return this->my_id; -} - -/** - * Implementation of policy_t.get_other_id - */ -static identification_t *get_other_id(private_policy_t *this) -{ - return this->other_id; -} - -/** - * Implementation of policy_t.get_my_ca - */ -static identification_t *get_my_ca(private_policy_t *this) -{ - return this->my_ca; -} - -/** - * Implementation of policy_t.get_other_ca - */ -static identification_t *get_other_ca(private_policy_t *this) -{ - return this->other_ca; -} - -/** - * Implementation of connection_t.auth_method_t. - */ -static auth_method_t get_auth_method(private_policy_t *this) -{ - return this->auth_method; -} - -/** - * Implementation of connection_t.get_eap_type. - */ -static eap_type_t get_eap_type(private_policy_t *this) -{ - return this->eap_type; -} - -/** - * Get traffic selectors, with wildcard-address update - */ -static linked_list_t *get_traffic_selectors(private_policy_t *this, - linked_list_t *list, host_t *host) -{ - iterator_t *iterator; - traffic_selector_t *current; - linked_list_t *result = linked_list_create(); - - iterator = list->create_iterator(list, TRUE); - - while (iterator->iterate(iterator, (void**)¤t)) - { - /* we make a copy of the TS, this allows us to update wildcard - * addresses in it. We won't pollute the shared policy. */ - current = current->clone(current); - if (host) - { - current->set_address(current, host); - } - - result->insert_last(result, (void*)current); - } - iterator->destroy(iterator); - return result; -} - -/** - * Implementation of policy_t.get_my_traffic_selectors - */ -static linked_list_t *get_my_traffic_selectors(private_policy_t *this, host_t *me) -{ - return get_traffic_selectors(this, this->my_ts, me); -} - -/** - * Implementation of policy_t.get_other_traffic_selectors - */ -static linked_list_t *get_other_traffic_selectors(private_policy_t *this, host_t *other) -{ - return get_traffic_selectors(this, this->other_ts, other); -} - -/** - * Narrow traffic selectors, with wildcard-address update in "stored". - */ -static linked_list_t *select_traffic_selectors(private_policy_t *this, - linked_list_t *stored, - linked_list_t *supplied, - host_t *host) -{ - iterator_t *supplied_iter, *stored_iter, *i1, *i2; - traffic_selector_t *supplied_ts, *stored_ts, *selected_ts, *ts1, *ts2; - linked_list_t *selected = linked_list_create(); - - DBG2(DBG_CFG, "selecting traffic selectors"); - - stored_iter = stored->create_iterator(stored, TRUE); - supplied_iter = supplied->create_iterator(supplied, TRUE); - - /* iterate over all stored selectors */ - while (stored_iter->iterate(stored_iter, (void**)&stored_ts)) - { - /* we make a copy of the TS, this allows us to update wildcard - * addresses in it. We won't pollute the shared policy. */ - stored_ts = stored_ts->clone(stored_ts); - if (host) - { - stored_ts->set_address(stored_ts, host); - } - - supplied_iter->reset(supplied_iter); - /* iterate over all supplied traffic selectors */ - while (supplied_iter->iterate(supplied_iter, (void**)&supplied_ts)) - { - DBG2(DBG_CFG, "stored %R <=> %R received", - stored_ts, supplied_ts); - - selected_ts = stored_ts->get_subset(stored_ts, supplied_ts); - if (selected_ts) - { - /* got a match, add to list */ - selected->insert_last(selected, (void*)selected_ts); - - DBG2(DBG_CFG, "found traffic selector for %s: %R", - stored == this->my_ts ? "us" : "other", selected_ts); - } - } - stored_ts->destroy(stored_ts); - } - stored_iter->destroy(stored_iter); - supplied_iter->destroy(supplied_iter); - - /* remove any redundant traffic selectors in the list */ - i1 = selected->create_iterator(selected, TRUE); - i2 = selected->create_iterator(selected, TRUE); - while (i1->iterate(i1, (void**)&ts1)) - { - while (i2->iterate(i2, (void**)&ts2)) - { - if (ts1 != ts2) - { - if (ts2->is_contained_in(ts2, ts1)) - { - i2->remove(i2); - ts2->destroy(ts2); - i1->reset(i1); - break; - } - if (ts1->is_contained_in(ts1, ts2)) - { - i1->remove(i1); - ts1->destroy(ts1); - i2->reset(i2); - break; - } - } - } - } - i1->destroy(i1); - i2->destroy(i2); - - return selected; -} - -/** - * Implementation of private_policy_t.select_my_traffic_selectors - */ -static linked_list_t *select_my_traffic_selectors(private_policy_t *this, - linked_list_t *supplied, - host_t *me) -{ - return select_traffic_selectors(this, this->my_ts, supplied, me); -} - -/** - * Implementation of private_policy_t.select_other_traffic_selectors - */ -static linked_list_t *select_other_traffic_selectors(private_policy_t *this, - linked_list_t *supplied, - host_t* other) -{ - return select_traffic_selectors(this, this->other_ts, supplied, other); -} - -/** - * Implementation of policy_t.get_proposal_iterator - */ -static linked_list_t *get_proposals(private_policy_t *this) -{ - iterator_t *iterator; - proposal_t *current; - linked_list_t *proposals = linked_list_create(); - - iterator = this->proposals->create_iterator(this->proposals, TRUE); - while (iterator->iterate(iterator, (void**)¤t)) - { - current = current->clone(current); - proposals->insert_last(proposals, (void*)current); - } - iterator->destroy(iterator); - - return proposals; -} - -/** - * Implementation of policy_t.select_proposal - */ -static proposal_t *select_proposal(private_policy_t *this, linked_list_t *proposals) -{ - iterator_t *stored_iter, *supplied_iter; - proposal_t *stored, *supplied, *selected; - - stored_iter = this->proposals->create_iterator(this->proposals, TRUE); - supplied_iter = proposals->create_iterator(proposals, TRUE); - - /* compare all stored proposals with all supplied. Stored ones are preferred. */ - while (stored_iter->iterate(stored_iter, (void**)&stored)) - { - supplied_iter->reset(supplied_iter); - while (supplied_iter->iterate(supplied_iter, (void**)&supplied)) - { - selected = stored->select(stored, supplied); - if (selected) - { - /* they match, return */ - stored_iter->destroy(stored_iter); - supplied_iter->destroy(supplied_iter); - return selected; - } - } - } - - /* no proposal match :-(, will result in a NO_PROPOSAL_CHOSEN... */ - stored_iter->destroy(stored_iter); - supplied_iter->destroy(supplied_iter); - - return NULL; -} - -/** - * Implementation of policy_t.add_authorities - */ -static void add_authorities(private_policy_t *this, identification_t *my_ca, identification_t *other_ca) -{ - this->my_ca = my_ca; - this->other_ca = other_ca; -} - -/** - * Implementation of policy_t.get_updown - */ -static char* get_updown(private_policy_t *this) -{ - return this->updown; -} - -/** - * Implementation of policy_t.get_hostaccess - */ -static bool get_hostaccess(private_policy_t *this) -{ - return this->hostaccess; -} - -/** - * Implements policy_t.get_dpd_action - */ -static dpd_action_t get_dpd_action(private_policy_t *this) -{ - return this->dpd_action; -} - -/** - * Implementation of policy_t.add_my_traffic_selector - */ -static void add_my_traffic_selector(private_policy_t *this, traffic_selector_t *traffic_selector) -{ - this->my_ts->insert_last(this->my_ts, (void*)traffic_selector); -} - -/** - * Implementation of policy_t.add_other_traffic_selector - */ -static void add_other_traffic_selector(private_policy_t *this, traffic_selector_t *traffic_selector) -{ - this->other_ts->insert_last(this->other_ts, (void*)traffic_selector); -} - -/** - * Implementation of policy_t.add_proposal - */ -static void add_proposal(private_policy_t *this, proposal_t *proposal) -{ - this->proposals->insert_last(this->proposals, (void*)proposal); -} - -/** - * Implementation of policy_t.get_soft_lifetime - */ -static u_int32_t get_soft_lifetime(private_policy_t *this) -{ - if (this->jitter == 0) - { - return this->soft_lifetime ; - } - return this->soft_lifetime - (random() % this->jitter); -} - -/** - * Implementation of policy_t.get_hard_lifetime - */ -static u_int32_t get_hard_lifetime(private_policy_t *this) -{ - return this->hard_lifetime; -} - -/** - * Implementation of policy_t.get_mode. - */ -static mode_t get_mode(private_policy_t *this) -{ - return this->mode; -} - -/** - * Implementation of policy_t.get_virtual_ip. - */ -static host_t* get_virtual_ip(private_policy_t *this, host_t *suggestion) -{ - if (suggestion == NULL) - { - if (this->my_virtual_ip) - { - return this->my_virtual_ip->clone(this->my_virtual_ip); - } - return NULL; - } - if (this->other_virtual_ip) - { - return this->other_virtual_ip->clone(this->other_virtual_ip); - } - if (suggestion->is_anyaddr(suggestion)) - { - return NULL; - } - return suggestion->clone(suggestion); -} - -/** - * Implements policy_t.get_ref. - */ -static void get_ref(private_policy_t *this) -{ - ref_get(&this->refcount); -} - -/** - * Implements policy_t.destroy. - */ -static void destroy(private_policy_t *this) -{ - if (ref_put(&this->refcount)) - { - - this->proposals->destroy_offset(this->proposals, offsetof(proposal_t, destroy)); - this->my_ts->destroy_offset(this->my_ts, offsetof(traffic_selector_t, destroy)); - this->other_ts->destroy_offset(this->other_ts, offsetof(traffic_selector_t, destroy)); - - /* delete certification authorities */ - DESTROY_IF(this->my_ca); - DESTROY_IF(this->other_ca); - - /* delete updown script */ - if (this->updown) - { - free(this->updown); - } - - /* delete ids */ - this->my_id->destroy(this->my_id); - this->other_id->destroy(this->other_id); - DESTROY_IF(this->my_virtual_ip); - DESTROY_IF(this->other_virtual_ip); - - free(this->name); - free(this); - } -} - -/* - * Described in header-file - */ -policy_t *policy_create(char *name, identification_t *my_id, identification_t *other_id, - host_t *my_virtual_ip, host_t *other_virtual_ip, - auth_method_t auth_method, eap_type_t eap_type, - u_int32_t hard_lifetime, u_int32_t soft_lifetime, - u_int32_t jitter, char *updown, bool hostaccess, - mode_t mode, dpd_action_t dpd_action) -{ - private_policy_t *this = malloc_thing(private_policy_t); - - /* public functions */ - this->public.get_name = (char* (*) (policy_t*))get_name; - this->public.get_my_id = (identification_t* (*) (policy_t*))get_my_id; - this->public.get_other_id = (identification_t* (*) (policy_t*))get_other_id; - this->public.get_my_ca = (identification_t* (*) (policy_t*))get_my_ca; - this->public.get_other_ca = (identification_t* (*) (policy_t*))get_other_ca; - this->public.get_auth_method = (auth_method_t (*) (policy_t*)) get_auth_method; - this->public.get_eap_type = (eap_type_t (*) (policy_t*)) get_eap_type; - this->public.get_my_traffic_selectors = (linked_list_t* (*) (policy_t*,host_t*))get_my_traffic_selectors; - this->public.get_other_traffic_selectors = (linked_list_t* (*) (policy_t*,host_t*))get_other_traffic_selectors; - this->public.select_my_traffic_selectors = (linked_list_t* (*) (policy_t*,linked_list_t*,host_t*))select_my_traffic_selectors; - this->public.select_other_traffic_selectors = (linked_list_t* (*) (policy_t*,linked_list_t*,host_t*))select_other_traffic_selectors; - this->public.get_proposals = (linked_list_t* (*) (policy_t*))get_proposals; - this->public.select_proposal = (proposal_t* (*) (policy_t*,linked_list_t*))select_proposal; - this->public.add_my_traffic_selector = (void (*) (policy_t*,traffic_selector_t*))add_my_traffic_selector; - this->public.add_other_traffic_selector = (void (*) (policy_t*,traffic_selector_t*))add_other_traffic_selector; - this->public.add_proposal = (void (*) (policy_t*,proposal_t*))add_proposal; - this->public.add_authorities = (void (*) (policy_t*,identification_t*,identification_t*))add_authorities; - this->public.get_updown = (char* (*) (policy_t*))get_updown; - this->public.get_hostaccess = (bool (*) (policy_t*))get_hostaccess; - this->public.get_dpd_action = (dpd_action_t (*) (policy_t*))get_dpd_action; - this->public.get_soft_lifetime = (u_int32_t (*) (policy_t *))get_soft_lifetime; - this->public.get_hard_lifetime = (u_int32_t (*) (policy_t *))get_hard_lifetime; - this->public.get_mode = (mode_t (*) (policy_t *))get_mode; - this->public.get_virtual_ip = (host_t* (*)(policy_t*,host_t*))get_virtual_ip; - this->public.get_ref = (void (*) (policy_t*))get_ref; - this->public.destroy = (void (*) (policy_t*))destroy; - - /* apply init values */ - this->name = strdup(name); - this->my_id = my_id; - this->other_id = other_id; - this->my_virtual_ip = my_virtual_ip; - this->other_virtual_ip = other_virtual_ip; - this->auth_method = auth_method; - this->eap_type = eap_type; - this->hard_lifetime = hard_lifetime; - this->soft_lifetime = soft_lifetime; - this->jitter = jitter; - this->updown = (updown == NULL) ? NULL : strdup(updown); - this->hostaccess = hostaccess; - this->dpd_action = dpd_action; - this->mode = mode; - - /* initialize private members*/ - this->refcount = 1; - this->my_ca = NULL; - this->other_ca = NULL; - this->proposals = linked_list_create(); - this->my_ts = linked_list_create(); - this->other_ts = linked_list_create(); - - return &this->public; -} diff --git a/src/charon/config/policies/policy.h b/src/charon/config/policies/policy.h deleted file mode 100644 index d8916b29e..000000000 --- a/src/charon/config/policies/policy.h +++ /dev/null @@ -1,413 +0,0 @@ -/** - * @file policy.h - * - * @brief Interface of policy_t. - * - */ - -/* - * Copyright (C) 2005-2006 Martin Willi - * Copyright (C) 2005 Jan Hutter - * Hochschule fuer Technik Rapperswil - * - * This program is free software; you can redistribute it and/or modify it - * under the terms of the GNU General Public License as published by the - * Free Software Foundation; either version 2 of the License, or (at your - * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>. - * - * This program is distributed in the hope that it will be useful, but - * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY - * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License - * for more details. - */ - -#ifndef POLICY_H_ -#define POLICY_H_ - -typedef enum dpd_action_t dpd_action_t; -typedef struct policy_t policy_t; - -#include <library.h> -#include <utils/identification.h> -#include <config/traffic_selector.h> -#include <config/proposal.h> -#include <sa/authenticators/authenticator.h> -#include <sa/authenticators/eap/eap_method.h> - - -/** - * @brief Actions to take when a peer does not respond (dead peer detected). - * - * These values are the same as in pluto/starter, so do not modify them! - * - * @ingroup config - */ -enum dpd_action_t { - /** DPD disabled */ - DPD_NONE, - /** remove CHILD_SA without replacement */ - DPD_CLEAR, - /** route the CHILD_SA to resetup when needed */ - DPD_ROUTE, - /** restart CHILD_SA in a new IKE_SA, immediately */ - DPD_RESTART, -}; - -/** - * enum names for dpd_action_t. - */ -extern enum_name_t *dpd_action_names; - -/** - * @brief Mode of an IPsec SA. - * - * These are equal to those defined in XFRM, so don't change. - * - * @ingroup config - */ -enum mode_t { - /** transport mode, no inner address */ - MODE_TRANSPORT = 0, - /** tunnel mode, inner and outer addresses */ - MODE_TUNNEL = 1, - /** BEET mode, tunnel mode but fixed, bound inner addresses */ - MODE_BEET = 4, -}; - -/** - * enum names for mode_t. - */ -extern enum_name_t *mode_names; - -/** - * @brief A policy_t defines the policies to apply to CHILD_SAs. - * - * The given two IDs identify a policy. These rules define how - * child SAs may be set up and which traffic may be IPsec'ed. - * - * @b Constructors: - * - policy_create() - * - * @ingroup config - */ -struct policy_t { - - /** - * @brief Get the name of the policy. - * - * Returned object is not getting cloned. - * - * @param this calling object - * @return policy's name - */ - char *(*get_name) (policy_t *this); - - /** - * @brief Get own id. - * - * Returned object is not getting cloned. - * - * @param this calling object - * @return own id - */ - identification_t *(*get_my_id) (policy_t *this); - - /** - * @brief Get peer id. - * - * Returned object is not getting cloned. - * - * @param this calling object - * @return other id - */ - identification_t *(*get_other_id) (policy_t *this); - - /** - * @brief Get own ca. - * - * Returned object is not getting cloned. - * - * @param this calling object - * @return own ca - */ - identification_t *(*get_my_ca) (policy_t *this); - - /** - * @brief Get peer ca. - * - * Returned object is not getting cloned. - * - * @param this calling object - * @return other ca - */ - identification_t *(*get_other_ca) (policy_t *this); - - /** - * @brief Get the authentication method to use. - * - * @param this calling object - * @return authentication method - */ - auth_method_t (*get_auth_method) (policy_t *this); - - /** - * @brief Get the EAP type to use for peer authentication. - * - * @param this calling object - * @return authentication method - */ - eap_type_t (*get_eap_type) (policy_t *this); - - /** - * @brief Get configured traffic selectors for our site. - * - * Returns a list with all traffic selectors for the local - * site. List and items must be destroyed after usage. - * - * @param this calling object - * @return list with traffic selectors - */ - linked_list_t *(*get_my_traffic_selectors) (policy_t *this, host_t *me); - - /** - * @brief Get configured traffic selectors for others site. - * - * Returns a list with all traffic selectors for the remote - * site. List and items must be destroyed after usage. - * - * @param this calling object - * @return list with traffic selectors - */ - linked_list_t *(*get_other_traffic_selectors) (policy_t *this, host_t* other); - - /** - * @brief Select traffic selectors from a supplied list for local site. - * - * Resulted list and traffic selectors must be destroyed after usage. - * As the traffic selectors may contain a wildcard address (0.0.0.0) for - * addresses we don't know in previous, an address may be supplied to - * replace these 0.0.0.0 addresses on-the-fly. - * - * @param this calling object - * @param supplied linked list with traffic selectors - * @param me host address used by us - * @return list containing the selected traffic selectors - */ - linked_list_t *(*select_my_traffic_selectors) (policy_t *this, - linked_list_t *supplied, - host_t *me); - - /** - * @brief Select traffic selectors from a supplied list for remote site. - * - * Resulted list and traffic selectors must be destroyed after usage. - * As the traffic selectors may contain a wildcard address (0.0.0.0) for - * addresses we don't know in previous, an address may be supplied to - * replace these 0.0.0.0 addresses on-the-fly. - * - * @param this calling object - * @param supplied linked list with traffic selectors - * @return list containing the selected traffic selectors - */ - linked_list_t *(*select_other_traffic_selectors) (policy_t *this, - linked_list_t *supplied, - host_t *other); - - /** - * @brief Get the list of internally stored proposals. - * - * policy_t does store proposals for AH/ESP, IKE proposals are in - * the connection_t. - * Resulting list and all of its proposals must be freed after usage. - * - * @param this calling object - * @return lists with proposals - */ - linked_list_t *(*get_proposals) (policy_t *this); - - /** - * @brief Select a proposal from a supplied list. - * - * Returned propsal is newly created and must be destroyed after usage. - * - * @param this calling object - * @param proposals list from from wich proposals are selected - * @return selected proposal, or NULL if nothing matches - */ - proposal_t *(*select_proposal) (policy_t *this, linked_list_t *proposals); - - /** - * @brief Add a traffic selector to the list for local site. - * - * After add, traffic selector is owned by policy. - * - * @param this calling object - * @param traffic_selector traffic_selector to add - */ - void (*add_my_traffic_selector) (policy_t *this, traffic_selector_t *traffic_selector); - - /** - * @brief Add a traffic selector to the list for remote site. - * - * After add, traffic selector is owned by policy. - * - * @param this calling object - * @param traffic_selector traffic_selector to add - */ - void (*add_other_traffic_selector) (policy_t *this, traffic_selector_t *traffic_selector); - - /** - * @brief Add a proposal to the list. - * - * The proposals are stored by priority, first added - * is the most prefered. - * After add, proposal is owned by policy. - * - * @param this calling object - * @param proposal proposal to add - */ - void (*add_proposal) (policy_t *this, proposal_t *proposal); - - /** - * @brief Add certification authorities. - * - * @param this calling object - * @param my_ca issuer of my certificate - * @param other_ca required issuer of the peer's certificate - */ - void (*add_authorities) (policy_t *this, identification_t *my_ca, identification_t *other_ca); - - /** - * @brief Get updown script - * - * @param this calling object - * @return path to updown script - */ - char* (*get_updown) (policy_t *this); - - /** - * @brief Get hostaccess flag - * - * @param this calling object - * @return value of hostaccess flag - */ - bool (*get_hostaccess) (policy_t *this); - - /** - * @brief What should be done with a CHILD_SA, when other peer does not respond. - * - * @param this calling object - * @return dpd action - */ - dpd_action_t (*get_dpd_action) (policy_t *this); - - /** - * @brief Get the lifetime of a policy, before rekeying starts. - * - * A call to this function automatically adds a jitter to - * avoid simultanous rekeying. - * - * @param this policy - * @return lifetime in seconds - */ - u_int32_t (*get_soft_lifetime) (policy_t *this); - - /** - * @brief Get the lifetime of a policy, before SA gets deleted. - * - * @param this policy - * @return lifetime in seconds - */ - u_int32_t (*get_hard_lifetime) (policy_t *this); - - /** - * @brief Get the mode to use for the CHILD_SA, tunnel, transport or BEET. - * - * @param this policy - * @return lifetime in seconds - */ - mode_t (*get_mode) (policy_t *this); - - /** - * @brief Get a virtual IP for the local or the remote host. - * - * By supplying NULL as IP, an IP for the local host is requested. It - * may be %any or specific. - * By supplying %any as host, an IP from the pool is selected to be - * served to the peer. - * If a specified host is supplied, it is checked if this address - * is acceptable to serve to the peer. If so, it is returned. Otherwise, - * an alternative IP is returned. - * In any mode, this call may return NULL indicating virtual IP should - * not be used. - * - * @param this policy - * @param suggestion NULL, %any or specific, see description - * @return clone of an IP to use, or NULL - */ - host_t* (*get_virtual_ip) (policy_t *this, host_t *suggestion); - - /** - * @brief Get a new reference. - * - * Get a new reference to this policy by increasing - * it's internal reference counter. - * Do not call get_ref or any other function until you - * already have a reference. Otherwise the object may get - * destroyed while calling get_ref(), - * - * @param this calling object - */ - void (*get_ref) (policy_t *this); - - /** - * @brief Destroys the policy object. - * - * Decrements the internal reference counter and - * destroys the policy when it reaches zero. - * - * @param this calling object - */ - void (*destroy) (policy_t *this); -}; - -/** - * @brief Create a configuration object for IKE_AUTH and later. - * - * name-string gets cloned, ID's not. - * Virtual IPs are used if they are != NULL. A %any host means the virtual - * IP should be obtained from the other peer. - * Lifetimes are in seconds. To prevent to peers to start rekeying at the - * same time, a jitter may be specified. Rekeying of an SA starts at - * (soft_lifetime - random(0, jitter)). After a successful rekeying, - * the hard_lifetime limit counter is reset. You should specify - * hard_lifetime > soft_lifetime > jitter. - * After a call to create, a reference is obtained (refcount = 1). - * - * @param name name of the policy - * @param my_id identification_t for ourselves - * @param other_id identification_t for the remote guy - * @param my_virtual_ip virtual IP for local host, or NULL - * @param other_virtual_ip virtual IP for remote host, or NULL - * @param auth_method Authentication method to use for our(!) auth data - * @param eap_type EAP type to use for peer authentication - * @param hard_lifetime lifetime before deleting an SA - * @param soft_lifetime lifetime before rekeying an SA - * @param jitter range of randomization time - * @param updown updown script to execute on up/down event - * @param hostaccess allow access to the host itself (used by the updown script) - * @param mode mode to propose for CHILD_SA, transport, tunnel or BEET - * @param dpd_action what to to with a CHILD_SA when other peer does not respond - * @return policy_t object - * - * @ingroup config - */ -policy_t *policy_create(char *name, - identification_t *my_id, identification_t *other_id, - host_t *my_virtual_ip, host_t *other_virtual_ip, - auth_method_t auth_method, eap_type_t eap_type, - u_int32_t hard_lifetime, u_int32_t soft_lifetime, - u_int32_t jitter, char *updown, bool hostaccess, - mode_t mode, dpd_action_t dpd_action); - -#endif /* POLICY_H_ */ diff --git a/src/charon/config/policies/policy_store.h b/src/charon/config/policies/policy_store.h deleted file mode 100755 index cd8870953..000000000 --- a/src/charon/config/policies/policy_store.h +++ /dev/null @@ -1,119 +0,0 @@ -/** - * @file policy_store.h - * - * @brief Interface policy_store_t. - * - */ - -/* - * Copyright (C) 2006 Martin Willi - * Hochschule fuer Technik Rapperswil - * - * This program is free software; you can redistribute it and/or modify it - * under the terms of the GNU General Public License as published by the - * Free Software Foundation; either version 2 of the License, or (at your - * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>. - * - * This program is distributed in the hope that it will be useful, but - * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY - * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License - * for more details. - */ - -#ifndef POLICY_STORE_H_ -#define POLICY_STORE_H_ - -typedef struct policy_store_t policy_store_t; - -#include <library.h> -#include <config/policies/policy.h> -#include <utils/linked_list.h> - - -/** - * @brief The interface for a store of policy_t's. - * - * The store uses reference counting to manage their lifetime. Call - * destroy() for a policy which is returned from the store after usage. - * - * @b Constructors: - * - stroke_create() - * - * @ingroup config - */ -struct policy_store_t { - - /** - * @brief Returns a policy identified by two IDs and a set of traffic selectors. - * - * other_id must be fully qualified. my_id may be %any, as the - * other peer may not include an IDr Request. - * - * @param this calling object - * @param my_id own ID of the policy - * @param other_id others ID of the policy - * @param my_ts traffic selectors requested for local host - * @param other_ts traffic selectors requested for remote host - * @param my_host host to use for wilcards in TS compare - * @param other_host host to use for wildcards in TS compare - * @return - * - matching policy_t, if found - * - NULL otherwise - */ - policy_t *(*get_policy) (policy_store_t *this, - identification_t *my_id, identification_t *other_id, - linked_list_t *my_ts, linked_list_t *other_ts, - host_t *my_host, host_t* other_host); - - /** - * @brief Returns a policy identified by a connection name. - * - * @param this calling object - * @param name name of the policy - * @return - * - matching policy_t, if found - * - NULL otherwise - */ - policy_t *(*get_policy_by_name) (policy_store_t *this, char *name); - - /** - * @brief Add a policy to the list. - * - * The policy is owned by the store after the call. Do - * not modify nor free. - * - * @param this calling object - * @param policy policy to add - */ - void (*add_policy) (policy_store_t *this, policy_t *policy); - - /** - * @brief Delete a policy from the store. - * - * Remove a policy from the store identified by its name. - * - * @param this calling object - * @param policy policy to add - * @return - * - SUCCESS, or - * - NOT_FOUND - */ - status_t (*delete_policy) (policy_store_t *this, char *name); - - /** - * @brief Get an iterator for the stored policies. - * - * @param this calling object - * @return iterator over all stored policies - */ - iterator_t* (*create_iterator) (policy_store_t *this); - - /** - * @brief Destroys a policy_store_t object. - * - * @param this calling object - */ - void (*destroy) (policy_store_t *this); -}; - -#endif /*POLICY_STORE_H_*/ diff --git a/src/charon/config/traffic_selector.c b/src/charon/config/traffic_selector.c index 2fb012e16..b399074d1 100644 --- a/src/charon/config/traffic_selector.c +++ b/src/charon/config/traffic_selector.c @@ -167,6 +167,8 @@ static int print(FILE *stream, const struct printf_info *info, const void *const *args) { private_traffic_selector_t *this = *((private_traffic_selector_t**)(args[0])); + linked_list_t *list = *((linked_list_t**)(args[0])); + iterator_t *iterator; char addr_str[INET6_ADDRSTRLEN] = ""; char *serv_proto = NULL; u_int8_t mask; @@ -179,6 +181,24 @@ static int print(FILE *stream, const struct printf_info *info, return fprintf(stream, "(null)"); } + if (info->alt) + { + iterator = list->create_iterator(list, TRUE); + while (iterator->iterate(iterator, (void**)&this)) + { + /* call recursivly */ + written += fprintf(stream, "%R ", this); + } + iterator->destroy(iterator); + return written; + } + + if (this->dynamic) + { + return fprintf(stream, "dynamic/%d", + this->type == TS_IPV4_ADDR_RANGE ? 32 : 128); + } + if (this->type == TS_IPV4_ADDR_RANGE) { inet_ntop(AF_INET, &this->from4, addr_str, sizeof(addr_str)); diff --git a/src/charon/control/controller.c b/src/charon/control/controller.c new file mode 100644 index 000000000..e69de29bb --- /dev/null +++ b/src/charon/control/controller.c diff --git a/src/charon/control/controller.h b/src/charon/control/controller.h new file mode 100644 index 000000000..e69de29bb --- /dev/null +++ b/src/charon/control/controller.h diff --git a/src/charon/threads/stroke_interface.c b/src/charon/control/stroke_interface.c index a9074debb..ef9238658 100755 --- a/src/charon/threads/stroke_interface.c +++ b/src/charon/control/stroke_interface.c @@ -1,12 +1,12 @@ /** - * @file stroke.c + * @file stroke_interface.c * - * @brief Implementation of stroke_t. + * @brief Implementation of stroke_interface_t. * */ /* - * Copyright (C) 2006 Martin Willi + * Copyright (C) 2006-2007 Martin Willi * Hochschule fuer Technik Rapperswil * * This program is free software; you can redistribute it and/or modify it @@ -40,23 +40,23 @@ #include <crypto/x509.h> #include <crypto/ca.h> #include <crypto/crl.h> -#include <queues/jobs/initiate_job.h> -#include <queues/jobs/route_job.h> +#include <processing/jobs/initiate_job.h> +#include <processing/jobs/route_job.h> #include <utils/leak_detective.h> #define IKE_PORT 500 #define PATH_BUF 256 - +#define STROKE_THREADS 3 struct sockaddr_un socket_addr = { AF_UNIX, STROKE_SOCKET}; -typedef struct private_stroke_t private_stroke_t; +typedef struct private_stroke_interface_t private_stroke_interface_t; /** * Private data of an stroke_t object. */ -struct private_stroke_t { +struct private_stroke_interface_t { /** * Public part of stroke_t object. @@ -64,9 +64,9 @@ struct private_stroke_t { stroke_t public; /** - * Output stream (stroke console) + * backend to store configurations */ - FILE *out; + local_backend_t *backend; /** * Unix socket to listen for strokes @@ -76,7 +76,7 @@ struct private_stroke_t { /** * Thread which reads from the Socket */ - pthread_t assigned_thread; + pthread_t threads[STROKE_THREADS]; }; /** @@ -187,10 +187,12 @@ static x509_t* load_ca_certificate(const char *filename) /** * Add a connection to the configuration list */ -static void stroke_add_conn(stroke_msg_t *msg, FILE *out) +static void stroke_add_conn(private_stroke_interface_t *this, + stroke_msg_t *msg, FILE *out) { - connection_t *connection; - policy_t *policy; + ike_cfg_t *ike_cfg; + peer_cfg_t *peer_cfg; + child_cfg_t *child_cfg; identification_t *my_id, *other_id; identification_t *my_ca = NULL; identification_t *other_ca = NULL; @@ -201,6 +203,8 @@ static void stroke_add_conn(stroke_msg_t *msg, FILE *out) proposal_t *proposal; traffic_selector_t *my_ts, *other_ts; char *interface; + bool use_existing = FALSE; + iterator_t *iterator; pop_string(msg, &msg->add_conn.name); pop_string(msg, &msg->add_conn.me.address); @@ -421,67 +425,102 @@ static void stroke_add_conn(stroke_msg_t *msg, FILE *out) DBG2(DBG_CFG, " other ca:'%D'", other_ca); DBG2(DBG_CFG, " updown: '%s'", msg->add_conn.me.updown); - connection = connection_create(msg->add_conn.name, - msg->add_conn.ikev2, - msg->add_conn.me.sendcert, - msg->add_conn.other.sendcert, - my_host, other_host, - msg->add_conn.dpd.delay, - msg->add_conn.rekey.reauth, - msg->add_conn.rekey.tries, - msg->add_conn.rekey.ike_lifetime, - msg->add_conn.rekey.ike_lifetime - msg->add_conn.rekey.margin, - msg->add_conn.rekey.margin * msg->add_conn.rekey.fuzz / 100); + /* have a look for an (almost) identical peer config to reuse */ + iterator = this->backend->create_peer_cfg_iterator(this->backend); + while (iterator->iterate(iterator, (void**)&peer_cfg)) + { + ike_cfg = peer_cfg->get_ike_cfg(peer_cfg); + if (my_id->equals(my_id, peer_cfg->get_my_id(peer_cfg)) && + other_id->equals(other_id, peer_cfg->get_other_id(peer_cfg)) && + my_host->equals(my_host, ike_cfg->get_my_host(ike_cfg)) && + other_host->equals(other_host, ike_cfg->get_other_host(ike_cfg)) && + peer_cfg->get_ike_version(peer_cfg) == (msg->add_conn.ikev2 ? 2 : 1) && + peer_cfg->get_auth_method(peer_cfg) == msg->add_conn.auth_method && + peer_cfg->get_eap_type(peer_cfg) == msg->add_conn.eap_type) + { + DBG1(DBG_CFG, "reusing existing configuration '%s'", + peer_cfg->get_name(peer_cfg)); + use_existing = TRUE; + break; + } + } + iterator->destroy(iterator); - if (msg->add_conn.algorithms.ike) + if (use_existing) { - char *proposal_string; - char *strict = msg->add_conn.algorithms.ike + strlen(msg->add_conn.algorithms.ike) - 1; - - if (*strict == '!') - *strict = '\0'; - else - strict = NULL; + my_host->destroy(my_host); + my_id->destroy(my_id); + my_ca->destroy(my_ca); + other_host->destroy(other_host); + other_id->destroy(other_id); + other_ca->destroy(other_ca); + } + else + { + ike_cfg = ike_cfg_create(msg->add_conn.other.sendcert != CERT_NEVER_SEND, + my_host, other_host); - while ((proposal_string = strsep(&msg->add_conn.algorithms.ike, ","))) + if (msg->add_conn.algorithms.ike) { - proposal = proposal_create_from_string(PROTO_IKE, proposal_string); - if (proposal == NULL) + char *proposal_string; + char *strict = msg->add_conn.algorithms.ike + strlen(msg->add_conn.algorithms.ike) - 1; + + if (*strict == '!') + *strict = '\0'; + else + strict = NULL; + + while ((proposal_string = strsep(&msg->add_conn.algorithms.ike, ","))) { - DBG1(DBG_CFG, "invalid IKE proposal string: %s", proposal_string); - my_id->destroy(my_id); - other_id->destroy(other_id); - my_ts->destroy(my_ts); - other_ts->destroy(other_ts); - my_ca->destroy(my_ca); - other_ca->destroy(other_ca); - connection->destroy(connection); - return; + proposal = proposal_create_from_string(PROTO_IKE, proposal_string); + if (proposal == NULL) + { + DBG1(DBG_CFG, "invalid IKE proposal string: %s", proposal_string); + my_id->destroy(my_id); + other_id->destroy(other_id); + my_ts->destroy(my_ts); + other_ts->destroy(other_ts); + my_ca->destroy(my_ca); + other_ca->destroy(other_ca); + ike_cfg->destroy(ike_cfg); + return; + } + ike_cfg->add_proposal(ike_cfg, proposal); + } + if (!strict) + { + proposal = proposal_create_default(PROTO_IKE); + ike_cfg->add_proposal(ike_cfg, proposal); } - connection->add_proposal(connection, proposal); } - if (!strict) + else { proposal = proposal_create_default(PROTO_IKE); - connection->add_proposal(connection, proposal); + ike_cfg->add_proposal(ike_cfg, proposal); } + + + peer_cfg = peer_cfg_create(msg->add_conn.name, msg->add_conn.ikev2 ? 2 : 1, + ike_cfg, my_id, other_id, my_ca, other_ca, msg->add_conn.me.sendcert, + msg->add_conn.auth_method, msg->add_conn.eap_type, + msg->add_conn.rekey.tries, msg->add_conn.rekey.ike_lifetime, + msg->add_conn.rekey.ike_lifetime - msg->add_conn.rekey.margin, + msg->add_conn.rekey.margin * msg->add_conn.rekey.fuzz / 100, + msg->add_conn.rekey.reauth, msg->add_conn.dpd.delay, + msg->add_conn.dpd.action,my_vip, other_vip); } - else - { - proposal = proposal_create_default(PROTO_IKE); - connection->add_proposal(connection, proposal); - } - policy = policy_create(msg->add_conn.name, my_id, other_id, my_vip, other_vip, - msg->add_conn.auth_method, msg->add_conn.eap_type, - msg->add_conn.rekey.ipsec_lifetime, - msg->add_conn.rekey.ipsec_lifetime - msg->add_conn.rekey.margin, - msg->add_conn.rekey.margin * msg->add_conn.rekey.fuzz / 100, - msg->add_conn.me.updown, msg->add_conn.me.hostaccess, - msg->add_conn.mode, msg->add_conn.dpd.action); - policy->add_my_traffic_selector(policy, my_ts); - policy->add_other_traffic_selector(policy, other_ts); - policy->add_authorities(policy, my_ca, other_ca); + child_cfg = child_cfg_create( + msg->add_conn.name, msg->add_conn.rekey.ipsec_lifetime, + msg->add_conn.rekey.ipsec_lifetime - msg->add_conn.rekey.margin, + msg->add_conn.rekey.margin * msg->add_conn.rekey.fuzz / 100, + msg->add_conn.me.updown, msg->add_conn.me.hostaccess, + msg->add_conn.mode); + + peer_cfg->add_child_cfg(peer_cfg, child_cfg); + + child_cfg->add_traffic_selector(child_cfg, TRUE, my_ts); + child_cfg->add_traffic_selector(child_cfg, FALSE, other_ts); if (msg->add_conn.algorithms.esp) { @@ -499,31 +538,30 @@ static void stroke_add_conn(stroke_msg_t *msg, FILE *out) if (proposal == NULL) { DBG1(DBG_CFG, "invalid ESP proposal string: %s", proposal_string); - policy->destroy(policy); - connection->destroy(connection); + peer_cfg->destroy(peer_cfg); return; } - policy->add_proposal(policy, proposal); + child_cfg->add_proposal(child_cfg, proposal); } if (!strict) { proposal = proposal_create_default(PROTO_ESP); - policy->add_proposal(policy, proposal); + child_cfg->add_proposal(child_cfg, proposal); } } else { proposal = proposal_create_default(PROTO_ESP); - policy->add_proposal(policy, proposal); + child_cfg->add_proposal(child_cfg, proposal); } - /* add to global connection list */ - charon->connections->add_connection(charon->connections, connection); - DBG1(DBG_CFG, "added connection '%s': %H[%D]...%H[%D]", - msg->add_conn.name, my_host, my_id, other_host, other_id); - /* add to global policy list */ - charon->policies->add_policy(charon->policies, policy); - + if (!use_existing) + { + /* add config to backend */ + this->backend->add_peer_cfg(this->backend, peer_cfg); + DBG1(DBG_CFG, "added configuration '%s': %H[%D]...%H[%D]", + msg->add_conn.name, my_host, my_id, other_host, other_id); + } return; /* mopping up after parsing errors */ @@ -540,69 +578,109 @@ destroy_hosts: /** * Delete a connection from the list */ -static void stroke_del_conn(stroke_msg_t *msg, FILE *out) +static void stroke_del_conn(private_stroke_interface_t *this, + stroke_msg_t *msg, FILE *out) { - status_t status; + iterator_t *peer_iter, *child_iter; + peer_cfg_t *peer, *child; pop_string(msg, &(msg->del_conn.name)); DBG1(DBG_CFG, "received stroke: delete connection '%s'", msg->del_conn.name); - status = charon->connections->delete_connection(charon->connections, - msg->del_conn.name); - charon->policies->delete_policy(charon->policies, msg->del_conn.name); - if (status == SUCCESS) + peer_iter = this->backend->create_peer_cfg_iterator(this->backend); + while (peer_iter->iterate(peer_iter, (void**)&peer)) { - fprintf(out, "deleted connection '%s'\n", msg->del_conn.name); + /* remove peer config with such a name */ + if (streq(peer->get_name(peer), msg->del_conn.name)) + { + peer_iter->remove(peer_iter); + peer->destroy(peer); + continue; + } + /* remove any child with such a name */ + child_iter = peer->create_child_cfg_iterator(peer); + while (child_iter->iterate(child_iter, (void**)&child)) + { + if (streq(child->get_name(child), msg->del_conn.name)) + { + child_iter->remove(child_iter); + child->destroy(child); + } + } + child_iter->destroy(child_iter); } - else + peer_iter->destroy(peer_iter); + + fprintf(out, "deleted connection '%s'\n", msg->del_conn.name); +} + +/** + * get the child_cfg with the same name as the peer cfg + */ +static child_cfg_t* get_child_from_peer(peer_cfg_t *peer_cfg) +{ + child_cfg_t *current, *found = NULL; + iterator_t *iterator; + + iterator = peer_cfg->create_child_cfg_iterator(peer_cfg); + while (iterator->iterate(iterator, (void**)¤t)) { - fprintf(out, "no connection named '%s'\n", msg->del_conn.name); + if (streq(current->get_name(current), peer_cfg->get_name(peer_cfg))) + { + found = current; + found->get_ref(found); + break; + } } + iterator->destroy(iterator); + return found; } /** * initiate a connection by name */ -static void stroke_initiate(stroke_msg_t *msg, FILE *out) +static void stroke_initiate(private_stroke_interface_t *this, + stroke_msg_t *msg, FILE *out) { initiate_job_t *job; - connection_t *connection; - policy_t *policy; + peer_cfg_t *peer_cfg; + child_cfg_t *child_cfg; ike_sa_t *init_ike_sa = NULL; signal_t signal; pop_string(msg, &(msg->initiate.name)); DBG1(DBG_CFG, "received stroke: initiate '%s'", msg->initiate.name); - connection = charon->connections->get_connection_by_name(charon->connections, - msg->initiate.name); - if (connection == NULL) + peer_cfg = charon->cfg_store->get_peer_cfg_by_name(charon->cfg_store, + msg->initiate.name); + if (peer_cfg == NULL) { if (msg->output_verbosity >= 0) { - fprintf(out, "no connection named '%s'\n", msg->initiate.name); + fprintf(out, "no config named '%s'\n", msg->initiate.name); } return; } - if (!connection->is_ikev2(connection)) + if (peer_cfg->get_ike_version(peer_cfg) != 2) { - connection->destroy(connection); + DBG1(DBG_CFG, "ignoring initiation request for IKEv%d config", + peer_cfg->get_ike_version(peer_cfg)); + peer_cfg->destroy(peer_cfg); return; } - policy = charon->policies->get_policy_by_name(charon->policies, - msg->initiate.name); - if (policy == NULL) + child_cfg = get_child_from_peer(peer_cfg); + if (child_cfg == NULL) { if (msg->output_verbosity >= 0) { - fprintf(out, "no policy named '%s'\n", msg->initiate.name); + fprintf(out, "no child config named '%s'\n", msg->initiate.name); } - connection->destroy(connection); + peer_cfg->destroy(peer_cfg); return; } - job = initiate_job_create(connection, policy); + job = initiate_job_create(peer_cfg, child_cfg); charon->bus->set_listen_state(charon->bus, TRUE); charon->job_queue->add(charon->job_queue, (job_t*)job); while (TRUE) @@ -654,49 +732,48 @@ static void stroke_initiate(stroke_msg_t *msg, FILE *out) /** * route/unroute a policy (install SPD entries) */ -static void stroke_route(stroke_msg_t *msg, FILE *out, bool route) +static void stroke_route(private_stroke_interface_t *this, + stroke_msg_t *msg, FILE *out, bool route) { route_job_t *job; - connection_t *connection; - policy_t *policy; + peer_cfg_t *peer_cfg; + child_cfg_t *child_cfg; pop_string(msg, &(msg->route.name)); DBG1(DBG_CFG, "received stroke: %s '%s'", route ? "route" : "unroute", msg->route.name); - /* we wouldn't need a connection, but we only want to route policies - * whose connections are keyexchange=ikev2. */ - connection = charon->connections->get_connection_by_name(charon->connections, - msg->route.name); - if (connection == NULL) + peer_cfg = charon->cfg_store->get_peer_cfg_by_name(charon->cfg_store, + msg->route.name); + if (peer_cfg == NULL) { - fprintf(out, "no connection named '%s'\n", msg->route.name); + fprintf(out, "no config named '%s'\n", msg->route.name); return; } - if (!connection->is_ikev2(connection)) + if (peer_cfg->get_ike_version(peer_cfg) != 2) { - connection->destroy(connection); + peer_cfg->destroy(peer_cfg); return; } - - policy = charon->policies->get_policy_by_name(charon->policies, - msg->route.name); - if (policy == NULL) + + child_cfg = get_child_from_peer(peer_cfg); + if (child_cfg == NULL) { - fprintf(out, "no policy named '%s'\n", msg->route.name); - connection->destroy(connection); + fprintf(out, "no child config named '%s'\n", msg->route.name); + peer_cfg->destroy(peer_cfg); return; } fprintf(out, "%s policy '%s'\n", route ? "routing" : "unrouting", msg->route.name); - job = route_job_create(connection, policy, route); + job = route_job_create(peer_cfg, child_cfg, route); charon->job_queue->add(charon->job_queue, (job_t*)job); } /** * terminate a connection by name */ -static void stroke_terminate(stroke_msg_t *msg, FILE *out) +static void stroke_terminate(private_stroke_interface_t *this, + stroke_msg_t *msg, FILE *out) { char *string, *pos = NULL, *name = NULL; u_int32_t id = 0; @@ -797,7 +874,8 @@ static void stroke_terminate(stroke_msg_t *msg, FILE *out) /** * Add a ca information record to the cainfo list */ -static void stroke_add_ca(stroke_msg_t *msg, FILE *out) +static void stroke_add_ca(private_stroke_interface_t *this, + stroke_msg_t *msg, FILE *out) { x509_t *cacert; ca_info_t *ca_info; @@ -864,7 +942,8 @@ static void stroke_add_ca(stroke_msg_t *msg, FILE *out) /** * Delete a ca information record from the cainfo list */ -static void stroke_del_ca(stroke_msg_t *msg, FILE *out) +static void stroke_del_ca(private_stroke_interface_t *this, + stroke_msg_t *msg, FILE *out) { status_t status; @@ -887,13 +966,15 @@ static void stroke_del_ca(stroke_msg_t *msg, FILE *out) /** * show status of daemon */ -static void stroke_statusall(stroke_msg_t *msg, FILE *out) +static void stroke_statusall(private_stroke_interface_t *this, + stroke_msg_t *msg, FILE *out) { - iterator_t *iterator; + iterator_t *iterator, *children; linked_list_t *list; host_t *host; - connection_t *connection; - policy_t *policy; + peer_cfg_t *peer_cfg; + ike_cfg_t *ike_cfg; + child_cfg_t *child_cfg; ike_sa_t *ike_sa; char *name = NULL; @@ -923,40 +1004,35 @@ static void stroke_statusall(stroke_msg_t *msg, FILE *out) name = msg->status.name; } - iterator = charon->connections->create_iterator(charon->connections); - if (iterator->get_count(iterator) > 0) + fprintf(out, "Connections:\n"); + iterator = this->backend->create_peer_cfg_iterator(this->backend); + while (iterator->iterate(iterator, (void**)&peer_cfg)) { - fprintf(out, "Connections:\n"); - } - while (iterator->iterate(iterator, (void**)&connection)) - { - if (connection->is_ikev2(connection) - && (name == NULL || streq(name, connection->get_name(connection)))) + if (peer_cfg->get_ike_version(peer_cfg) != 2 || + (name && !streq(name, peer_cfg->get_name(peer_cfg)))) { - fprintf(out, "%12s: %H...%H\n", - connection->get_name(connection), - connection->get_my_host(connection), - connection->get_other_host(connection)); + continue; } - } - iterator->destroy(iterator); - - iterator = charon->policies->create_iterator(charon->policies); - if (iterator->get_count(iterator) > 0) - { - fprintf(out, "Policies:\n"); - } - while (iterator->iterate(iterator, (void**)&policy)) - { - if (name == NULL || streq(name, policy->get_name(policy))) + + ike_cfg = peer_cfg->get_ike_cfg(peer_cfg); + fprintf(out, "%12s: %H[%D]...%H[%D]\n", peer_cfg->get_name(peer_cfg), + ike_cfg->get_my_host(ike_cfg), peer_cfg->get_my_id(peer_cfg), + ike_cfg->get_other_host(ike_cfg), peer_cfg->get_other_id(peer_cfg)); + children = peer_cfg->create_child_cfg_iterator(peer_cfg); + while (children->iterate(children, (void**)&child_cfg)) { - fprintf(out, "%12s: '%D'...'%D'\n", - policy->get_name(policy), - policy->get_my_id(policy), - policy->get_other_id(policy)); + linked_list_t *my_ts, *other_ts; + my_ts = child_cfg->get_traffic_selectors(child_cfg, TRUE, NULL, NULL); + other_ts = child_cfg->get_traffic_selectors(child_cfg, FALSE, NULL, NULL); + fprintf(out, "%12s: %#R=== %#R\n", child_cfg->get_name(child_cfg), + my_ts, other_ts); + my_ts->destroy_offset(my_ts, offsetof(traffic_selector_t, destroy)); + other_ts->destroy_offset(other_ts, offsetof(traffic_selector_t, destroy)); } + children->destroy(children); } iterator->destroy(iterator); + iterator = charon->ike_sa_manager->create_iterator(charon->ike_sa_manager); if (iterator->get_count(iterator) > 0) @@ -970,7 +1046,7 @@ static void stroke_statusall(stroke_msg_t *msg, FILE *out) iterator_t *children = ike_sa->create_child_sa_iterator(ike_sa); /* print IKE_SA */ - if (name == NULL || strncmp(name, ike_sa->get_name(ike_sa), strlen(name)) == 0) + if (name == NULL || strcmp(name, ike_sa->get_name(ike_sa)) == 0) { fprintf(out, "%#K\n", ike_sa); ike_sa_printed = TRUE; @@ -979,7 +1055,7 @@ static void stroke_statusall(stroke_msg_t *msg, FILE *out) while (children->iterate(children, (void**)&child_sa)) { bool child_sa_match = name == NULL || - strncmp(name, child_sa->get_name(child_sa), strlen(name)) == 0; + strcmp(name, child_sa->get_name(child_sa)) == 0; /* print IKE_SA if its name differs from the CHILD_SA's name */ if (!ike_sa_printed && child_sa_match) @@ -1002,7 +1078,8 @@ static void stroke_statusall(stroke_msg_t *msg, FILE *out) /** * show status of daemon */ -static void stroke_status(stroke_msg_t *msg, FILE *out) +static void stroke_status(private_stroke_interface_t *this, + stroke_msg_t *msg, FILE *out) { iterator_t *iterator; ike_sa_t *ike_sa; @@ -1022,7 +1099,7 @@ static void stroke_status(stroke_msg_t *msg, FILE *out) iterator_t *children = ike_sa->create_child_sa_iterator(ike_sa); /* print IKE_SA */ - if (name == NULL || strncmp(name, ike_sa->get_name(ike_sa), strlen(name)) == 0) + if (name == NULL || strcmp(name, ike_sa->get_name(ike_sa)) == 0) { fprintf(out, "%K\n", ike_sa); ike_sa_printed = TRUE; @@ -1031,7 +1108,7 @@ static void stroke_status(stroke_msg_t *msg, FILE *out) while (children->iterate(children, (void**)&child_sa)) { bool child_sa_match = name == NULL || - strncmp(name, child_sa->get_name(child_sa), strlen(name)) == 0; + strcmp(name, child_sa->get_name(child_sa)) == 0; /* print IKE_SA if its name differs from the CHILD_SA's name */ if (!ike_sa_printed && child_sa_match) @@ -1054,7 +1131,8 @@ static void stroke_status(stroke_msg_t *msg, FILE *out) /** * list all authority certificates matching a specified flag */ -static void list_auth_certificates(u_int flag, const char *label, bool utc, FILE *out) +static void list_auth_certificates(private_stroke_interface_t *this, u_int flag, + const char *label, bool utc, FILE *out) { bool first = TRUE; x509_t *cert; @@ -1081,7 +1159,8 @@ static void list_auth_certificates(u_int flag, const char *label, bool utc, FILE /** * list various information */ -static void stroke_list(stroke_msg_t *msg, FILE *out) +static void stroke_list(private_stroke_interface_t *this, + stroke_msg_t *msg, FILE *out) { iterator_t *iterator; @@ -1111,7 +1190,7 @@ static void stroke_list(stroke_msg_t *msg, FILE *out) } if (msg->list.flags & LIST_CACERTS) { - list_auth_certificates(AUTH_CA, "CA", msg->list.utc, out); + list_auth_certificates(this, AUTH_CA, "CA", msg->list.utc, out); } if (msg->list.flags & LIST_CAINFOS) { @@ -1132,60 +1211,59 @@ static void stroke_list(stroke_msg_t *msg, FILE *out) } if (msg->list.flags & LIST_CRLS) { - ca_info_t *ca_info; - bool first = TRUE; - - iterator = charon->credentials->create_cainfo_iterator(charon->credentials); - - while (iterator->iterate(iterator, (void **)&ca_info)) - { - if (ca_info->has_crl(ca_info)) - { - if (first) - { - fprintf(out, "\n"); - fprintf(out, "List of X.509 CRLs:\n"); - fprintf(out, "\n"); - first = FALSE; - } - ca_info->list_crl(ca_info, out, msg->list.utc); - } - } - iterator->destroy(iterator); + ca_info_t *ca_info; + bool first = TRUE; + + iterator = charon->credentials->create_cainfo_iterator(charon->credentials); + while (iterator->iterate(iterator, (void **)&ca_info)) + { + if (ca_info->has_crl(ca_info)) + { + if (first) + { + fprintf(out, "\n"); + fprintf(out, "List of X.509 CRLs:\n"); + fprintf(out, "\n"); + first = FALSE; + } + ca_info->list_crl(ca_info, out, msg->list.utc); + } + } + iterator->destroy(iterator); } if (msg->list.flags & LIST_OCSPCERTS) { - list_auth_certificates(AUTH_OCSP, "OCSP", msg->list.utc, out); + list_auth_certificates(this, AUTH_OCSP, "OCSP", msg->list.utc, out); } if (msg->list.flags & LIST_OCSP) { ca_info_t *ca_info; bool first = TRUE; - iterator = charon->credentials->create_cainfo_iterator(charon->credentials); - - while (iterator->iterate(iterator, (void **)&ca_info)) - { - if (ca_info->has_certinfos(ca_info)) - { - if (first) - { - fprintf(out, "\n"); - fprintf(out, "List of OCSP responses:\n"); - first = FALSE; - } - fprintf(out, "\n"); - ca_info->list_certinfos(ca_info, out, msg->list.utc); - } - } - iterator->destroy(iterator); + iterator = charon->credentials->create_cainfo_iterator(charon->credentials); + while (iterator->iterate(iterator, (void **)&ca_info)) + { + if (ca_info->has_certinfos(ca_info)) + { + if (first) + { + fprintf(out, "\n"); + fprintf(out, "List of OCSP responses:\n"); + first = FALSE; + } + fprintf(out, "\n"); + ca_info->list_certinfos(ca_info, out, msg->list.utc); + } + } + iterator->destroy(iterator); } } /** * reread various information */ -static void stroke_reread(stroke_msg_t *msg, FILE *out) +static void stroke_reread(private_stroke_interface_t *this, + stroke_msg_t *msg, FILE *out) { if (msg->reread.flags & REREAD_CACERTS) { @@ -1204,7 +1282,8 @@ static void stroke_reread(stroke_msg_t *msg, FILE *out) /** * purge various information */ -static void stroke_purge(stroke_msg_t *msg, FILE *out) +static void stroke_purge(private_stroke_interface_t *this, + stroke_msg_t *msg, FILE *out) { if (msg->purge.flags & PURGE_OCSP) { @@ -1237,7 +1316,8 @@ signal_t get_signal_from_logtype(char *type) /** * set the verbosity debug output */ -static void stroke_loglevel(stroke_msg_t *msg, FILE *out) +static void stroke_loglevel(private_stroke_interface_t *this, + stroke_msg_t *msg, FILE *out) { signal_t signal; @@ -1259,13 +1339,12 @@ static void stroke_loglevel(stroke_msg_t *msg, FILE *out) /** * process a stroke request from the socket pointed by "fd" */ -static void stroke_process(int *fd) +static void stroke_process(private_stroke_interface_t *this, int strokefd) { stroke_msg_t *msg; u_int16_t msg_length; ssize_t bytes_read; FILE *out; - int strokefd = *fd; /* peek the length */ bytes_read = recv(strokefd, &msg_length, sizeof(msg_length), MSG_PEEK); @@ -1300,46 +1379,46 @@ static void stroke_process(int *fd) switch (msg->type) { case STR_INITIATE: - stroke_initiate(msg, out); + stroke_initiate(this, msg, out); break; case STR_ROUTE: - stroke_route(msg, out, TRUE); + stroke_route(this, msg, out, TRUE); break; case STR_UNROUTE: - stroke_route(msg, out, FALSE); + stroke_route(this, msg, out, FALSE); break; case STR_TERMINATE: - stroke_terminate(msg, out); + stroke_terminate(this, msg, out); break; case STR_STATUS: - stroke_status(msg, out); + stroke_status(this, msg, out); break; case STR_STATUS_ALL: - stroke_statusall(msg, out); + stroke_statusall(this, msg, out); break; case STR_ADD_CONN: - stroke_add_conn(msg, out); + stroke_add_conn(this, msg, out); break; case STR_DEL_CONN: - stroke_del_conn(msg, out); + stroke_del_conn(this, msg, out); break; case STR_ADD_CA: - stroke_add_ca(msg, out); + stroke_add_ca(this, msg, out); break; case STR_DEL_CA: - stroke_del_ca(msg, out); + stroke_del_ca(this, msg, out); break; case STR_LOGLEVEL: - stroke_loglevel(msg, out); + stroke_loglevel(this, msg, out); break; case STR_LIST: - stroke_list(msg, out); + stroke_list(this, msg, out); break; case STR_REREAD: - stroke_reread(msg, out); + stroke_reread(this, msg, out); break; case STR_PURGE: - stroke_purge(msg, out); + stroke_purge(this, msg, out); break; default: DBG1(DBG_CFG, "received unknown stroke"); @@ -1350,15 +1429,14 @@ static void stroke_process(int *fd) } /** - * Implementation of private_stroke_t.stroke_receive. + * Implementation of private_stroke_interface_t.stroke_receive. */ -static void stroke_receive(private_stroke_t *this) +static void stroke_receive(private_stroke_interface_t *this) { struct sockaddr_un strokeaddr; int strokeaddrlen = sizeof(strokeaddr); - int strokefd; int oldstate; - pthread_t thread; + int strokefd; /* ignore sigpipe. writing over the pipe back to the console * only fails if SIGPIPE is ignored. */ @@ -1379,24 +1457,22 @@ static void stroke_receive(private_stroke_t *this) DBG1(DBG_CFG, "accepting stroke connection failed: %m"); continue; } - - /* handle request asynchronously */ - if (pthread_create(&thread, NULL, (void*(*)(void*))stroke_process, (void*)&strokefd) != 0) - { - DBG1(DBG_CFG, "failed to spawn stroke thread: %m"); - } - /* detach so the thread terminates cleanly */ - pthread_detach(thread); + stroke_process(this, strokefd); } } /** * Implementation of stroke_t.destroy. */ -static void destroy(private_stroke_t *this) +static void destroy(private_stroke_interface_t *this) { - pthread_cancel(this->assigned_thread); - pthread_join(this->assigned_thread, NULL); + int i; + + for (i = 0; i < STROKE_THREADS; i++) + { + pthread_cancel(this->threads[i]); + pthread_join(this->threads[i], NULL); + } close(this->socket); unlink(socket_addr.sun_path); @@ -1406,14 +1482,17 @@ static void destroy(private_stroke_t *this) /* * Described in header-file */ -stroke_t *stroke_create() +stroke_t *stroke_create(local_backend_t *backend) { - private_stroke_t *this = malloc_thing(private_stroke_t); + private_stroke_interface_t *this = malloc_thing(private_stroke_interface_t); mode_t old; + int i; /* public functions */ this->public.destroy = (void (*)(stroke_t*))destroy; + this->backend = backend; + /* set up unix socket */ this->socket = socket(AF_UNIX, SOCK_STREAM, 0); if (this->socket == -1) @@ -1442,14 +1521,13 @@ stroke_t *stroke_create() return NULL; } - /* start a thread reading from the socket */ - if (pthread_create(&(this->assigned_thread), NULL, (void*(*)(void*))stroke_receive, this) != 0) + /* start threads reading from the socket */ + for (i = 0; i < STROKE_THREADS; i++) { - DBG1(DBG_CFG, "could not spawn stroke thread"); - close(this->socket); - unlink(socket_addr.sun_path); - free(this); - return NULL; + if (pthread_create(&this->threads[i], NULL, (void*(*)(void*))stroke_receive, this) != 0) + { + charon->kill(charon, "unable to create stroke thread"); + } } return (&this->public); diff --git a/src/charon/threads/stroke_interface.h b/src/charon/control/stroke_interface.h index 0def5167e..8ba81ad70 100644 --- a/src/charon/threads/stroke_interface.h +++ b/src/charon/control/stroke_interface.h @@ -25,11 +25,14 @@ typedef struct stroke_t stroke_t; +#include <config/backends/local_backend.h> + /** * @brief Stroke is a configuration and control interface which * allows other processes to modify charons behavior. * - * stroke_t allows config manipulation (as whack in pluto). + * stroke_t allows config manipulation (as whack in pluto). Configurations + * are stored in a special backend, the in-memory local_backend_t. * Messages of type stroke_msg_t's are sent over a unix socket * (/var/run/charon.ctl). * @@ -52,10 +55,11 @@ struct stroke_t { /** * @brief Create the stroke interface and listen on the socket. * - * @return stroke_t object + * @param backend backend to store received configurations + * @return stroke_t object * * @ingroup threads */ -stroke_t *stroke_create(void); +stroke_t *stroke_create(local_backend_t *backend); #endif /* STROKE_INTERFACE_H_ */ diff --git a/src/charon/daemon.c b/src/charon/daemon.c index 7671aea86..ef07d6531 100644 --- a/src/charon/daemon.c +++ b/src/charon/daemon.c @@ -42,8 +42,7 @@ #include <crypto/ca.h> #include <utils/fetcher.h> #include <config/credentials/local_credential_store.h> -#include <config/connections/local_connection_store.h> -#include <config/policies/local_policy_store.h> +#include <config/backends/local_backend.h> #include <sa/authenticators/eap/eap_method.h> @@ -179,8 +178,8 @@ static void destroy(private_daemon_t *this) DESTROY_IF(this->public.event_queue); DESTROY_IF(this->public.configuration); DESTROY_IF(this->public.credentials); - DESTROY_IF(this->public.connections); - DESTROY_IF(this->public.policies); + DESTROY_IF(this->public.cfg_store); + DESTROY_IF(this->public.local_backend); sched_yield(); /* we hope the sender could send the outstanding deletes, but * we shut down here at any cost */ @@ -264,9 +263,11 @@ static void initialize(private_daemon_t *this, bool strict, bool syslog, this->public.ike_sa_manager = ike_sa_manager_create(); this->public.job_queue = job_queue_create(); this->public.event_queue = event_queue_create(); - this->public.connections = (connection_store_t*)local_connection_store_create(); - this->public.policies = (policy_store_t*)local_policy_store_create(); this->public.credentials = (credential_store_t*)local_credential_store_create(strict); + this->public.cfg_store = cfg_store_create(); + this->public.local_backend = local_backend_create(); + this->public.cfg_store->register_backend(this->public.cfg_store, + &this->public.local_backend->backend); /* initialize fetcher_t class */ fetcher_initialize(); @@ -279,7 +280,7 @@ static void initialize(private_daemon_t *this, bool strict, bool syslog, credentials->load_secrets(credentials); /* start building threads, we are multi-threaded NOW */ - this->public.stroke = stroke_create(); + this->public.stroke = stroke_create(this->public.local_backend); this->public.sender = sender_create(); this->public.receiver = receiver_create(); this->public.scheduler = scheduler_create(); @@ -335,8 +336,8 @@ private_daemon_t *daemon_create(void) this->public.event_queue = NULL; this->public.configuration = NULL; this->public.credentials = NULL; - this->public.connections = NULL; - this->public.policies = NULL; + this->public.cfg_store = NULL; + this->public.local_backend = NULL; this->public.sender= NULL; this->public.receiver = NULL; this->public.scheduler = NULL; diff --git a/src/charon/daemon.h b/src/charon/daemon.h index 420262474..6ba676812 100644 --- a/src/charon/daemon.h +++ b/src/charon/daemon.h @@ -29,22 +29,21 @@ typedef struct daemon_t daemon_t; #include <credential_store.h> -#include <threads/sender.h> -#include <threads/receiver.h> -#include <threads/scheduler.h> -#include <threads/kernel_interface.h> -#include <threads/thread_pool.h> -#include <threads/stroke_interface.h> +#include <network/sender.h> +#include <network/receiver.h> #include <network/socket.h> +#include <processing/scheduler.h> +#include <processing/thread_pool.h> +#include <processing/job_queue.h> +#include <processing/event_queue.h> +#include <kernel/kernel_interface.h> +#include <control/stroke_interface.h> #include <bus/bus.h> #include <bus/listeners/file_logger.h> #include <bus/listeners/sys_logger.h> #include <sa/ike_sa_manager.h> -#include <queues/job_queue.h> -#include <queues/event_queue.h> -#include <config/configuration.h> -#include <config/connections/connection_store.h> -#include <config/policies/policy_store.h> +#include <config/cfg_store.h> +#include <config/backends/local_backend.h> /** * @defgroup charon charon @@ -324,12 +323,12 @@ struct daemon_t { /** * A connection_store_t instance. */ - connection_store_t *connections; + cfg_store_t *cfg_store; /** - * A policy_store_t instance. + * A backend for cfg_store using in-memory lists */ - policy_store_t *policies; + local_backend_t *local_backend; /** * A credential_store_t instance. diff --git a/src/charon/doc/Known-bugs.txt b/src/charon/doc/Known-bugs.txt deleted file mode 100644 index d32a5b2f0..000000000 --- a/src/charon/doc/Known-bugs.txt +++ /dev/null @@ -1,5 +0,0 @@ - Known bugs in charon -====================== - - - diff --git a/src/charon/doc/architecture.h b/src/charon/doc/architecture.h deleted file mode 100644 index 14b99274c..000000000 --- a/src/charon/doc/architecture.h +++ /dev/null @@ -1,56 +0,0 @@ -/** @mainpage - -@section design strongSwans overall design - -IKEv1 and IKEv2 is handled in different keying daemons. The ole IKEv1 stuff is -completely handled in pluto, as it was all the times. IKEv2 is handled in the -new keying daemon, which is called #charon. -Daemon control is done over unix sockets. Pluto uses whack, as it did for years. -Charon uses another socket interface, called stroke. Stroke uses another -format as whack and therefore is not compatible to whack. The starter utility, -wich does fast configuration parsing, speaks both the protocols, whack and -stroke. It also handles daemon startup and termination. -Pluto uses starter for some commands, for other it uses the whack utility. To be -as close to pluto as possible, charon has the same split up of commands to -starter and stroke. All commands are wrapped together in the ipsec script, which -allows transparent control of both daemons. -@verbatim - - +-----------------------------------------+ - | ipsec | - +-----+--------------+---------------+----+ - | | | - | | | - | +-----+-----+ | - +-----+----+ | | +-----+----+ - | | | starter | | | - | stroke | | | | whack | - | | +---+--+----+ | | - +------+---+ | | +--+-------+ - | | | | - +---+------+ | | +------+--+ - | | | | | | - | charon +----+ +----+ pluto | - | | | | - +-----+----+ +----+----+ - | | - +-----+----+ | - | LSF | | - +-----+----+ | - | | - +-----+----+ +----+----+ - | RAW Sock | | UDP/500 | - +----------+ +---------+ - -@endverbatim -Since IKEv2 uses the same port as IKEv1, both daemons must listen to UDP port -500. Under Linux, there is no clean way to set up two sockets at the same port. -To reslove this problem, charon uses a RAW socket, as they are used in network -sniffers. An installed Linux Socket Filter (LSF) filters out all none-IKEv2 -traffic. Pluto receives any IKE message, independant of charons behavior. -Therefore plutos behavior is changed to discard any IKEv2 traffic silently. - -To gain some reusability of the code, generic crypto and utility functions are -separeted in a shared library, libstrongswan. - -*/
\ No newline at end of file diff --git a/src/charon/doc/standards/draft-eronen-ipsec-ikev2-clarifications-09.txt b/src/charon/doc/standards/draft-eronen-ipsec-ikev2-clarifications-09.txt deleted file mode 100644 index 00f50dc31..000000000 --- a/src/charon/doc/standards/draft-eronen-ipsec-ikev2-clarifications-09.txt +++ /dev/null @@ -1,3250 +0,0 @@ - - - - -Network Working Group P. Eronen -Internet-Draft Nokia -Intended status: Informational P. Hoffman -Expires: November 5, 2006 VPN Consortium - May 4, 2006 - - - IKEv2 Clarifications and Implementation Guidelines - draft-eronen-ipsec-ikev2-clarifications-09.txt - -Status of this Memo - - By submitting this Internet-Draft, each author represents that any - applicable patent or other IPR claims of which he or she is aware - have been or will be disclosed, and any of which he or she becomes - aware will be disclosed, in accordance with Section 6 of BCP 79. - - 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 5, 2006. - -Copyright Notice - - Copyright (C) The Internet Society (2006). - -Abstract - - This document clarifies many areas of the IKEv2 specification. It - does not to introduce any changes to the protocol, but rather - provides descriptions that are less prone to ambiguous - interpretations. The purpose of this document is to encourage the - development of interoperable implementations. - - - - - -Eronen & Hoffman Expires November 5, 2006 [Page 1] - -Internet-Draft IKEv2 Clarifications May 2006 - - -Table of Contents - - 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 - 2. Creating the IKE_SA . . . . . . . . . . . . . . . . . . . . . 4 - 2.1. SPI values in IKE_SA_INIT exchange . . . . . . . . . . . . 4 - 2.2. Message IDs for IKE_SA_INIT messages . . . . . . . . . . . 5 - 2.3. Retransmissions of IKE_SA_INIT requests . . . . . . . . . 5 - 2.4. Interaction of COOKIE and INVALID_KE_PAYLOAD . . . . . . . 6 - 2.5. Invalid cookies . . . . . . . . . . . . . . . . . . . . . 8 - 3. Authentication . . . . . . . . . . . . . . . . . . . . . . . . 8 - 3.1. Data included in AUTH payload calculation . . . . . . . . 8 - 3.2. Hash function for RSA signatures . . . . . . . . . . . . . 9 - 3.3. Encoding method for RSA signatures . . . . . . . . . . . . 10 - 3.4. Identification type for EAP . . . . . . . . . . . . . . . 10 - 3.5. Identity for policy lookups when using EAP . . . . . . . . 11 - 3.6. Certificate encoding types . . . . . . . . . . . . . . . . 11 - 3.7. Shared key authentication and fixed PRF key size . . . . . 12 - 3.8. EAP authentication and fixed PRF key size . . . . . . . . 13 - 3.9. Matching ID payloads to certificate contents . . . . . . . 13 - 3.10. Message IDs for IKE_AUTH messages . . . . . . . . . . . . 13 - 4. Creating CHILD_SAs . . . . . . . . . . . . . . . . . . . . . . 13 - 4.1. Creating SAs with the CREATE_CHILD_SA exchange . . . . . . 13 - 4.2. Creating an IKE_SA without a CHILD_SA . . . . . . . . . . 16 - 4.3. Diffie-Hellman for first CHILD_SA . . . . . . . . . . . . 16 - 4.4. Extended Sequence Numbers (ESN) transform . . . . . . . . 16 - 4.5. Negotiation of ESP_TFC_PADDING_NOT_SUPPORTED . . . . . . . 17 - 4.6. Negotiation of NON_FIRST_FRAGMENTS_ALSO . . . . . . . . . 17 - 4.7. Semantics of complex traffic selector payloads . . . . . . 18 - 4.8. ICMP type/code in traffic selector payloads . . . . . . . 18 - 4.9. Mobility header in traffic selector payloads . . . . . . . 19 - 4.10. Narrowing the traffic selectors . . . . . . . . . . . . . 20 - 4.11. SINGLE_PAIR_REQUIRED . . . . . . . . . . . . . . . . . . . 20 - 4.12. Traffic selectors violating own policy . . . . . . . . . . 21 - 4.13. Traffic selector authorization . . . . . . . . . . . . . . 21 - 5. Rekeying and deleting SAs . . . . . . . . . . . . . . . . . . 22 - 5.1. Rekeying SAs with the CREATE_CHILD_SA exchange . . . . . . 23 - 5.2. Rekeying the IKE_SA vs. reauthentication . . . . . . . . . 24 - 5.3. SPIs when rekeying the IKE_SA . . . . . . . . . . . . . . 25 - 5.4. SPI when rekeying a CHILD_SA . . . . . . . . . . . . . . . 25 - 5.5. Changing PRFs when rekeying the IKE_SA . . . . . . . . . . 25 - 5.6. Deleting vs. closing SAs . . . . . . . . . . . . . . . . . 25 - 5.7. Deleting a CHILD_SA pair . . . . . . . . . . . . . . . . . 26 - 5.8. Deleting an IKE_SA . . . . . . . . . . . . . . . . . . . . 26 - 5.9. Who is the original initiator of IKE_SA . . . . . . . . . 26 - 5.10. Comparing nonces . . . . . . . . . . . . . . . . . . . . . 27 - 5.11. Exchange collisions . . . . . . . . . . . . . . . . . . . 27 - 5.12. Diffie-Hellman and rekeying the IKE_SA . . . . . . . . . . 36 - 6. Configuration payloads . . . . . . . . . . . . . . . . . . . . 36 - - - -Eronen & Hoffman Expires November 5, 2006 [Page 2] - -Internet-Draft IKEv2 Clarifications May 2006 - - - 6.1. Assigning IP addresses . . . . . . . . . . . . . . . . . . 36 - 6.2. Requesting any INTERNAL_IP4/IP6_ADDRESS . . . . . . . . . 37 - 6.3. INTERNAL_IP4_SUBNET/INTERNAL_IP6_SUBNET . . . . . . . . . 38 - 6.4. INTERNAL_IP4_NETMASK . . . . . . . . . . . . . . . . . . . 40 - 6.5. Configuration payloads for IPv6 . . . . . . . . . . . . . 41 - 6.6. INTERNAL_IP6_NBNS . . . . . . . . . . . . . . . . . . . . 43 - 6.7. INTERNAL_ADDRESS_EXPIRY . . . . . . . . . . . . . . . . . 43 - 6.8. Address assignment failures . . . . . . . . . . . . . . . 43 - 7. Miscellaneous issues . . . . . . . . . . . . . . . . . . . . . 44 - 7.1. Matching ID_IPV4_ADDR and ID_IPV6_ADDR . . . . . . . . . . 44 - 7.2. Relationship of IKEv2 to RFC4301 . . . . . . . . . . . . . 44 - 7.3. Reducing the window size . . . . . . . . . . . . . . . . . 45 - 7.4. Minimum size of nonces . . . . . . . . . . . . . . . . . . 45 - 7.5. Initial zero octets on port 4500 . . . . . . . . . . . . . 45 - 7.6. Destination port for NAT traversal . . . . . . . . . . . . 46 - 7.7. SPI values for messages outside of an IKE_SA . . . . . . . 46 - 7.8. Protocol ID/SPI fields in Notify payloads . . . . . . . . 47 - 7.9. Which message should contain INITIAL_CONTACT . . . . . . . 47 - 7.10. Alignment of payloads . . . . . . . . . . . . . . . . . . 47 - 7.11. Key length transform attribute . . . . . . . . . . . . . . 48 - 7.12. IPsec IANA considerations . . . . . . . . . . . . . . . . 48 - 7.13. Combining ESP and AH . . . . . . . . . . . . . . . . . . . 49 - 8. Implementation mistakes . . . . . . . . . . . . . . . . . . . 49 - 9. Security considerations . . . . . . . . . . . . . . . . . . . 50 - 10. IANA considerations . . . . . . . . . . . . . . . . . . . . . 50 - 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 50 - 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 50 - 12.1. Normative References . . . . . . . . . . . . . . . . . . . 50 - 12.2. Informative References . . . . . . . . . . . . . . . . . . 51 - Appendix A. Exchanges and payloads . . . . . . . . . . . . . . . 53 - A.1. IKE_SA_INIT exchange . . . . . . . . . . . . . . . . . . . 53 - A.2. IKE_AUTH exchange without EAP . . . . . . . . . . . . . . 54 - A.3. IKE_AUTH exchange with EAP . . . . . . . . . . . . . . . . 55 - A.4. CREATE_CHILD_SA exchange for creating/rekeying - CHILD_SAs . . . . . . . . . . . . . . . . . . . . . . . . 56 - A.5. CREATE_CHILD_SA exchange for rekeying the IKE_SA . . . . . 56 - A.6. INFORMATIONAL exchange . . . . . . . . . . . . . . . . . . 56 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 56 - Intellectual Property and Copyright Statements . . . . . . . . . . 58 - - - - - - - - - - - - -Eronen & Hoffman Expires November 5, 2006 [Page 3] - -Internet-Draft IKEv2 Clarifications May 2006 - - -1. Introduction - - This document clarifies many areas of the IKEv2 specification that - may be difficult to understand to developers not intimately familiar - with the specification and its history. The clarifications in this - document come from the discussion on the IPsec WG mailing list, from - experience in interoperability testing, and from implementation - issues that have been brought to the editors' attention. - - IKEv2/IPsec can be used for several different purposes, including - IPsec-based remote access (sometimes called the "road warrior" case), - site-to-site virtual private networks (VPNs), and host-to-host - protection of application traffic. While this document attempts to - consider all of these uses, the remote access scenario has perhaps - received more attention here than the other uses. - - This document does not place any requirements on anyone, and does not - use [RFC2119] keywords such as "MUST" and "SHOULD", except in - quotations from the original IKEv2 documents. The requirements are - given in the IKEv2 specification [IKEv2] and IKEv2 cryptographic - algorithms document [IKEv2ALG]. - - In this document, references to a numbered section (such as "Section - 2.15") mean that section in [IKEv2]. References to mailing list - messages or threads refer to the IPsec WG mailing list at - ipsec@ietf.org. Archives of the mailing list can be found at - <http://www.ietf.org/mail-archive/web/ipsec/index.html>. - - -2. Creating the IKE_SA - -2.1. SPI values in IKE_SA_INIT exchange - - Normal IKE messages include the initiator's and responder's SPIs, - both of which are non-zero, in the IKE header. However, there are - some corner cases where the IKEv2 specification is not fully - consistent about what values should be used. - - First, Section 3.1 says that the Responder's SPI "...MUST NOT be zero - in any other message" (than the first message of the IKE_SA_INIT - exchange). However, the figure in Section 2.6 shows the second - IKE_SA_INIT message as "HDR(A,0), N(COOKIE)", contradicting the text - in 3.1. - - Since the responder's SPI identifies security-related state held by - the responder, and in this case no state is created, sending a zero - value seems reasonable. - - - - -Eronen & Hoffman Expires November 5, 2006 [Page 4] - -Internet-Draft IKEv2 Clarifications May 2006 - - - Second, in addition to cookies, there are several other cases when - the IKE_SA_INIT exchange does not result in the creation of an IKE_SA - (for instance, INVALID_KE_PAYLOAD or NO_PROPOSAL_CHOSEN). What - responder SPI value should be used in the IKE_SA_INIT response in - this case? - - Since the IKE_SA_INIT request always has a zero responder SPI, the - value will not be actually used by the initiator. Thus, we think - sending a zero value is correct also in this case. - - If the responder sends a non-zero responder SPI, the initiator should - not reject the response only for that reason. However, when retrying - the IKE_SA_INIT request, the initiator will use a zero responder SPI, - as described in Section 3.1: "Responder's SPI [...] This value MUST - be zero in the first message of an IKE Initial Exchange (including - repeats of that message including a cookie) [...]". We believe the - intent was to cover repeats of that message due to other reasons, - such as INVALID_KE_PAYLOAD, as well. - - (References: "INVALID_KE_PAYLOAD and clarifications document" thread, - Sep-Oct 2005.) - -2.2. Message IDs for IKE_SA_INIT messages - - The Message ID for IKE_SA_INIT messages is always zero. This - includes retries of the message due to responses such as COOKIE and - INVALID_KE_PAYLOAD. - - This is because Message IDs are part of the IKE_SA state, and when - the responder replies to IKE_SA_INIT request with N(COOKIE) or - N(INVALID_KE_PAYLOAD), the responder does not allocate any state. - - (References: "Question about N(COOKIE) and N(INVALID_KE_PAYLOAD) - combination" thread, Oct 2004. Tero Kivinen's mail "Comments of - draft-eronen-ipsec-ikev2-clarifications-02.txt", 2005-04-05.) - -2.3. Retransmissions of IKE_SA_INIT requests - - When a responder receives an IKE_SA_INIT request, it has to determine - whether the packet is a retransmission belonging to an existing - "half-open" IKE_SA (in which case the responder retransmits the same - response), or a new request (in which case the responder creates a - new IKE_SA and sends a fresh response). - - The specification does not describe in detail how this determination - is done. In particular, it is not sufficient to use the initiator's - SPI and/or IP address for this purpose: two different peers behind a - single NAT could choose the same initiator SPI (and the probability - - - -Eronen & Hoffman Expires November 5, 2006 [Page 5] - -Internet-Draft IKEv2 Clarifications May 2006 - - - of this happening is not necessarily small, since IKEv2 does not - require SPIs to be chosen randomly). Instead, the responder should - do the IKE_SA lookup using the whole packet or its hash (or at the - minimum, the Ni payload which is always chosen randomly). - - For all other packets than IKE_SA_INIT requests, looking up right - IKE_SA is of course done based on the recipient's SPI (either the - initiator or responder SPI depending on the value of the Initiator - bit in the IKE header). - -2.4. Interaction of COOKIE and INVALID_KE_PAYLOAD - - There are two common reasons why the initiator may have to retry the - IKE_SA_INIT exchange: the responder requests a cookie or wants a - different Diffie-Hellman group than was included in the KEi payload. - Both of these cases are quite simple alone, but it is not totally - obvious what happens when they occur at the same time, that is, the - IKE_SA_INIT exchange is retried several times. - - The main question seems to be the following: if the initiator - receives a cookie from the responder, should it include the cookie in - only the next retry of the IKE_SA_INIT request, or in all subsequent - retries as well? Section 3.10.1 says that: - - "This notification MUST be included in an IKE_SA_INIT request - retry if a COOKIE notification was included in the initial - response." - - This could be interpreted as saying that when a cookie is received in - the initial response, it is included in all retries. On the other - hand, Section 2.6 says that: - - "Initiators who receive such responses MUST retry the - IKE_SA_INIT with a Notify payload of type COOKIE containing - the responder supplied cookie data as the first payload and - all other payloads unchanged." - - Including the same cookie in later retries makes sense only if the - "all other payloads unchanged" restriction applies only to the first - retry, but not to subsequent retries. - - It seems that both interpretations can peacefully co-exist. If the - initiator includes the cookie only in the next retry, one additional - roundtrip may be needed in some cases: - - - - - - - -Eronen & Hoffman Expires November 5, 2006 [Page 6] - -Internet-Draft IKEv2 Clarifications May 2006 - - - Initiator Responder - ----------- ----------- - HDR(A,0), SAi1, KEi, Ni --> - <-- HDR(A,0), N(COOKIE) - HDR(A,0), N(COOKIE), SAi1, KEi, Ni --> - <-- HDR(A,0), N(INVALID_KE_PAYLOAD) - HDR(A,0), SAi1, KEi', Ni --> - <-- HDR(A,0), N(COOKIE') - HDR(A,0), N(COOKIE'), SAi1, KEi',Ni --> - <-- HDR(A,B), SAr1, KEr, Nr - - An additional roundtrip is needed also if the initiator includes the - cookie in all retries, but the responder does not support this - functionality. For instance, if the responder includes the SAi1 and - KEi payloads in cookie calculation, it will reject the request by - sending a new cookie (see also Section 2.5 of this document for more - text about invalid cookies): - - Initiator Responder - ----------- ----------- - HDR(A,0), SAi1, KEi, Ni --> - <-- HDR(A,0), N(COOKIE) - HDR(A,0), N(COOKIE), SAi1, KEi, Ni --> - <-- HDR(A,0), N(INVALID_KE_PAYLOAD) - HDR(A,0), N(COOKIE), SAi1, KEi', Ni --> - <-- HDR(A,0), N(COOKIE') - HDR(A,0), N(COOKIE'), SAi1, KEi',Ni --> - <-- HDR(A,B), SAr1, KEr, Nr - - If both peers support including the cookie in all retries, a slightly - shorter exchange can happen: - - Initiator Responder - ----------- ----------- - HDR(A,0), SAi1, KEi, Ni --> - <-- HDR(A,0), N(COOKIE) - HDR(A,0), N(COOKIE), SAi1, KEi, Ni --> - <-- HDR(A,0), N(INVALID_KE_PAYLOAD) - HDR(A,0), N(COOKIE), SAi1, KEi', Ni --> - <-- HDR(A,B), SAr1, KEr, Nr - - This document recommends that implementations should support this - shorter exchange, but it must not be assumed the other peer also - supports the shorter exchange. - - - - - - - -Eronen & Hoffman Expires November 5, 2006 [Page 7] - -Internet-Draft IKEv2 Clarifications May 2006 - - - In theory, even this exchange has one unnecessary roundtrip, as both - the cookie and Diffie-Hellman group could be checked at the same - time: - - Initiator Responder - ----------- ----------- - HDR(A,0), SAi1, KEi, Ni --> - <-- HDR(A,0), N(COOKIE), - N(INVALID_KE_PAYLOAD) - HDR(A,0), N(COOKIE), SAi1, KEi',Ni --> - <-- HDR(A,B), SAr1, KEr, Nr - - However, it is clear that this case is not allowed by the text in - Section 2.6, since "all other payloads" clearly includes the KEi - payload as well. - - (References: "INVALID_KE_PAYLOAD and clarifications document" thread, - Sep-Oct 2005.) - -2.5. Invalid cookies - - There has been some confusion what should be done when an IKE_SA_INIT - request containing an invalid cookie is received ("invalid" in the - sense that its contents do not match the value expected by the - responder). - - The correct action is to ignore the cookie, and process the message - as if no cookie had been included (usually this means sending a - response containing a new cookie). This is shown in Section 2.6 when - it says "The responder in that case MAY reject the message by sending - another response with a new cookie [...]". - - Other possible actions, such as ignoring the whole request (or even - all requests from this IP address for some time), create strange - failure modes even in the absence of any malicious attackers, and do - not provide any additional protection against DoS attacks. - - (References: "Invalid Cookie" thread, Sep-Oct 2005.) - - -3. Authentication - -3.1. Data included in AUTH payload calculation - - Section 2.15 describes how the AUTH payloads are calculated; this - calculation involves values prf(SK_pi,IDi') and prf(SK_pr,IDr'). The - text describes the method in words, but does not give clear - definitions of what is signed or MACed. - - - -Eronen & Hoffman Expires November 5, 2006 [Page 8] - -Internet-Draft IKEv2 Clarifications May 2006 - - - The initiator's signed octets can be described as: - - InitiatorSignedOctets = RealMessage1 | NonceRData | MACedIDForI - GenIKEHDR = [ four octets 0 if using port 4500 ] | RealIKEHDR - RealIKEHDR = SPIi | SPIr | . . . | Length - RealMessage1 = RealIKEHDR | RestOfMessage1 - NonceRPayload = PayloadHeader | NonceRData - InitiatorIDPayload = PayloadHeader | RestOfIDPayload - RestOfInitIDPayload = IDType | RESERVED | InitIDData - MACedIDForI = prf(SK_pi, RestOfInitIDPayload) - - The responder's signed octets can be described as: - - ResponderSignedOctets = RealMessage2 | NonceIData | MACedIDForR - GenIKEHDR = [ four octets 0 if using port 4500 ] | RealIKEHDR - RealIKEHDR = SPIi | SPIr | . . . | Length - RealMessage2 = RealIKEHDR | RestOfMessage2 - NonceIPayload = PayloadHeader | NonceIData - ResponderIDPayload = PayloadHeader | RestOfIDPayload - RestOfRespIDPayload = IDType | RESERVED | InitIDData - MACedIDForR = prf(SK_pr, RestOfRespIDPayload) - -3.2. Hash function for RSA signatures - - Section 3.8 says that RSA digital signature is "Computed as specified - in section 2.15 using an RSA private key over a PKCS#1 padded hash." - - Unlike IKEv1, IKEv2 does not negotiate a hash function for the - IKE_SA. The algorithm for signatures is selected by the signing - party who, in general, may not know beforehand what algorithms the - verifying party supports. Furthermore, [IKEv2ALG] does not say what - algorithms implementations are required or recommended to support. - This clearly has a potential for causing interoperability problems, - since authentication will fail if the signing party selects an - algorithm that is not supported by the verifying party, or not - acceptable according to the verifying party's policy. - - This document recommends that all implementations support SHA-1, and - use SHA-1 as the default hash function when generating the - signatures, unless there are good reasons (such as explicit manual - configuration) to believe that the peer supports something else. - - Note that hash function collision attacks are not important for the - AUTH payloads, since they are not intended for third-party - verification, and the data includes fresh nonces. See [HashUse] for - more discussion about hash function attacks and IPsec. - - Another reasonable choice would be to use the hash function that was - - - -Eronen & Hoffman Expires November 5, 2006 [Page 9] - -Internet-Draft IKEv2 Clarifications May 2006 - - - used by the CA when signing the peer certificate. However, this does - not guarantee that the IKEv2 peer would be able to validate the AUTH - payload, because the same code might not be used to validate - certificate signatures and IKEv2 message signatures, and these two - routines may support a different set of hash algorithms. The peer - could be configured with a fingerprint of the certificate, or - certificate validation could be performed by an external entity using - [SCVP]. Furthermore, not all CERT payloads types include a - signature, and the certificate could be signed with some algorithm - other than RSA. - - Note that unlike IKEv1, IKEv2 uses the PKCS#1 v1.5 [PKCS1v20] - signature encoding method (see next section for details), which - includes the algorithm identifier for the hash algorithm. Thus, when - the verifying party receives the AUTH payload it can at least - determine which hash function was used. - - (References: Magnus Nystrom's mail "RE:", 2005-01-03. Pasi Eronen's - reply, 2005-01-04. Tero Kivinen's reply, 2005-01-04. "First draft - of IKEv2.1" thread, Dec 2005/Jan 2006.) - -3.3. Encoding method for RSA signatures - - Section 3.8 says that the RSA digital signature is "Computed as - specified in section 2.15 using an RSA private key over a PKCS#1 - padded hash." - - The PKCS#1 specification [PKCS1v21] defines two different encoding - methods (ways of "padding the hash") for signatures. However, the - Internet-Draft approved by the IESG had a reference to the older - PKCS#1 v2.0 [PKCS1v20]. That version has only one encoding method - for signatures (EMSA-PKCS1-v1_5), and thus there is no ambiguity. - - Note that this encoding method is different from the encoding method - used in IKEv1. If future revisions of IKEv2 provide support for - other encoding methods (such as EMSA-PSS), they will be given new - Auth Method numbers. - - (References: Pasi Eronen's mail "RE:", 2005-01-04.) - -3.4. Identification type for EAP - - Section 3.5 defines several different types for identification - payloads, including, e.g., ID_FQDN, ID_RFC822_ADDR, and ID_KEY_ID. - EAP [EAP] does not mandate the use of any particular type of - identifier, but often EAP is used with Network Access Identifiers - (NAIs) defined in [NAI]. Although NAIs look a bit like email - addresses (e.g., "joe@example.com"), the syntax is not exactly the - - - -Eronen & Hoffman Expires November 5, 2006 [Page 10] - -Internet-Draft IKEv2 Clarifications May 2006 - - - same as the syntax of email address in [RFC822]. This raises the - question of which identification type should be used. - - This document recommends that ID_RFC822_ADDR identification type is - used for those NAIs that include the realm component. Therefore, - responder implementations should not attempt to verify that the - contents actually conform to the exact syntax given in [RFC822] or - [RFC2822], but instead should accept any reasonable looking NAI. - - For NAIs that do not include the realm component, this document - recommends using the ID_KEY_ID identification type. - - (References: "need your help on this IKEv2/i18n/EAP issue" and "IKEv2 - identifier issue with EAP" threads, Aug 2004.) - -3.5. Identity for policy lookups when using EAP - - When the initiator authentication uses EAP, it is possible that the - contents of the IDi payload is used only for AAA routing purposes and - selecting which EAP method to use. This value may be different from - the identity authenticated by the EAP method (see [EAP], Sections 5.1 - and 7.3). - - It is important that policy lookups and access control decisions use - the actual authenticated identity. Often the EAP server is - implemented in a separate AAA server that communicates with the IKEv2 - responder using, e.g., RADIUS [RADEAP]. In this case, the - authenticated identity has to be sent from the AAA server to the - IKEv2 responder. - - (References: Pasi Eronen's mail "RE: Reauthentication in IKEv2", - 2004-10-28. "Policy lookups" thread, Oct/Nov 2004. RFC 3748, - Section 7.3.) - -3.6. Certificate encoding types - - Section 3.6 defines a total of twelve different certificate encoding - types, and continues that "Specific syntax is for some of the - certificate type codes above is not defined in this document." - However, the text does not provide references to other documents that - would contain information about the exact contents and use of those - values. - - - - - - - - - -Eronen & Hoffman Expires November 5, 2006 [Page 11] - -Internet-Draft IKEv2 Clarifications May 2006 - - - Without this information, it is not possible to develop interoperable - implementations. Therefore, this document recommends that the - following certificate encoding values should not be used before new - specifications that specify their use are available. - - PKCS #7 wrapped X.509 certificate 1 - PGP Certificate 2 - DNS Signed Key 3 - Kerberos Token 6 - SPKI Certificate 9 - - This document recommends that most implementations should use only - those values that are "MUST"/"SHOULD" requirements in [IKEv2]; i.e., - "X.509 Certificate - Signature" (4), "Raw RSA Key" (11), "Hash and - URL of X.509 certificate" (12), and "Hash and URL of X.509 bundle" - (13). - - Furthermore, Section 3.7 says that the "Certificate Encoding" field - for the Certificate Request payload uses the same values as for - Certificate payload. However, the contents of the "Certification - Authority" field are defined only for X.509 certificates (presumably - covering at least types 4, 10, 12, and 13). This document recommends - that other values should not be used before new specifications that - specify their use are available. - - The "Raw RSA Key" type needs one additional clarification. Section - 3.6 says it contains "a PKCS #1 encoded RSA key". What this means is - a DER-encoded RSAPublicKey structure from PKCS#1 [PKCS1v21]. - -3.7. Shared key authentication and fixed PRF key size - - Section 2.15 says that "If the negotiated prf takes a fixed-size key, - the shared secret MUST be of that fixed size". This statement is - correct: the shared secret must be of the correct size. If it is - not, it cannot be used; there is no padding, truncation, or other - processing involved to force it to that correct size. - - This requirement means that it is difficult to use these PRFs with - shared key authentication. The authors think this part of the - specification was very poorly thought out, and using PRFs with a - fixed key size is likely to result in interoperability problems. - Thus, we recommend that such PRFs should not be used with shared key - authentication. PRF_AES128_XCBC [RFC3664] originally used fixed key - sizes; that RFC has been updated to handle variable key sizes in - [RFC3664bis]. - - Note that Section 2.13 also contains text that is related to PRFs - with fixed key size: "When the key for the prf function has fixed - - - -Eronen & Hoffman Expires November 5, 2006 [Page 12] - -Internet-Draft IKEv2 Clarifications May 2006 - - - length, the data provided as a key is truncated or padded with zeros - as necessary unless exceptional processing is explained following the - formula". However, this text applies only to the prf+ construction, - so it does not contradict the text in Section 2.15. - - (References: Paul Hoffman's mail "Re: ikev2-07: last nits", - 2003-05-02. Hugo Krawczyk's reply, 2003-05-12. Thread "Question - about PRFs with fixed size key", Jan 2005.) - -3.8. EAP authentication and fixed PRF key size - - As described in the previous section, PRFs with a fixed key size - require a shared secret of exactly that size. This restriction - applies also to EAP authentication. For instance, a PRF that - requires a 128-bit key cannot be used with EAP since [EAP] specifies - that the MSK is at least 512 bits long. - - (References: Thread "Question about PRFs with fixed size key", Jan - 2005.) - -3.9. Matching ID payloads to certificate contents - - In IKEv1, there was some confusion about whether or not the - identities in certificates used to authenticate IKE were required to - match the contents of the ID payloads. The PKI4IPsec Working Group - produced the document [PKI4IPsec] which covers this topic in much - more detail. However, Section 3.5 of [IKEv2] explicitly says that - the ID payload "does not necessarily have to match anything in the - CERT payload". - -3.10. Message IDs for IKE_AUTH messages - - According to Section 2.2, "The IKE_SA initial setup messages will - always be numbered 0 and 1." That is true when the IKE_AUTH exchange - does not use EAP. When EAP is used, each pair of messages has their - message numbers incremented. The first pair of AUTH messages will - have an ID of 1, the second will be 2, and so on. - - (References: "Question about MsgID in AUTH exchange" thread, April - 2005.) - - -4. Creating CHILD_SAs - -4.1. Creating SAs with the CREATE_CHILD_SA exchange - - Section 1.3's organization does not lead to clear understanding of - what is needed in which environment. The section can be reorganized - - - -Eronen & Hoffman Expires November 5, 2006 [Page 13] - -Internet-Draft IKEv2 Clarifications May 2006 - - - with subsections for each use of the CREATE_CHILD_SA exchange - (creating child SAs, rekeying IKE SAs, and rekeying child SAs.) - - The new Section 1.3 with subsections and the above changes might look - like the following. - - NEW-1.3 The CREATE_CHILD_SA Exchange - - The CREATE_CHILD_SA Exchange is used to create new CHILD_SAs and - to rekey both IKE_SAs and CHILD_SAs. This exchange consists of - a single request/response pair, and some of its function was - referred to as a phase 2 exchange in IKEv1. It MAY be initiated - by either end of the IKE_SA after the initial exchanges are - completed. - - All messages following the initial exchange are - cryptographically protected using the cryptographic algorithms - and keys negotiated in the first two messages of the IKE - exchange. These subsequent messages use the syntax of the - Encrypted Payload described in section 3.14. All subsequent - messages include an Encrypted Payload, even if they are referred - to in the text as "empty". - - The CREATE_CHILD_SA is used for rekeying IKE_SAs and CHILD_SAs. - This section describes the first part of rekeying, the creation - of new SAs; Section 2.8 covers the mechanics of rekeying, - including moving traffic from old to new SAs and the deletion of - the old SAs. The two sections must be read together to - understand the entire process of rekeying. - - Either endpoint may initiate a CREATE_CHILD_SA exchange, so in - this section the term initiator refers to the endpoint - initiating this exchange. An implementation MAY refuse all - CREATE_CHILD_SA requests within an IKE_SA. - - The CREATE_CHILD_SA request MAY optionally contain a KE payload - for an additional Diffie-Hellman exchange to enable stronger - guarantees of forward secrecy for the CHILD_SA or IKE_SA. The - keying material for the SA is a function of SK_d established - during the establishment of the IKE_SA, the nonces exchanged - during the CREATE_CHILD_SA exchange, and the Diffie-Hellman - value (if KE payloads are included in the CREATE_CHILD_SA - exchange). The details are described in sections 2.17 and 2.18. - - If a CREATE_CHILD_SA exchange includes a KEi payload, at least - one of the SA offers MUST include the Diffie-Hellman group of - the KEi. The Diffie-Hellman group of the KEi MUST be an element - of the group the initiator expects the responder to accept - - - -Eronen & Hoffman Expires November 5, 2006 [Page 14] - -Internet-Draft IKEv2 Clarifications May 2006 - - - (additional Diffie-Hellman groups can be proposed). If the - responder rejects the Diffie-Hellman group of the KEi payload, - the responder MUST reject the request and indicate its preferred - Diffie-Hellman group in the INVALID_KE_PAYLOAD Notification - payload. In the case of such a rejection, the CREATE_CHILD_SA - exchange fails, and the initiator SHOULD retry the exchange with - a Diffie-Hellman proposal and KEi in the group that the - responder gave in the INVALID_KE_PAYLOAD. - - NEW-1.3.1 Creating New CHILD_SAs with the CREATE_CHILD_SA Exchange - - A CHILD_SA may be created by sending a CREATE_CHILD_SA request. - The CREATE_CHILD_SA request for creating a new CHILD_SA is: - - Initiator Responder - ----------- ----------- - HDR, SK {[N+], SA, Ni, [KEi], - TSi, TSr} --> - - The initiator sends SA offer(s) in the SA payload, a nonce in - the Ni payload, optionally a Diffie-Hellman value in the KEi - payload, and the proposed traffic selectors for the proposed - CHILD_SA in the TSi and TSr payloads. The request can also - contain Notify payloads that specify additional details for the - CHILD_SA: these include IPCOMP_SUPPORTED, USE_TRANSPORT_MODE, - ESP_TFC_PADDING_NOT_SUPPORTED, and NON_FIRST_FRAGMENTS_ALSO. - - The CREATE_CHILD_SA response for creating a new CHILD_SA is: - - <-- HDR, SK {[N+], SA, Nr, - [KEr], TSi, TSr} - - The responder replies with the accepted offer in an SA payload, - and a Diffie-Hellman value in the KEr payload if KEi was - included in the request and the selected cryptographic suite - includes that group. As with the request, optional Notification - payloads can specify additional details for the CHILD_SA. - - The traffic selectors for traffic to be sent on that SA are - specified in the TS payloads in the response, which may be a - subset of what the initiator of the CHILD_SA proposed. - - The text about rekeying SAs can be found in Section 5.1 of this - document. - - - - - - - -Eronen & Hoffman Expires November 5, 2006 [Page 15] - -Internet-Draft IKEv2 Clarifications May 2006 - - -4.2. Creating an IKE_SA without a CHILD_SA - - CHILD_SAs can be created either by being piggybacked on the IKE_AUTH - exchange, or using a separate CREATE_CHILD_SA exchange. The - specification is not clear about what happens if creating the - CHILD_SA during the IKE_AUTH exchange fails for some reason. - - Our recommendation in this sitation is that the IKE_SA is created as - usual. This is also in line with how the CREATE_CHILD_SA exchange - works: a failure to create a CHILD_SA does not close the IKE_SA. - - The list of responses in the IKE_AUTH exchange that do not prevent an - IKE_SA from being set up include at least the following: - NO_PROPOSAL_CHOSEN, TS_UNACCEPTABLE, SINGLE_PAIR_REQUIRED, - INTERNAL_ADDRESS_FAILURE, and FAILED_CP_REQUIRED. - - (References: "Questions about internal address" thread, April, 2005.) - -4.3. Diffie-Hellman for first CHILD_SA - - Section 1.2 shows that IKE_AUTH messages do not contain KEi/KEr or - Ni/Nr payloads. This implies that the SA payload in IKE_AUTH - exchange cannot contain Transform Type 4 (Diffie-Hellman Group) with - any other value than NONE. Implementations should probably leave the - transform out entirely in this case. - -4.4. Extended Sequence Numbers (ESN) transform - - The description of the ESN transform in Section 3.3 has be proved - difficult to understand. The ESN transform has the following - meaning: - - o A proposal containing one ESN transform with value 0 means "do not - use extended sequence numbers". - - o A proposal containing one ESN transform with value 1 means "use - extended sequence numbers". - - o A proposal containing two ESN transforms with values 0 and 1 means - "I support both normal and extended sequence numbers, you choose". - (Obviously this case is only allowed in requests; the response - will contain only one ESN transform.) - - In most cases, the exchange initiator will include either the first - or third alternative in its SA payload. The second alternative is - rarely useful for the initiator: it means that using normal sequence - numbers is not acceptable (so if the responder does not support ESNs, - the exchange will fail with NO_PROPOSAL_CHOSEN). - - - -Eronen & Hoffman Expires November 5, 2006 [Page 16] - -Internet-Draft IKEv2 Clarifications May 2006 - - - Note that including the ESN transform is mandatory when creating - ESP/AH SAs (it was optional in earlier drafts of the IKEv2 - specification). - - (References: "Technical change needed to IKEv2 before publication", - "STRAW POLL: Dealing with the ESN negotiation interop issue in IKEv2" - and "Results of straw poll regarding: IKEv2 interoperability issue" - threads, March-April 2005.) - -4.5. Negotiation of ESP_TFC_PADDING_NOT_SUPPORTED - - The description of ESP_TFC_PADDING_NOT_SUPPORTED notification in - Section 3.10.1 says that "This notification asserts that the sending - endpoint will NOT accept packets that contain Flow Confidentiality - (TFC) padding". - - However, the text does not say in which messages this notification - should be included, or whether the scope of this notification is a - single CHILD_SA or all CHILD_SAs of the peer. - - Our interpretation is that the scope is a single CHILD_SA, and thus - this notification is included in messages containing an SA payload - negotiating a CHILD_SA. If neither endpoint accepts TFC padding, - this notification will be included in both the request proposing an - SA and the response accepting it. If this notification is included - in only one of the messages, TFC padding can still be sent in one - direction. - -4.6. Negotiation of NON_FIRST_FRAGMENTS_ALSO - - NON_FIRST_FRAGMENTS_ALSO notification is described in Section 3.10.1 - simply as "Used for fragmentation control. See [RFC4301] for - explanation." - - [RFC4301] says "Implementations that will transmit non-initial - fragments on a tunnel mode SA that makes use of non-trivial port (or - ICMP type/code or MH type) selectors MUST notify a peer via the IKE - NOTIFY NON_FIRST_FRAGMENTS_ALSO payload. The peer MUST reject this - proposal if it will not accept non-initial fragments in this context. - If an implementation does not successfully negotiate transmission of - non-initial fragments for such an SA, it MUST NOT send such fragments - over the SA." - - However, it is not clear exactly how the negotiation works. Our - interpretation is that the negotiation works the same way as for - IPCOMP_SUPPORTED and USE_TRANSPORT_MODE: sending non-first fragments - is enabled only if NON_FIRST_FRAGMENTS_ALSO notification is included - in both the request proposing an SA and the response accepting it. - - - -Eronen & Hoffman Expires November 5, 2006 [Page 17] - -Internet-Draft IKEv2 Clarifications May 2006 - - - In other words, if the peer "rejects this proposal", it only omits - NON_FIRST_FRAGMENTS_ALSO notification from the response, but does not - reject the whole CHILD_SA creation. - -4.7. Semantics of complex traffic selector payloads - - As described in Section 3.13, the TSi/TSr payloads can include one or - more individual traffic selectors. - - There is no requirement that TSi and TSr contain the same number of - individual traffic selectors. Thus, they are interpreted as follows: - a packet matches a given TSi/TSr if it matches at least one of the - individual selectors in TSi, and at least one of the individual - selectors in TSr. - - For instance, the following traffic selectors: - - TSi = ((17, 100, 192.0.1.66-192.0.1.66), - (17, 200, 192.0.1.66-192.0.1.66)) - TSr = ((17, 300, 0.0.0.0-255.255.255.255), - (17, 400, 0.0.0.0-255.255.255.255)) - - would match UDP packets from 192.0.1.66 to anywhere, with any of the - four combinations of source/destination ports (100,300), (100,400), - (200,300), and (200, 400). - - This implies that some types of policies may require several CHILD_SA - pairs. For instance, a policy matching only source/destination ports - (100,300) and (200,400), but not the other two combinations, cannot - be negotiated as a single CHILD_SA pair using IKEv2. - - (References: "IKEv2 Traffic Selectors?" thread, Feb 2005.) - -4.8. ICMP type/code in traffic selector payloads - - The traffic selector types 7 and 8 can also refer to ICMP type and - code fields. As described in Section 3.13.1, "For the ICMP protocol, - the two one-octet fields Type and Code are treated as a single 16-bit - integer (with Type in the most significant eight bits and Code in the - least significant eight bits) port number for the purposes of - filtering based on this field." - - Since ICMP packets do not have separate source and destination port - fields, there is some room for confusion what exactly the four TS - payloads (two in the request, two in the response, each containing - both start and end port fields) should contain. - - The answer to this question can be found from [RFC4301] Section - - - -Eronen & Hoffman Expires November 5, 2006 [Page 18] - -Internet-Draft IKEv2 Clarifications May 2006 - - - 4.4.1.3. - - To give a concrete example, if a host at 192.0.1.234 wants to create - a transport mode SA for sending "Destination Unreachable" packets - (ICMPv4 type 3) to 192.0.2.155, but is not willing to receive them - over this SA pair, the CREATE_CHILD_SA exchange would look like this: - - Initiator Responder - ----------- ----------- - HDR, SK { N(USE_TRANSPORT_MODE), SA, Ni, - TSi(1, 0x0300-0x03FF, 192.0.1.234-192.0.1.234), - TSr(1, 65535-0, 192.0.2.155-192.0.2.155) } --> - - <-- HDR, SK { N(USE_TRANSPORT_MODE), SA, Nr, - TSi(1, 0x0300-0x03FF, 192.0.1.234-192.0.1.234), - TSr(1, 65535-0, 192.0.2.155-192.0.2.155) } - - Since IKEv2 always creates IPsec SAs in pairs, two SAs are also - created in this case, even though the second SA is never used for - data traffic. - - An exchange creating an SA pair that can be used both for sending and - receiving "Destination Unreachable" places the same value in all the - port: - - Initiator Responder - ----------- ----------- - HDR, SK { N(USE_TRANSPORT_MODE), SA, Ni, - TSi(1, 0x0300-0x03FF, 192.0.1.234-192.0.1.234), - TSr(1, 0x0300-0x03FF, 192.0.2.155-192.0.2.155) } --> - - <-- HDR, SK { N(USE_TRANSPORT_MODE), SA, Nr, - TSi(1, 0x0300-0x03FF, 192.0.1.234-192.0.1.234), - TSr(1, 0x0300-0x03FF, 192.0.2.155-192.0.2.155) } - - (References: "ICMP and MH TSs for IKEv2" thread, Sep 2005.) - -4.9. Mobility header in traffic selector payloads - - Traffic selectors can use IP Protocol ID 135 to match the IPv6 - mobility header [MIPv6]. However, the IKEv2 specification does not - define how to represent the "MH Type" field in traffic selectors. - - At some point, it was expected that this will be defined in a - separate document later. However, [RFC4301] says that "For IKE, the - IPv6 mobility header message type (MH type) is placed in the most - significant eight bits of the 16 bit local "port" selector". The - direction semantics of TSi/TSr port fields are the same as for ICMP, - - - -Eronen & Hoffman Expires November 5, 2006 [Page 19] - -Internet-Draft IKEv2 Clarifications May 2006 - - - and are described in the previous section. - - (References: Tero Kivinen's mail "Issue #86: Add IPv6 mobility header - message type as selector", 2003-10-14. "ICMP and MH TSs for IKEv2" - thread, Sep 2005.) - -4.10. Narrowing the traffic selectors - - Section 2.9 describes how traffic selectors are negotiated when - creating a CHILD_SA. A more concise summary of the narrowing process - is presented below. - - o If the responder's policy does not allow any part of the traffic - covered by TSi/TSr, it responds with TS_UNACCEPTABLE. - - o If the responder's policy allows the entire set of traffic covered - by TSi/TSr, no narrowing is necessary, and the responder can - return the same TSi/TSr values. - - o Otherwise, narrowing is needed. If the responder's policy allows - all traffic covered by TSi[1]/TSr[1] (the first traffic selectors - in TSi/TSr) but not entire TSi/TSr, the responder narrows to an - acceptable subset of TSi/TSr that includes TSi[1]/TSr[1]. - - o If the responder's policy does not allow all traffic covered by - TSi[1]/TSr[1], but does allow some parts of TSi/TSr, it narrows to - an acceptable subset of TSi/TSr. - - In the last two cases, there may be several subsets that are - acceptable (but their union is not); in this case, the responder - arbitrarily chooses one of them, and includes ADDITIONAL_TS_POSSIBLE - notification in the response. - -4.11. SINGLE_PAIR_REQUIRED - - The description of the SINGLE_PAIR_REQUIRED notify payload in - Sections 2.9 and 3.10.1 is not fully consistent. - - We do not attempt to describe this payload in this document either, - since it is expected that most implementations will not have policies - that require separate SAs for each address pair. - - Thus, if only some part (or parts) of the TSi/TSr proposed by the - initiator is (are) acceptable to the responder, most responders - should simply narrow TSi/TSr to an acceptable subset (as described in - the last two paragraphs of Section 2.9), rather than use - SINGLE_PAIR_REQUIRED. - - - - -Eronen & Hoffman Expires November 5, 2006 [Page 20] - -Internet-Draft IKEv2 Clarifications May 2006 - - -4.12. Traffic selectors violating own policy - - Section 2.9 describes traffic selector negotiation in great detail. - One aspect of this negotiation that may need some clarification is - that when creating a new SA, the initiator should not propose traffic - selectors that violate its own policy. If this rule is not followed, - valid traffic may be dropped. - - This is best illustrated by an example. Suppose that host A has a - policy whose effect is that traffic to 192.0.1.66 is sent via host B - encrypted using AES, and traffic to all other hosts in 192.0.1.0/24 - is also sent via B, but encrypted using 3DES. Suppose also that host - B accepts any combination of AES and 3DES. - - If host A now proposes an SA that uses 3DES, and includes TSr - containing (192.0.1.0-192.0.1.0.255), this will be accepted by host - B. Now, host B can also use this SA to send traffic from 192.0.1.66, - but those packets will be dropped by A since it requires the use of - AES for those traffic. Even if host A creates a new SA only for - 192.0.1.66 that uses AES, host B may freely continue to use the first - SA for the traffic. In this situation, when proposing the SA, host A - should have followed its own policy, and included a TSr containing - ((192.0.1.0-192.0.1.65),(192.0.1.67-192.0.1.255)) instead. - - In general, if (1) the initiator makes a proposal "for traffic X - (TSi/TSr), do SA", and (2) for some subset X' of X, the initiator - does not actually accept traffic X' with SA, and (3) the initiator - would be willing to accept traffic X' with some SA' (!=SA), valid - traffic can be unnecessarily dropped since the responder can apply - either SA or SA' to traffic X'. - - (References: "Question about "narrowing" ..." thread, Feb 2005. - "IKEv2 needs a "policy usage mode"..." thread, Feb 2005. "IKEv2 - Traffic Selectors?" thread, Feb 2005. "IKEv2 traffic selector - negotiation examples", 2004-08-08.) - -4.13. Traffic selector authorization - - IKEv2 relies on information in the Peer Authorization Database (PAD) - when determining what kind of IPsec SAs a peer is allowed to create. - This process is described in [RFC4301] Section 4.4.3. When a peer - requests the creation of an IPsec SA with some traffic selectors, the - PAD must contain "Child SA Authorization Data" linking the identity - authenticated by IKEv2 and the addresses permitted for traffic - selectors. - - For example, the PAD might be configured so that authenticated - identity "sgw23.example.com" is allowed to create IPsec SAs for - - - -Eronen & Hoffman Expires November 5, 2006 [Page 21] - -Internet-Draft IKEv2 Clarifications May 2006 - - - 192.0.2.0/24, meaning this security gateway is a valid - "representative" for these addresses. Host-to-host IPsec requires - similar entries, linking, for example, "fooserver4.example.com" with - 192.0.1.66/32, meaning this identity a valid "owner" or - "representative" of the address in question. - - As noted in [RFC4301], "It is necessary to impose these constraints - on creation of child SAs to prevent an authenticated peer from - spoofing IDs associated with other, legitimate peers." In the - example given above, a correct configuration of the PAD prevents - sgw23 from creating IPsec SAs with address 192.0.1.66, and prevents - fooserver4 from creating IPsec SAs with addresses from 192.0.2.0/24. - - It is important to note that simply sending IKEv2 packets using some - particular address does not imply a permission to create IPsec SAs - with that address in the traffic selectors. For example, even if - sgw23 would be able to spoof its IP address as 192.0.1.66, it could - not create IPsec SAs matching fooserver4's traffic. - - The IKEv2 specification does not specify how exactly IP address - assignment using configuration payloads interacts with the PAD. Our - interpretation is that when a security gateway assigns an address - using configuration payloads, it also creates a temporary PAD entry - linking the authenticated peer identity and the newly allocated inner - address. - - It has been recognized that configuring the PAD correctly may be - difficult in some environments. For instance, if IPsec is used - between a pair of hosts whose addresses are allocated dynamically - using DHCP, it is extremely difficult to ensure that the PAD - specifies the correct "owner" for each IP address. This would - require a mechanism to securely convey address assignments from the - DHCP server, and link them to identities authenticated using IKEv2. - - Due to this limitation, some vendors have been known to configure - their PADs to allow an authenticated peer to create IPsec SAs with - traffic selectors containing the same address that was used for the - IKEv2 packets. In environments where IP spoofing is possible (i.e., - almost everywhere) this essentially allows any peer to create IPsec - SAs with any traffic selectors. This is not an appropriate or secure - configuration in most circumstances. See [Aura05] for an extensive - discussion about this issue, and the limitations of host-to-host - IPsec in general. - - -5. Rekeying and deleting SAs - - - - - -Eronen & Hoffman Expires November 5, 2006 [Page 22] - -Internet-Draft IKEv2 Clarifications May 2006 - - -5.1. Rekeying SAs with the CREATE_CHILD_SA exchange - - Continued from Section 4.1 of this document. - - NEW-1.3.2 Rekeying IKE_SAs with the CREATE_CHILD_SA Exchange - - The CREATE_CHILD_SA request for rekeying an IKE_SA is: - - Initiator Responder - ----------- ----------- - HDR, SK {SA, Ni, [KEi]} --> - - The initiator sends SA offer(s) in the SA payload, a nonce in - the Ni payload, and optionally a Diffie-Hellman value in the KEi - payload. - - The CREATE_CHILD_SA response for rekeying an IKE_SA is: - - <-- HDR, SK {SA, Nr, [KEr]} - - The responder replies (using the same Message ID to respond) - with the accepted offer in an SA payload, a nonce in the Nr - payload, and, optionally, a Diffie-Hellman value in the KEr - payload. - - The new IKE_SA has its message counters set to 0, regardless of - what they were in the earlier IKE_SA. The window size starts at - 1 for any new IKE_SA. The new initiator and responder SPIs are - supplied in the SPI fields of the SA payloads. - - NEW-1.3.3 Rekeying CHILD_SAs with the CREATE_CHILD_SA Exchange - - The CREATE_CHILD_SA request for rekeying a CHILD_SA is: - - Initiator Responder - ----------- ----------- - HDR, SK {N(REKEY_SA), [N+], SA, - Ni, [KEi], TSi, TSr} --> - - The leading Notify payload of type REKEY_SA identifies the - CHILD_SA being rekeyed, and contains the SPI that the initiator - expects in the headers of inbound packets. In addition, the - initiator sends SA offer(s) in the SA payload, a nonce in the Ni - payload, optionally a Diffie-Hellman value in the KEi payload, - and the proposed traffic selectors in the TSi and TSr payloads. - The request can also contain Notify payloads that specify - additional details for the CHILD_SA. - - - - -Eronen & Hoffman Expires November 5, 2006 [Page 23] - -Internet-Draft IKEv2 Clarifications May 2006 - - - The CREATE_CHILD_SA response for rekeying a CHILD_SA is: - - <-- HDR, SK {[N+], SA, Nr, - [KEr], TSi, TSr} - - The responder replies with the accepted offer in an SA payload, - and a Diffie-Hellman value in the KEr payload if KEi was - included in the request and the selected cryptographic suite - includes that group. - - The traffic selectors for traffic to be sent on that SA are - specified in the TS payloads in the response, which may be a - subset of what the initiator of the CHILD_SA proposed. - -5.2. Rekeying the IKE_SA vs. reauthentication - - Rekeying the IKE_SA and reauthentication are different concepts in - IKEv2. Rekeying the IKE_SA establishes new keys for the IKE_SA and - resets the Message ID counters, but it does not authenticate the - parties again (no AUTH or EAP payloads are involved). - - While rekeying the IKE_SA may be important in some environments, - reauthentication (the verification that the parties still have access - to the long-term credentials) is often more important. - - IKEv2 does not have any special support for reauthentication. - Reauthentication is done by creating a new IKE_SA from scratch (using - IKE_SA_INIT/IKE_AUTH exchanges, without any REKEY_SA notify - payloads), creating new CHILD_SAs within the new IKE_SA (without - REKEY_SA notify payloads), and finally deleting the old IKE_SA (which - deletes the old CHILD_SAs as well). - - This means that reauthentication also establishes new keys for the - IKE_SA and CHILD_SAs. Therefore, while rekeying can be performed - more often than reauthentication, the situation where "authentication - lifetime" is shorter than "key lifetime" does not make sense. - - While creation of a new IKE_SA can be initiated by either party - (initiator or responder in the original IKE_SA), the use of EAP - authentication and/or configuration payloads means in practice that - reauthentication has to be initiated by the same party as the - original IKE_SA. IKEv2 does not currently allow the responder to - request reauthentication in this case; however, there is ongoing work - to add this functionality [ReAuth]. - - (References: "Reauthentication in IKEv2" thread, Oct/Nov 2004.) - - - - - -Eronen & Hoffman Expires November 5, 2006 [Page 24] - -Internet-Draft IKEv2 Clarifications May 2006 - - -5.3. SPIs when rekeying the IKE_SA - - Section 2.18 says that "New initiator and responder SPIs are supplied - in the SPI fields". This refers to the SPI fields in the Proposal - structures inside the Security Association (SA) payloads, not the SPI - fields in the IKE header. - - (References: Tom Stiemerling's mail "Rekey IKE SA", 2005-01-24. - Geoffrey Huang's reply, 2005-01-24.) - -5.4. SPI when rekeying a CHILD_SA - - Section 3.10.1 says that in REKEY_SA notifications, "The SPI field - identifies the SA being rekeyed." - - Since CHILD_SAs always exist in pairs, there are two different SPIs. - The SPI placed in the REKEY_SA notification is the SPI the exchange - initiator would expect in inbound ESP or AH packets (just as in - Delete payloads). - -5.5. Changing PRFs when rekeying the IKE_SA - - When rekeying the IKE_SA, Section 2.18 says that "SKEYSEED for the - new IKE_SA is computed using SK_d from the existing IKE_SA as - follows: - - SKEYSEED = prf(SK_d (old), [g^ir (new)] | Ni | Nr)" - - If the old and new IKE_SA selected a different PRF, it is not totally - clear which PRF should be used. - - Since the rekeying exchange belongs to the old IKE_SA, it is the old - IKE_SA's PRF that is used. This also follows the principle that the - same key (the old SK_d) should not be used with multiple - cryptographic algorithms. - - Note that this may work poorly if the new IKE_SA's PRF has a fixed - key size, since the output of the PRF may not be of the correct size. - This supports our opinion earlier in the document that the use of - PRFs with a fixed key size is a bad idea. - - (References: "Changing PRFs when rekeying the IKE_SA" thread, June - 2005.) - -5.6. Deleting vs. closing SAs - - The IKEv2 specification talks about "closing" and "deleting" SAs, but - it is not always clear what exactly is meant. However, other parts - - - -Eronen & Hoffman Expires November 5, 2006 [Page 25] - -Internet-Draft IKEv2 Clarifications May 2006 - - - of the specification make it clear that when local state related to a - CHILD_SA is removed, the SA must also be actively deleted with a - Delete payload. - - In particular, Section 2.4 says that "If an IKE endpoint chooses to - delete CHILD_SAs, it MUST send Delete payloads to the other end - notifying it of the deletion". Section 1.4 also explains that "ESP - and AH SAs always exist in pairs, with one SA in each direction. - When an SA is closed, both members of the pair MUST be closed." - -5.7. Deleting a CHILD_SA pair - - Section 1.4 describes how to delete SA pairs using the Informational - exchange: "To delete an SA, an INFORMATIONAL exchange with one or - more delete payloads is sent listing the SPIs (as they would be - expected in the headers of inbound packets) of the SAs to be deleted. - The recipient MUST close the designated SAs." - - The "one or more delete payloads" phrase has caused some confusion. - You never send delete payloads for the two sides of an SA in a single - message. If you have many SAs to delete at the same time (such as - the nested example given in that paragraph), you include delete - payloads for in inbound half of each SA in your Informational - exchange. - -5.8. Deleting an IKE_SA - - Since IKE_SAs do not exist in pairs, it is not totally clear what the - response message should contain when the request deleted the IKE_SA. - - Since there is no information that needs to be sent to the other side - (except that the request was received), an empty Informational - response seems like the most logical choice. - - (References: "Question about delete IKE SA" thread, May 2005.) - -5.9. Who is the original initiator of IKE_SA - - In the IKEv2 document, "initiator" refers to the party who initiated - the exchange being described, and "original initiator" refers to the - party who initiated the whole IKE_SA. However, there is some - potential for confusion because the IKE_SA can be rekeyed by either - party. - - To clear up this confusion, we propose that "original initiator" - always refers to the party who initiated the exchange which resulted - in the current IKE_SA. In other words, if the "original responder" - starts rekeying the IKE_SA, that party becomes the "original - - - -Eronen & Hoffman Expires November 5, 2006 [Page 26] - -Internet-Draft IKEv2 Clarifications May 2006 - - - initiator" of the new IKE_SA. - - (References: Paul Hoffman's mail "Original initiator in IKEv2", 2005- - 04-21.) - -5.10. Comparing nonces - - Section 2.8 about rekeying says that "If redundant SAs are created - though such a collision, the SA created with the lowest of the four - nonces used in the two exchanges SHOULD be closed by the endpoint - that created it." - - Here "lowest" uses an octet-by-octet (lexicographical) comparison - (instead of, for instance, comparing the nonces as large integers). - In other words, start by comparing the first octet; if they're equal, - move to the next octet, and so on. If you reach the end of one - nonce, that nonce is the lower one. - - (References: "IKEv2 rekeying question" thread, July 2005.) - -5.11. Exchange collisions - - Since IKEv2 exchanges can be initiated by both peers, it is possible - that two exchanges affecting the same SA partly overlap. This can - lead to a situation where the SA state information is temporarily not - synchronized, and a peer can receive a request it cannot process in a - normal fashion. Some of these corner cases are discussed in the - specification, some are not. - - Obviously, using a window size greater than one leads to infinitely - more complex situations, especially if requests are processed out of - order. In this section, we concentrate on problems that can arise - even with window size 1. - - (References: "IKEv2: invalid SPI in DELETE payload" thread, Dec 2005/ - Jan 2006. "Problem with exchanges collisions" thread, Dec 2005.) - -5.11.1. Simultaneous CHILD_SA close - - Probably the simplest case happens if both peers decide to close the - same CHILD_SA pair at the same time: - - - - - - - - - - -Eronen & Hoffman Expires November 5, 2006 [Page 27] - -Internet-Draft IKEv2 Clarifications May 2006 - - - Host A Host B - -------- -------- - send req1: D(SPIa) --> - <-- send req2: D(SPIb) - --> recv req1 - <-- send resp1: () - recv resp1 - recv req2 - send resp2: () --> - --> recv resp2 - - This case is described in Section 1.4, and is handled by omitting the - Delete payloads from the response messages. - -5.11.2. Simultaneous IKE_SA close - - Both peers can also decide to close the IKE_SA at the same time. The - desired end result is obvious; however, in certain cases the final - exchanges may not be fully completed. - - Host A Host B - -------- -------- - send req1: D() --> - <-- send req2: D() - --> recv req1 - - At this point, host B should reply as usual (with empty Informational - response), close the IKE_SA, and stop retransmitting req2. This is - because once host A receives resp1, it may not be able to reply any - longer. The situation is symmetric, so host A should behave the same - way. - - Host A Host B - -------- -------- - <-- send resp1: () - send resp2: () - - Even if neither resp1 nor resp2 ever arrives, the end result is still - correct: the IKE_SA is gone. The same happens if host A never - receives req2. - -5.11.3. Simultaneous CHILD_SA rekeying - - Another case that is described in the specification is simultaneous - rekeying. Section 2.8 says - - - - - - -Eronen & Hoffman Expires November 5, 2006 [Page 28] - -Internet-Draft IKEv2 Clarifications May 2006 - - - "If the two ends have the same lifetime policies, it is possible - that both will initiate a rekeying at the same time (which will - result in redundant SAs). To reduce the probability of this - happening, the timing of rekeying requests SHOULD be jittered - (delayed by a random amount of time after the need for rekeying is - noticed). - - This form of rekeying may temporarily result in multiple similar - SAs between the same pairs of nodes. When there are two SAs - eligible to receive packets, a node MUST accept incoming packets - through either SA. If redundant SAs are created though such a - collision, the SA created with the lowest of the four nonces used - in the two exchanges SHOULD be closed by the endpoint that created - it." - - However, a better explanation on what impact this has on - implementations is needed. Assume that hosts A and B have an - existing IPsec SA pair with SPIs (SPIa1,SPIb1), and both start - rekeying it at the same time: - - Host A Host B - -------- -------- - send req1: N(REKEY_SA,SPIa1), - SA(..,SPIa2,..),Ni1,.. --> - <-- send req2: N(REKEY_SA,SPIb1), - SA(..,SPIb2,..),Ni2,.. - recv req2 <-- - - At this point, A knows there is a simultaneous rekeying going on. - However, it cannot yet know which of the exchanges will have the - lowest nonce, so it will just note the situation and respond as - usual. - - send resp2: SA(..,SPIa3,..),Nr1,.. --> - --> recv req1 - - Now B also knows that simultaneous rekeying is going on. Similarly - as host A, it has to respond as usual. - - <-- send resp1: SA(..,SPIb3,..),Nr2,.. - recv resp1 <-- - --> recv resp2 - - At this point, there are three CHILD_SA pairs between A and B (the - old one and two new ones). A and B can now compare the nonces. - Suppose that the lowest nonce was Nr1 in message resp2; in this case, - B (the sender of req2) deletes the redundant new SA, and A (the node - that initiated the surviving rekeyed SA), deletes the old one. - - - -Eronen & Hoffman Expires November 5, 2006 [Page 29] - -Internet-Draft IKEv2 Clarifications May 2006 - - - send req3: D(SPIa1) --> - <-- send req4: D(SPIb2) - --> recv req3 - <-- send resp4: D(SPIb1) - recv req4 <-- - send resp4: D(SPIa3) --> - - The rekeying is now finished. - - However, there is a second possible sequence of events that can - happen if some packets are lost in the network, resulting in - retransmissions. The rekeying begins as usual, but A's first packet - (req1) is lost. - - Host A Host B - -------- -------- - send req1: N(REKEY_SA,SPIa1), - SA(..,SPIa2,..),Ni1,.. --> (lost) - <-- send req2: N(REKEY_SA,SPIb1), - SA(..,SPIb2,..),Ni2,.. - recv req2 <-- - send resp2: SA(..,SPIa3,..),Nr1,.. --> - --> recv resp2 - <-- send req3: D(SPIb1) - recv req3 <-- - send resp3: D(SPIa1) --> - --> recv resp3 - - From B's point of view, the rekeying is now completed, and since it - has not yet received A's req1, it does not even know that these was - simultaneous rekeying. However, A will continue retransmitting the - message, and eventually it will reach B. - - resend req1 --> - --> recv req1 - - What should B do in this point? To B, it looks like A is trying to - rekey an SA that no longer exists; thus failing the request with - something non-fatal such as NO_PROPOSAL_CHOSEN seems like a - reasonable approach. - - <-- send resp1: N(NO_PROPOSAL_CHOSEN) - recv resp1 <-- - - When A receives this error, it already knows there was simultaneous - rekeying, so it can ignore the error message. - - - - - -Eronen & Hoffman Expires November 5, 2006 [Page 30] - -Internet-Draft IKEv2 Clarifications May 2006 - - -5.11.4. Simultaneous IKE_SA rekeying - - Probably the most complex case occurs when both peers try to rekey - the IKE_SA at the same time. Basically, the text in Section 2.8 - applies to this case as well; however, it is important to ensure that - the CHILD_SAs are inherited by the right IKE_SA. - - The case where both endpoints notice the simultaneous rekeying works - the same way as with CHILD_SAs. After the CREATE_CHILD_SA exchanges, - three IKE_SAs exist between A and B; the one containing the lowest - nonce inherits the CHILD_SAs. - - However, there is a twist to the other case where one rekeying - finishes first: - - Host A Host B - -------- -------- - send req1: - SA(..,SPIa1,..),Ni1,.. --> - <-- send req2: SA(..,SPIb1,..),Ni2,.. - --> recv req1 - <-- send resp1: SA(..,SPIb2,..),Nr2,.. - recv resp1 <-- - send req3: D() --> - --> recv req3 - - At this point, host B sees a request to close the IKE_SA. There's - not much more to do than to reply as usual. However, at this point - host B should stop retransmitting req2, since once host A receives - resp3, it will delete all the state associated with the old IKE_SA, - and will not be able to reply to it. - - <-- send resp3: () - -5.11.5. Closing and rekeying a CHILD_SA - - A case similar to simultaneous rekeying can occur if one peer decides - to close an SA and the other peer tries to rekey it: - - Host A Host B - -------- -------- - send req1: D(SPIa) --> - <-- send req2: N(REKEY_SA,SPIb),SA,.. - --> recv req1 - - At this point, host B notices that host A is trying to close an SA - that host B is currently rekeying. Replying as usual is probably the - best choice: - - - -Eronen & Hoffman Expires November 5, 2006 [Page 31] - -Internet-Draft IKEv2 Clarifications May 2006 - - - <-- send resp1: D(SPIb) - - Depending on in which order req2 and resp1 arrive, host A sees either - a request to rekey an SA that it is currently closing, or a request - to rekey an SA that does not exist. In both cases, - NO_PROPOSAL_CHOSEN is probably fine. - - recv req2 - recv resp1 - send resp2: N(NO_PROPOSAL_CHOSEN) --> - --> recv resp2 - -5.11.6. Closing a new CHILD_SA - - Yet another case occurs when host A creates a CHILD_SA pair, but soon - thereafter host B decides to delete it (possible because its policy - changed): - - Host A Host B - -------- -------- - send req1: [N(REKEY_SA,SPIa1)], - SA(..,SPIa2,..),.. --> - --> recv req1 - (lost) <-- send resp1: SA(..,SPIb2,..),.. - - <-- send req2: D(SPIb2) - recv req2 - - At this point, host A has not yet received message resp1 (and is - retransmitting message req1), so it does not recognize SPIb in - message req2. What should host A do? - - One option would be to reply with an empty Informational response. - However, this same reply would also be sent if host A has received - resp1, but has already sent a new request to delete the SA that was - just created. This would lead to a situation where the peers are no - longer in sync about which SAs exist between them. However, host B - would eventually notice that the other half of the CHILD_SA pair has - not been deleted. Section 1.4 describes this case and notes that "a - node SHOULD regard half-closed connections as anomalous and audit - their existence should they persist", and continues that "if - connection state becomes sufficiently messed up, a node MAY close the - IKE_SA". - - Another solution that has been proposed is to reply with an - INVALID_SPI notification which contains SPIb. This would explicitly - tell host B that the SA was not deleted, so host B could try deleting - it again later. However, this usage is not part of the IKEv2 - - - -Eronen & Hoffman Expires November 5, 2006 [Page 32] - -Internet-Draft IKEv2 Clarifications May 2006 - - - specification, and would not be in line with normal use of the - INVALID_SPI notification where the data field contains the SPI the - recipient of the notification would put in outbound packets. - - Yet another solution would be to ignore req2 at this time, and wait - until we have received resp1. However, this alternative has not been - fully analyzed at this time; in general, ignoring valid requests is - always a bit dangerous, because both endpoints could do it, leading - to a deadlock. - - This document recommends the first alternative. - -5.11.7. Rekeying a new CHILD_SA - - Yet another case occurs when a CHILD_SA is rekeyed soon after it has - been created: - - Host A Host B - -------- -------- - send req1: [N(REKEY_SA,SPIa1)], - SA(..,SPIa2,..),.. --> - (lost) <-- send resp1: SA(..,SPIb2,..),.. - - <-- send req2: N(REKEY_SA,SPIb2), - SA(..,SPIb3,..),.. - recv req2 <-- - - To host A, this looks like a request to rekey an SA that does not - exist. Like in the simultaneous rekeying case, replying with - NO_PROPOSAL_CHOSEN is probably reasonable: - - send resp2: N(NO_PROPOSAL_CHOSEN) --> - recv resp1 - -5.11.8. Collisions with IKE_SA rekeying - - Another set of cases occur when one peer starts rekeying the IKE_SA - at the same time the other peer starts creating, rekeying, or closing - a CHILD_SA. Suppose that host B starts creating a CHILD_SA, and soon - after, host A starts rekeying the IKE_SA: - - Host A Host B - -------- -------- - <-- send req1: SA,Ni1,TSi,TSr - send req2: SA,Ni2,.. --> - --> recv req2 - - What should host B do at this point? Replying as usual would seem - - - -Eronen & Hoffman Expires November 5, 2006 [Page 33] - -Internet-Draft IKEv2 Clarifications May 2006 - - - like a reasonable choice: - - <-- send resp2: SA,Ni2,.. - recv resp2 <-- - send req3: D() --> - --> recv req3 - - Now, a problem arises: If host B now replies normally with an empty - Informational response, this will cause host A to delete state - associated with the IKE_SA. This means host B should stop - retransmitting req1. However, host B cannot know whether or not host - A has received req1. If host A did receive it, it will move the - CHILD_SA to the new IKE_SA as usual, and the state information will - then be out of sync. - - It seems this situation is tricky to handle correctly. Our proposal - is as follows: if a host receives a request to rekey the IKE_SA when - it has CHILD_SAs in "half-open" state (currently being created or - rekeyed), it should reply with NO_PROPOSAL_CHOSEN. If a host - receives a request to create or rekey a CHILD_SA after it has started - rekeying the IKE_SA, it should reply with NO_ADDITIONAL_SAS. - - The case where CHILD_SAs are being closed is even worse. Our - recommendation is that if a host receives a request to rekey the - IKE_SA when it has CHILD_SAs in "half-closed" state (currently being - closed), it should reply with NO_PROPOSAL_CHOSEN. And if a host - receives a request to close a CHILD_SA after it has started rekeying - the IKE_SA, it should reply with an empty Informational response. - This ensures that at least the other peer will eventually notice that - the CHILD_SA is still in "half-closed" state, and will start a new - IKE_SA from scratch. - -5.11.9. Closing and rekeying the IKE_SA - - The final case considered in this section occurs if one peer decides - to close the IKE_SA while the other peer tries to rekey it. - - Host A Host B - -------- -------- - send req1: SA(..,SPIa1,..),Ni1 --> - <-- send req2: D() - --> recv req1 - recv req2 <-- - - At this point, host B should probably reply with NO_PROPOSAL_CHOSEN, - and host A should reply as usual, close the IKE_SA, and stop - retransmitting req1. - - - - -Eronen & Hoffman Expires November 5, 2006 [Page 34] - -Internet-Draft IKEv2 Clarifications May 2006 - - - <-- send resp1: N(NO_PROPOSAL_CHOSEN) - send resp2: () - - If host A wants to continue communication with B, it can now start a - new IKE_SA. - -5.11.10. Summary - - If a host receives a request to rekey: - - o a CHILD_SA pair that the host is currently trying to close: reply - with NO_PROPOSAL_CHOSEN. - - o a CHILD_SA pair that the host is currently rekeying: reply as - usual, but prepare to close redundant SAs later based on the - nonces. - - o a CHILD_SA pair that does not exist: reply with - NO_PROPOSAL_CHOSEN. - - o the IKE_SA, and the host is currently rekeying the IKE_SA: reply - as usual, but prepare to close redundant SAs and move inherited - CHILD_SAs later based on the nonces. - - o the IKE_SA, and the host is currently creating, rekeying, or - closing a CHILD_SA: reply with NO_PROPOSAL_CHOSEN. - - o the IKE_SA, and the host is currently trying to close the IKE_SA: - reply with NO_PROPOSAL_CHOSEN. - - If a host receives a request to close: - - o a CHILD_SA pair that the host is currently trying to close: reply - without Delete payloads. - - o a CHILD_SA pair that the host is currently rekeying: reply as - usual, with Delete payload. - - o a CHILD_SA pair that does not exist: reply without Delete - payloads. - - o the IKE_SA, and the host is currently rekeying the IKE_SA: reply - as usual, and forget about our own rekeying request. - - o the IKE_SA, and the host is currently trying to close the IKE_SA: - reply as usual, and forget about our own close request. - - If a host receives a request to create or rekey a CHILD_SA when it is - - - -Eronen & Hoffman Expires November 5, 2006 [Page 35] - -Internet-Draft IKEv2 Clarifications May 2006 - - - currently rekeying the IKE_SA: reply with NO_ADDITIONAL_SAS. - - If a host receives a request to delete a CHILD_SA when it is - currently rekeying the IKE_SA: reply without Delete payloads. - -5.12. Diffie-Hellman and rekeying the IKE_SA - - There has been some confusion whether doing a new Diffie-Hellman - exchange is mandatory when the IKE_SA is rekeyed. - - It seems that this case is allowed by the IKEv2 specification. - Section 2.18 shows the Diffie-Hellman term (g^ir) in brackets. - Section 3.3.3 does not contradict this when it says that including - the D-H transform is mandatory: although including the transform is - mandatory, it can contain the value "NONE". - - However, having the option to skip the Diffie-Hellman exchange when - rekeying the IKE_SA does not add useful functionality to the - protocol. The main purpose of rekeying the IKE_SA is to ensure that - the compromise of old keying material does not provide information - about the current keys, or vice versa. This requires performing the - Diffie-Hellman exchange when rekeying. Furthermore, it is likely - that this option would have been removed from the protocol as - unnecessary complexity had it been discussed earlier. - - Given this, we recommend that implementations should have a hard- - coded policy that requires performing a new Diffie-Hellman exchange - when rekeying the IKE_SA. In other words, the initiator should not - propose the value "NONE" for the D-H transform, and the responder - should not accept such a proposal. This policy also implies that a - succesful exchange rekeying the IKE_SA always includes the KEi/KEr - payloads. - - (References: "Rekeying IKE_SAs with the CREATE_CHILD_SA exhange" - thread, Oct 2005. "Comments of - draft-eronen-ipsec-ikev2-clarifications-02.txt" thread, Apr 2005.) - - -6. Configuration payloads - -6.1. Assigning IP addresses - - Section 2.9 talks about traffic selector negotiation and mentions - that "In support of the scenario described in section 1.1.3, an - initiator may request that the responder assign an IP address and - tell the initiator what it is." - - This sentence is correct, but its placement is slightly confusing. - - - -Eronen & Hoffman Expires November 5, 2006 [Page 36] - -Internet-Draft IKEv2 Clarifications May 2006 - - - IKEv2 does allow the initiator to request assignment of an IP address - from the responder, but this is done using configuration payloads, - not traffic selector payloads. An address in a TSi payload in a - response does not mean that the responder has assigned that address - to the initiator; it only means that if packets matching these - traffic selectors are sent by the initiator, IPsec processing can be - performed as agreed for this SA. The TSi payload itself does not - give the initiator permission to configure the initiator's TCP/IP - stack with the address and use it as its source address. - - In other words, IKEv2 does not have two different mechanisms for - assigning addresses, but only one: configuration payloads. In the - scenario described in Section 1.1.3, both configuration and traffic - selector payloads are usually included in the same message, and often - contain the same information in the response message (see Section 6.3 - of this document for some examples). However, their semantics are - still different. - -6.2. Requesting any INTERNAL_IP4/IP6_ADDRESS - - When describing the INTERNAL_IP4/IP6_ADDRESS attributes, Section - 3.15.1 says that "In a request message, the address specified is a - requested address (or zero if no specific address is requested)". - The question here is that does "zero" mean an address "0.0.0.0" or a - zero length string? - - Earlier, the same section also says that "If an attribute in the - CFG_REQUEST Configuration Payload is not zero-length, it is taken as - a suggestion for that attribute". Also, the table of configuration - attributes shows that the length of INTERNAL_IP4_ADDRESS is either "0 - or 4 octets", and likewise, INTERNAL_IP6_ADDRESS is either "0 or 17 - octets". - - Thus, if the client does not request a specific address, it includes - a zero-length INTERNAL_IP4/IP6_ADDRESS attribute, not an attribute - containing an all-zeroes address. The example in 2.19 is thus - incorrect, since it shows the attribute as - "INTERNAL_ADDRESS(0.0.0.0)". - - However, since the value is only a suggestion, implementations are - recommended to ignore suggestions they do not accept; or in other - words, treat the same way a zero-length INTERNAL_IP4_ADDRESS, - "0.0.0.0", and any other addresses the implementation does not - recognize as a reasonable suggestion. - - - - - - - -Eronen & Hoffman Expires November 5, 2006 [Page 37] - -Internet-Draft IKEv2 Clarifications May 2006 - - -6.3. INTERNAL_IP4_SUBNET/INTERNAL_IP6_SUBNET - - Section 3.15.1 describes the INTERNAL_IP4_SUBNET as "The protected - sub-networks that this edge-device protects. This attribute is made - up of two fields: the first is an IP address and the second is a - netmask. Multiple sub-networks MAY be requested. The responder MAY - respond with zero or more sub-network attributes." - INTERNAL_IP6_SUBNET is defined in a similar manner. - - This raises two questions: first, since this information is usually - included in the TSr payload, what functionality does this attribute - add? And second, what does this attribute mean in CFG_REQUESTs? - - For the first question, there seem to be two sensible - interpretations. Clearly TSr (in IKE_AUTH or CREATE_CHILD_SA - response) indicates which subnets are accessible through the SA that - was just created. - - The first interpretation of the INTERNAL_IP4/6_SUBNET attributes is - that they indicate additional subnets that can be reached through - this gateway, but need a separate SA. According to this - interpretation, the INTERNAL_IP4/6_SUBNET attributes are useful - mainly when they contain addresses not included in TSr. - - The second interpretation is that the INTERNAL_IP4/6_SUBNET - attributes express the gateway's policy about what traffic should be - sent through the gateway. The client can choose whether other - traffic (covered by TSr, but not in INTERNAL_IP4/6_SUBNET) is sent - through the gateway or directly to the destination. According to - this interpretation, the attributes are useful mainly when TSr - contains addresses not included in the INTERNAL_IP4/6_SUBNET - attributes. - - It turns out that these two interpretations are not incompatible, but - rather two sides of the same principle: traffic to the addresses - listed in the INTERNAL_IP4/6_SUBNET attributes should be sent via - this gateway. If there are no existing IPsec SAs whose traffic - selectors cover the address in question, new SAs have to be created. - - A couple of examples are given below. For instance, if there are two - subnets, 192.0.1.0/26 and 192.0.2.0/24, and the client's request - contains the following: - - CP(CFG_REQUEST) = - INTERNAL_IP4_ADDRESS() - TSi = (0, 0-65535, 0.0.0.0-255.255.255.255) - TSr = (0, 0-65535, 0.0.0.0-255.255.255.255) - - - - -Eronen & Hoffman Expires November 5, 2006 [Page 38] - -Internet-Draft IKEv2 Clarifications May 2006 - - - Then a valid response could be the following (in which TSr and - INTERNAL_IP4_SUBNET contain the same information): - - CP(CFG_REPLY) = - INTERNAL_IP4_ADDRESS(192.0.1.234) - INTERNAL_IP4_SUBNET(192.0.1.0/255.255.255.192) - INTERNAL_IP4_SUBNET(192.0.2.0/255.255.255.0) - TSi = (0, 0-65535, 192.0.1.234-192.0.1.234) - TSr = ((0, 0-65535, 192.0.1.0-192.0.1.63), - (0, 0-65535, 192.0.2.0-192.0.2.255)) - - In these cases, the INTERNAL_IP4_SUBNET does not really carry any - useful information. Another possible reply would have been this: - - CP(CFG_REPLY) = - INTERNAL_IP4_ADDRESS(192.0.1.234) - INTERNAL_IP4_SUBNET(192.0.1.0/255.255.255.192) - INTERNAL_IP4_SUBNET(192.0.2.0/255.255.255.0) - TSi = (0, 0-65535, 192.0.1.234-192.0.1.234) - TSr = (0, 0-65535, 0.0.0.0-255.255.255.255) - - This would mean that the client can send all its traffic through the - gateway, but the gateway does not mind if the client sends traffic - not included by INTERNAL_IP4_SUBNET directly to the destination - (without going through the gateway). - - A different situation arises if the gateway has a policy that - requires the traffic for the two subnets to be carried in separate - SAs. Then a response like this would indicate to the client that if - it wants access to the second subnet, it needs to create a separate - SA: - - CP(CFG_REPLY) = - INTERNAL_IP4_ADDRESS(192.0.1.234) - INTERNAL_IP4_SUBNET(192.0.1.0/255.255.255.192) - INTERNAL_IP4_SUBNET(192.0.2.0/255.255.255.0) - TSi = (0, 0-65535, 192.0.1.234-192.0.1.234) - TSr = (0, 0-65535, 192.0.1.0-192.0.1.63) - - INTERNAL_IP4_SUBNET can also be useful if the client's TSr included - only part of the address space. For instance, if the client requests - the following: - - CP(CFG_REQUEST) = - INTERNAL_IP4_ADDRESS() - TSi = (0, 0-65535, 0.0.0.0-255.255.255.255) - TSr = (0, 0-65535, 192.0.2.155-192.0.2.155) - - - - -Eronen & Hoffman Expires November 5, 2006 [Page 39] - -Internet-Draft IKEv2 Clarifications May 2006 - - - Then the gateway's reply could be this: - - CP(CFG_REPLY) = - INTERNAL_IP4_ADDRESS(192.0.1.234) - INTERNAL_IP4_SUBNET(192.0.1.0/255.255.255.192) - INTERNAL_IP4_SUBNET(192.0.2.0/255.255.255.0) - TSi = (0, 0-65535, 192.0.1.234-192.0.1.234) - TSr = (0, 0-65535, 192.0.2.155-192.0.2.155) - - It is less clear what the attributes mean in CFG_REQUESTs, and - whether other lengths than zero make sense in this situation (but for - INTERNAL_IP6_SUBNET, zero length is not allowed at all!). Currently - this document recommends that implementations should not include - INTERNAL_IP4_SUBNET or INTERNAL_IP6_SUBNET attributes in - CFG_REQUESTs. - - For the IPv4 case, this document recommends using only netmasks - consisting of some amount of "1" bits followed by "0" bits; for - instance, "255.0.255.0" would not be a valid netmask for - INTERNAL_IP4_SUBNET. - - It is also worthwhile to note that the contents of the INTERNAL_IP4/ - 6_SUBNET attributes do not imply link boundaries. For instance, a - gateway providing access to a large company intranet using addresses - from the 10.0.0.0/8 block can send a single INTERNAL_IP4_SUBNET - attribute (10.0.0.0/255.0.0.0) even if the intranet has hundreds of - routers and separate links. - - (References: Tero Kivinen's mail "Intent of couple of attributes in - Configuration Payload in IKEv2?", 2004-11-19. Srinivasa Rao - Addepalli's mail "INTERNAL_IP4_SUBNET and INTERNAL_IP6_SUBNET in - IKEv2", 2004-09-10. Yoav Nir's mail "Re: New I-D: IKEv2 - Clarifications and Implementation Guidelines", 2005-02-07. - "Clarifications open issue: INTERNAL_IP4_SUBNET/NETMASK" thread, - April 2005.) - -6.4. INTERNAL_IP4_NETMASK - - Section 3.15.1 defines the INTERNAL_IP4_NETMASK attribute, and says - that "The internal network's netmask. Only one netmask is allowed in - the request and reply messages (e.g., 255.255.255.0) and it MUST be - used only with an INTERNAL_IP4_ADDRESS attribute". - - However, it is not clear what exactly this attribute means, as the - concept of "netmask" is not very well defined for point-to-point - links (unlike multi-access links, where it means "you can reach hosts - inside this netmask directly using layer 2, instead of sending - packets via a router"). Even if the operating system's TCP/IP stack - - - -Eronen & Hoffman Expires November 5, 2006 [Page 40] - -Internet-Draft IKEv2 Clarifications May 2006 - - - requires a netmask to be configured, for point-to-point links it - could be just set to 255.255.255.255. So, why is this information - sent in IKEv2? - - One possible interpretation would be that the host is given a whole - block of IP addresses instead of a single address. This is also what - Framed-IP-Netmask does in [RADIUS], the IPCP "subnet mask" extension - does in PPP [IPCPSubnet], and the prefix length in the IPv6 Framed- - IPv6-Prefix attribute does in [RADIUS6]. However, nothing in the - specification supports this interpretation, and discussions on the - IPsec WG mailing list have confirmed it was not intended. Section - 3.15.1 also says that multiple addresses are assigned using multiple - INTERNAL_IP4/6_ADDRESS attributes. - - Currently, this document's interpretation is the following: - INTERNAL_IP4_NETMASK in a CFG_REPLY means roughly the same thing as - INTERNAL_IP4_SUBNET containing the same information ("send traffic to - these addresses through me"), but also implies a link boundary. For - instance, the client could use its own address and the netmask to - calculate the broadcast address of the link. (Whether the gateway - will actually deliver broadcast packets to other VPN clients and/or - other nodes connected to this link is another matter.) - - An empty INTERNAL_IP4_NETMASK attribute can be included in a - CFG_REQUEST to request this information (although the gateway can - send the information even when not requested). However, it seems - that non-empty values for this attribute do not make sense in - CFG_REQUESTs. - - Fortunately, Section 4 clearly says that a minimal implementation - does not need to include or understand the INTERNAL_IP4_NETMASK - attribute, and thus this document recommends that implementations - should not use the INTERNAL_IP4_NETMASK attribute or assume that the - other peer supports it. - - (References: Charlie Kaufman's mail "RE: Proposed Last Call based - revisions to IKEv2", 2004-05-27. Email discussion with Tero Kivinen, - Jan 2005. Yoav Nir's mail "Re: New I-D: IKEv2 Clarifications and - Implementation Guidelines", 2005-02-07. "Clarifications open issue: - INTERNAL_IP4_SUBNET/NETMASK" thread, April 2005.) - -6.5. Configuration payloads for IPv6 - - IKEv2 also defines configuration payloads for IPv6. However, they - are based on the corresponding IPv4 payloads, and do not fully follow - the "normal IPv6 way of doing things". - - - - - -Eronen & Hoffman Expires November 5, 2006 [Page 41] - -Internet-Draft IKEv2 Clarifications May 2006 - - - A client can be assigned an IPv6 address using the - INTERNAL_IP6_ADDRESS configuration payload. A minimal exchange could - look like this: - - CP(CFG_REQUEST) = - INTERNAL_IP6_ADDRESS() - INTERNAL_IP6_DNS() - TSi = (0, 0-65535, :: - FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF) - TSr = (0, 0-65535, :: - FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF) - - CP(CFG_REPLY) = - INTERNAL_IP6_ADDRESS(2001:DB8:0:1:2:3:4:5/64) - INTERNAL_IP6_DNS(2001:DB8:99:88:77:66:55:44) - TSi = (0, 0-65535, 2001:DB8:0:1:2:3:4:5 - 2001:DB8:0:1:2:3:4:5) - TSr = (0, 0-65535, :: - FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF) - - In particular, IPv6 stateless autoconfiguration or router - advertisement messages are not used; neither is neighbor discovery. - - The client can also send a non-empty INTERNAL_IP6_ADDRESS attribute - in the CFG_REQUEST to request a specific address or interface - identifier. The gateway first checks if the specified address is - acceptable, and if it is, returns that one. If the address was not - acceptable, the gateway will attempt to use the interface identifier - with some other prefix; if even that fails, the gateway will select - another interface identifier. - - The INTERNAL_IP6_ADDRESS attribute also contains a prefix length - field. When used in a CFG_REPLY, this corresponds to the - INTERNAL_IP4_NETMASK attribute in the IPv4 case (and indeed, was - called INTERNAL_IP6_NETMASK in earlier versions of the IKEv2 draft). - See the previous section for more details. - - While this approach to configuring IPv6 addresses is reasonably - simple, it has some limitations: IPsec tunnels configured using IKEv2 - are not fully-featured "interfaces" in the IPv6 addressing - architecture [IPv6Addr] sense. In particular, they do not - necessarily have link-local addresses, and this may complicate the - use of protocols that assume them, such as [MLDv2]. (Whether they - are called "interfaces" in some particular operating system is a - different issue.) - - (References: "VPN remote host configuration IPv6 ?" thread, May 2004. - "Clarifications open issue: INTERNAL_IP4_SUBNET/NETMASK" thread, - April 2005.) - - - - - - -Eronen & Hoffman Expires November 5, 2006 [Page 42] - -Internet-Draft IKEv2 Clarifications May 2006 - - -6.6. INTERNAL_IP6_NBNS - - Section 3.15.1 defines the INTERNAL_IP6_NBNS attribute for sending - the IPv6 address of NetBIOS name servers. - - However, NetBIOS is not defined for IPv6, and probably never will be. - Thus, this attribute most likely does not make much sense. - - (Pointed out by Bernard Aboba in the IP Configuration Security (ICOS) - BoF at IETF62.) - -6.7. INTERNAL_ADDRESS_EXPIRY - - Section 3.15.1 defines the INTERNAL_ADDRESS_EXPIRY attribute as - "Specifies the number of seconds that the host can use the internal - IP address. The host MUST renew the IP address before this expiry - time. Only one of these attributes MAY be present in the reply." - - Expiry times and explicit renewals are primarily useful in - environments like DHCP, where the server cannot reliably know when - the client has gone away. However, in IKEv2 this is known, and the - gateway can simply free the address when the IKE_SA is deleted. - - Also, Section 4 says that supporting renewals is not mandatory. - Given that this functionality is usually not needed, we recommend - that gateways should not send the INTERNAL_ADDRESS_EXPIRY attribute. - (And since this attribute does not seem to make much sense for - CFG_REQUESTs, clients should not send it either.) - - Note that according to Section 4, clients are required to understand - INTERNAL_ADDRESS_EXPIRY if they receive it. A minimum implementation - would use the value to limit the lifetime of the IKE_SA. - - (References: Tero Kivinen's mail "Comments of - draft-eronen-ipsec-ikev2-clarifications-02.txt", 2005-04-05. - "Questions about internal address" thread, April 2005.) - -6.8. Address assignment failures - - If the responder encounters an error while attempting to assign an IP - address to the initiator, it responds with an - INTERNAL_ADDRESS_FAILURE notification as described in Section 3.10.1. - However, there are some more complex error cases. - - First, if the responder does not support configuration payloads at - all, it can simply ignore all configuration payloads. This type of - implementation never sends INTERNAL_ADDRESS_FAILURE notifications. - If the initiator requires the assignment of an IP address, it will - - - -Eronen & Hoffman Expires November 5, 2006 [Page 43] - -Internet-Draft IKEv2 Clarifications May 2006 - - - treat a response without CFG_REPLY as an error. - - A second case is where the responder does support configuration - payloads, but only for particular type of addresses (IPv4 or IPv6). - Section 4 says that "A minimal IPv4 responder implementation will - ignore the contents of the CP payload except to determine that it - includes an INTERNAL_IP4_ADDRESS attribute". If, for instance, the - initiator includes both INTERNAL_IP4_ADDRESS and INTERNAL_IP6_ADDRESS - in the CFG_REQUEST, an IPv4-only responder can thus simply ignore the - IPv6 part and process the IPv4 request as usual. - - A third case is where the initiator requests multiple addresses of a - type that the responder supports: what should happen if some (but not - all) of the requests fail? It seems that an optimistic approach - would be the best one here: if the responder is able to assign at - least one address, it replies with those; it sends - INTERNAL_ADDRESS_FAILURE only if no addresses can be assigned. - - (References: "ikev2 and internal_ivpn_address" thread, June 2005.) - - -7. Miscellaneous issues - -7.1. Matching ID_IPV4_ADDR and ID_IPV6_ADDR - - When using the ID_IPV4_ADDR/ID_IPV6_ADDR identity types in IDi/IDr - payloads, IKEv2 does not require this address to match the address in - the IP header (of IKEv2 packets), or anything in the TSi/TSr - payloads. The contents of IDi/IDr is used purely to fetch the policy - and authentication data related to the other party. - - (References: "Identities types IP address,FQDN/user FQDN and DN and - its usage in preshared key authentication" thread, Jan 2005.) - -7.2. Relationship of IKEv2 to RFC4301 - - The IKEv2 specification refers to [RFC4301], but it never makes - clearly defines the exact relationship is. - - However, there are some requirements in the specification that make - it clear that IKEv2 requires [RFC4301]. In other words, an - implementation that does IPsec processing strictly according to - [RFC2401] cannot be compliant with the IKEv2 specification. - - One such example can be found in Section 2.24: "Specifically, tunnel - encapsulators and decapsulators for all tunnel-mode SAs created by - IKEv2 [...] MUST implement the tunnel encapsulation and - decapsulation processing specified in [RFC4301] to prevent discarding - - - -Eronen & Hoffman Expires November 5, 2006 [Page 44] - -Internet-Draft IKEv2 Clarifications May 2006 - - - of ECN congestion indications." - - Nevertheless, the changes required to existing [RFC2401] - implementations are not very large, especially since supporting many - of the new features (such as Extended Sequence Numbers) is optional. - -7.3. Reducing the window size - - In IKEv2, the window size is assumed to be a (possibly configurable) - property of a particular implementation, and is not related to - congestion control (unlike the window size in TCP, for instance). - - In particular, it is not defined what the responder should do when it - receives a SET_WINDOW_SIZE notification containing a smaller value - than is currently in effect. Thus, there is currently no way to - reduce the window size of an existing IKE_SA. However, when rekeying - an IKE_SA, the new IKE_SA starts with window size 1 until it is - explicitly increased by sending a new SET_WINDOW_SIZE notification. - - (References: Tero Kivinen's mail "Comments of - draft-eronen-ipsec-ikev2-clarifications-02.txt", 2005-04-05.) - -7.4. Minimum size of nonces - - Section 2.10 says that "Nonces used in IKEv2 MUST be randomly chosen, - MUST be at least 128 bits in size, and MUST be at least half the key - size of the negotiated prf." - - However, the initiator chooses the nonce before the outcome of the - negotiation is known. In this case, the nonce has to be long enough - for all the PRFs being proposed. - -7.5. Initial zero octets on port 4500 - - It is not clear whether a peer sending an IKE_SA_INIT request on port - 4500 should include the initial four zero octets. Section 2.23 talks - about how to upgrade to tunneling over port 4500 after message 2, but - it does not say what to do if message 1 is sent on port 4500. - - - - - - - - - - - - - -Eronen & Hoffman Expires November 5, 2006 [Page 45] - -Internet-Draft IKEv2 Clarifications May 2006 - - - IKE MUST listen on port 4500 as well as port 500. - - [...] - - The IKE initiator MUST check these payloads if present and if - they do not match the addresses in the outer packet MUST tunnel - all future IKE and ESP packets associated with this IKE_SA over - UDP port 4500. - - To tunnel IKE packets over UDP port 4500, the IKE header has four - octets of zero prepended and the result immediately follows the - UDP header. [...] - - The very beginning of Section 2 says "... though IKE messages may - also be received on UDP port 4500 with a slightly different format - (see section 2.23)." - - That "slightly different format" is only described in discussing what - to do after changing to port 4500. However, [RFC3948] shows clearly - the format has the initial zeros even for initiators on port 4500. - Furthermore, without the initial zeros, the processing engine cannot - determine whether the packet is an IKE packet or an ESP packet. - - Thus, all packets sent on port 4500 need the four zero prefix; - otherwise, the receiver won't know how to handle them. - -7.6. Destination port for NAT traversal - - Section 2.23 says that "an IPsec endpoint that discovers a NAT - between it and its correspondent MUST send all subsequent traffic to - and from port 4500". - - This sentence is misleading. The peer "outside" the NAT uses source - port 4500 for the traffic it sends, but the destination port is, of - course, taken from packets sent by the peer behind the NAT. This - port number is usually dynamically allocated by the NAT. - -7.7. SPI values for messages outside of an IKE_SA - - The IKEv2 specification is not quite clear what SPI values should be - used in the IKE header for the small number of notifications that are - allowed to be sent outside of an IKE_SA. Note that such - notifications are explicitly not Informational exchanges; Section 1.5 - makes it clear that these are one-way messages that must not be - responded to. - - There are two cases when such a one-way notification can be sent: - INVALID_IKE_SPI and INVALID_SPI. - - - -Eronen & Hoffman Expires November 5, 2006 [Page 46] - -Internet-Draft IKEv2 Clarifications May 2006 - - - In case of INVALID_IKE_SPI, the message sent is a response message, - and Section 2.21 says that "If a response is sent, the response MUST - be sent to the IP address and port from whence it came with the same - IKE SPIs and the Message ID copied." - - In case of INVALID_SPI, however, there are no IKE SPI values that - would be meaningful to the recipient of such a notification. Also, - the message sent is now an INFORMATIONAL request. A strict - interpretation of the specification would require the sender to - invent garbage values for the SPI fields. However, we think this was - not the intention, and using zero values is acceptable. - - (References: "INVALID_IKE_SPI" thread, June 2005.) - -7.8. Protocol ID/SPI fields in Notify payloads - - Section 3.10 says that the Protocol ID field in Notify payloads "For - notifications that do not relate to an existing SA, this field MUST - be sent as zero and MUST be ignored on receipt". However, the - specification does not clearly say which notifications are related to - existing SAs and which are not. - - Since the main purpose of the Protocol ID field is to specify the - type of the SPI, our interpretation is that the Protocol ID field - should be non-zero only when the SPI field is non-empty. - - There are currently only two notifications where this is the case: - INVALID_SELECTORS and REKEY_SA. - -7.9. Which message should contain INITIAL_CONTACT - - The description of the INITIAL_CONTACT notification in Section 3.10.1 - says that "This notification asserts that this IKE_SA is the only - IKE_SA currently active between the authenticated identities". - However, neither Section 2.4 nor 3.10.1 says in which message this - payload should be placed. - - The general agreement is that INITIAL_CONTACT is best communicated in - the first IKE_AUTH request, not as a separate exchange afterwards. - - (References: "Clarifying the use of INITIAL_CONTACT in IKEv2" thread, - April 2005. "Initial Contact messages" thread, December 2004. - "IKEv2 and Initial Contact" thread, September 2004 and April 2005.) - -7.10. Alignment of payloads - - Many IKEv2 payloads contain fields marked as "RESERVED", mostly - because IKEv1 had them, and partly because they make the pictures - - - -Eronen & Hoffman Expires November 5, 2006 [Page 47] - -Internet-Draft IKEv2 Clarifications May 2006 - - - easier to draw. In particular, payloads in IKEv2 are not, in - general, aligned to 4-octet boundaries. (Note that payloads were not - aligned to 4-byte boundaries in IKEv1 either.) - - (References: "IKEv2: potential 4-byte alignment problem" thread, June - 2004.) - -7.11. Key length transform attribute - - Section 3.3.5 says that "The only algorithms defined in this document - that accept attributes are the AES based encryption, integrity, and - pseudo-random functions, which require a single attribute specifying - key width." - - This is incorrect. The AES-based integrity and pseudo-random - functions defined in [IKEv2] always use a 128-bit key. In fact, - there are currently no integrity or PRF algorithms that use the key - length attribute (and we recommend that they should not be defined in - the future either). - - For encryption algorithms, the situation is slightly more complex - since there are three different types of algorithms: - - o The key length attribute is never used with algorithms that use a - fixed length key, such as DES and IDEA. - - o The key length attribute is always included for the currently - defined AES-based algorithms (CBC, CTR, CCM and GCM). Omitting - the key length attribute is not allowed; if the proposal does not - contain it, the proposal has to be rejected. - - o For other algorithms, the key length attribute can be included but - is not mandatory. These algorithms include, e.g., RC5, CAST and - BLOWFISH. If the key length attribute is not included, the - default value specified in [RFC2451] is used. - -7.12. IPsec IANA considerations - - There are currently three different IANA registry files that contain - important numbers for IPsec: ikev2-registry, isakmp-registry, and - ipsec-registry. Implementors should note that IKEv2 may use numbers - different from IKEv1 for a particular algorithm. - - For instance, an encryption algorithm can have up to three different - numbers: the IKEv2 "Transform Type 1" identifier in ikev2-registry, - the IKEv1 phase 1 "Encryption Algorithm" identifier in ipsec- - registry, and the IKEv1 phase 2 "IPSEC ESP Transform Identifier" - isakmp-registry. Although some algorithms have the same number in - - - -Eronen & Hoffman Expires November 5, 2006 [Page 48] - -Internet-Draft IKEv2 Clarifications May 2006 - - - all three registries, the registries are not identical. - - Similarly, an integrity algorithm can have at least the IKEv2 - "Transform Type 3" identifier in ikev2-registry, the IKEv1 phase 2 - "IPSEC AH Transform Identifier" in isakmp-registry, and the IKEv1 - phase 2 ESP "Authentication Algorithm Security Association Attribute" - identifier in isakmp-registry. And there is also the IKEv1 phase 1 - "Hash Algorithm" list in ipsec-registry. - - This issue needs special care also when writing a specification for - how a new algorithm is used together with IPsec. - -7.13. Combining ESP and AH - - The IKEv2 specification contains some misleading text about how ESP - and AH can be combined. - - IKEv2 is based on [RFC4301] which does not include "SA bundles" that - were part of [RFC2401]. While a single packet can go through IPsec - processing multiple times, each of these passes uses a separate SA, - and the passes are coordinated by the forwarding tables. In IKEv2, - each of these SAs has to be created using a separate CREATE_CHILD_SA - exchange. Thus, the text in Section 2.7 about a single proposal - containing both ESP and AH is incorrect. - - Morever, the combination of ESP and AH (between the same endpoints) - become largely obsolete already in 1998 when RFC 2406 was published. - Our recommendation is that IKEv2 implementations should not support - this combination, and implementors should not assume the combination - can be made to work in interoperable manner. - - (References: "Rekeying SA bundles" thread, Oct 2005.) - - -8. Implementation mistakes - - Some implementers at the early IKEv2 bakeoffs didn't do everything - correctly. This may seem like an obvious statement, but it is - probably useful to list a few things that were clear in the document - and not needing clarification, that some implementors didn't do. All - of these things caused interoperability problems. - - o Some implementations continued to send traffic on a CHILD_SA after - it was rekeyed, even after receiving an DELETE payload. - - o After rekeying an IKE_SA, some implementations did not reset their - message counters to zero. One set the counter to 2, another did - not reset the counter at all. - - - -Eronen & Hoffman Expires November 5, 2006 [Page 49] - -Internet-Draft IKEv2 Clarifications May 2006 - - - o Some implementations could only handle a single pair of traffic - selectors, or would only process the first pair in the proposal. - - o Some implementations responded to a delete request by sending an - empty INFORMATIONAL response, and then initiated their own - INFORMATIONAL exchange with the pair of SAs to delete. - - o Although this did not happen at the bakeoff, from the discussion - there, it is clear that some people had not implemented message - window sizes correctly. Some implementations might have sent - messages that did not fit into the responder's message windows, - and some implementations may not have torn down an SA if they did - not ever receive a message that they know they should have. - - -9. Security considerations - - This document does not introduce any new security considerations to - IKEv2. If anything, clarifying complex areas of the specification - can reduce the likelihood of implementation problems that may have - security implications. - - -10. IANA considerations - - This document does not change or create any IANA-registered values. - - -11. Acknowledgments - - This document is mainly based on conversations on the IPsec WG - mailing list. The authors would especially like to thank Bernard - Aboba, Jari Arkko, Vijay Devarapalli, William Dixon, Francis Dupont, - Mika Joutsenvirta, Charlie Kaufman, Stephen Kent, Tero Kivinen, Yoav - Nir, Michael Richardson, and Joel Snyder for their contributions. - - In addition, the authors would like to thank all the participants of - the first public IKEv2 bakeoff, held in Santa Clara in February 2005, - for their questions and proposed clarifications. - - -12. References - -12.1. Normative References - - [IKEv2] Kaufman, C., Ed., "Internet Key Exchange (IKEv2) - Protocol", RFC 4306, December 2005. - - - - -Eronen & Hoffman Expires November 5, 2006 [Page 50] - -Internet-Draft IKEv2 Clarifications May 2006 - - - [IKEv2ALG] - Schiller, J., "Cryptographic Algorithms for Use in the - Internet Key Exchange Version 2 (IKEv2)", RFC 4307, - December 2005. - - [PKCS1v20] - Kaliski, B. and J. Staddon, "PKCS #1: RSA Cryptography - Specifications Version 2.0", RFC 2437, October 1998. - - [PKCS1v21] - Jonsson, J. and B. Kaliski, "Public-Key Cryptography - Standards (PKCS) #1: RSA Cryptography Specifications - Version 2.1", RFC 3447, February 2003. - - [RFC2401] Kent, S. and R. Atkinson, "Security Architecture for the - Internet Protocol", RFC 2401, November 1998. - - [RFC4301] Kent, S. and K. Seo, "Security Architecture for the - Internet Protocol", RFC 4301, December 2005. - -12.2. Informative References - - [Aura05] Aura, T., Roe, M., and A. Mohammed, "Experiences with - Host-to-Host IPsec", 13th International Workshop on - Security Protocols, Cambridge, UK, April 2005. - - [EAP] Aboba, B., Blunk, L., Vollbrecht, J., Carlson, J., and H. - Levkowetz, "Extensible Authentication Protocol (EAP)", - RFC 3748, June 2004. - - [HashUse] Hoffman, P., "Use of Hash Algorithms in IKE and IPsec", - draft-hoffman-ike-ipsec-hash-use-01 (work in progress), - December 2005. - - [IPCPSubnet] - Cisco Systems, Inc., "IPCP Subnet Mask Support - Enhancements", http://www.cisco.com/univercd/cc/td/doc/ - product/software/ios121/121newft/121limit/121dc/121dc3/ - ipcp_msk.htm, January 2003. - - [IPv6Addr] - Hinden, R. and S. Deering, "Internet Protocol Version 6 - (IPv6) Addressing Architecture", RFC 4291, April 2004. - - [MIPv6] Johnson, D., Perkins, C., and J. Arkko, "Mobility Support - in IPv6", RFC 3775, June 2004. - - [MLDv2] Vida, R. and L. Costa, "Multicast Listener Discovery - - - -Eronen & Hoffman Expires November 5, 2006 [Page 51] - -Internet-Draft IKEv2 Clarifications May 2006 - - - Version 2 (MLDv2) for IPv6", RFC 3810, June 2004. - - [NAI] Aboba, B., Beadles, M., Arkko, J., and P. Eronen, "The - Network Access Identifier", RFC 4282, December 2005. - - [PKI4IPsec] - Korver, B., "Internet PKI Profile of IKEv1/ISAKMP, IKEv2, - and PKIX", draft-ietf-pki4ipsec-ikecert-profile (work in - progress), February 2006. - - [RADEAP] Aboba, B. and P. Calhoun, "RADIUS (Remote Authentication - Dial In User Service) Support For Extensible - Authentication Protocol (EAP)", RFC 3579, September 2003. - - [RADIUS] Rigney, C., Willens, S., Rubens, A., and W. Simpson, - "Remote Authentication Dial In User Service (RADIUS)", - RFC 2865, June 2000. - - [RADIUS6] Aboba, B., Zorn, G., and D. Mitton, "RADIUS and IPv6", - RFC 3162, August 2001. - - [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", RFC 2119, March 1997. - - [RFC2451] Pereira, R. and R. Adams, "The ESP CBC-Mode Cipher - Algorithms", RFC 2451, November 1998. - - [RFC2822] Resnick, P., "Internet Message Format", RFC 2822, - April 2001. - - [RFC3664] Hoffman, P., "The AES-XCBC-PRF-128 Algorithm for the - Internet Key Exchange Protocol (IKE)", RFC 3664, - January 2004. - - [RFC3664bis] - Hoffman, P., "The AES-XCBC-PRF-128 Algorithm for the - Internet Key Exchange Protocol (IKE)", - draft-hoffman-rfc3664bis (work in progress), October 2005. - - [RFC3948] Huttunen, A., Swander, B., Volpe, V., DiBurro, L., and M. - Stenberg, "UDP Encapsulation of IPsec ESP Packets", - RFC 3948, January 2005. - - [RFC822] Crocker, D., "Standard for the format of ARPA Internet - text messages", RFC 822, August 1982. - - [ReAuth] Nir, Y., "Repeated Authentication in Internet Key Exchange - (IKEv2) Protocol", RFC 4478, April 2006. - - - -Eronen & Hoffman Expires November 5, 2006 [Page 52] - -Internet-Draft IKEv2 Clarifications May 2006 - - - [SCVP] Freeman, T., Housley, R., Malpani, A., Cooper, D., and T. - Polk, "Simple Certificate Validation Protocol (SCVP)", - draft-ietf-pkix-scvp-21 (work in progress), October 2005. - - -Appendix A. Exchanges and payloads - - This appendix contains a short summary of the IKEv2 exchanges, and - what payloads can appear in which message. This appendix is purely - informative; if it disagrees with the body of this document or the - IKEv2 specification, the other text is considered correct. - - Vendor-ID (V) payloads may be included in any place in any message. - This sequence shows what are, in our opinion, the most logical places - for them. - - The specification does not say which messages can contain - N(SET_WINDOW_SIZE). It can possibly be included in any message, but - it is not yet shown below. - -A.1. IKE_SA_INIT exchange - - request --> [N(COOKIE)], - SA, KE, Ni, - [N(NAT_DETECTION_SOURCE_IP)+, - N(NAT_DETECTION_DESTINATION_IP)], - [V+] - - normal response <-- SA, KE, Nr, - (no cookie) [N(NAT_DETECTION_SOURCE_IP), - N(NAT_DETECTION_DESTINATION_IP)], - [[N(HTTP_CERT_LOOKUP_SUPPORTED)], CERTREQ+], - [V+] - - - - - - - - - - - - - - - - - - -Eronen & Hoffman Expires November 5, 2006 [Page 53] - -Internet-Draft IKEv2 Clarifications May 2006 - - -A.2. IKE_AUTH exchange without EAP - - request --> IDi, [CERT+], - [N(INITIAL_CONTACT)], - [[N(HTTP_CERT_LOOKUP_SUPPORTED)], CERTREQ+], - [IDr], - AUTH, - [CP(CFG_REQUEST)], - [N(IPCOMP_SUPPORTED)+], - [N(USE_TRANSPORT_MODE)], - [N(ESP_TFC_PADDING_NOT_SUPPORTED)], - [N(NON_FIRST_FRAGMENTS_ALSO)], - SA, TSi, TSr, - [V+] - - response <-- IDr, [CERT+], - AUTH, - [CP(CFG_REPLY)], - [N(IPCOMP_SUPPORTED)], - [N(USE_TRANSPORT_MODE)], - [N(ESP_TFC_PADDING_NOT_SUPPORTED)], - [N(NON_FIRST_FRAGMENTS_ALSO)], - SA, TSi, TSr, - [N(ADDITIONAL_TS_POSSIBLE)], - [V+] - - - - - - - - - - - - - - - - - - - - - - - - - - -Eronen & Hoffman Expires November 5, 2006 [Page 54] - -Internet-Draft IKEv2 Clarifications May 2006 - - -A.3. IKE_AUTH exchange with EAP - - first request --> IDi, - [N(INITIAL_CONTACT)], - [[N(HTTP_CERT_LOOKUP_SUPPORTED)], CERTREQ+], - [IDr], - [CP(CFG_REQUEST)], - [N(IPCOMP_SUPPORTED)+], - [N(USE_TRANSPORT_MODE)], - [N(ESP_TFC_PADDING_NOT_SUPPORTED)], - [N(NON_FIRST_FRAGMENTS_ALSO)], - SA, TSi, TSr, - [V+] - - first response <-- IDr, [CERT+], AUTH, - EAP, - [V+] - - / --> EAP - repeat 1..N times | - \ <-- EAP - - last request --> AUTH - - last response <-- AUTH, - [CP(CFG_REPLY)], - [N(IPCOMP_SUPPORTED)], - [N(USE_TRANSPORT_MODE)], - [N(ESP_TFC_PADDING_NOT_SUPPORTED)], - [N(NON_FIRST_FRAGMENTS_ALSO)], - SA, TSi, TSr, - [N(ADDITIONAL_TS_POSSIBLE)], - [V+] - - - - - - - - - - - - - - - - - - -Eronen & Hoffman Expires November 5, 2006 [Page 55] - -Internet-Draft IKEv2 Clarifications May 2006 - - -A.4. CREATE_CHILD_SA exchange for creating/rekeying CHILD_SAs - - request --> [N(REKEY_SA)], - [N(IPCOMP_SUPPORTED)+], - [N(USE_TRANSPORT_MODE)], - [N(ESP_TFC_PADDING_NOT_SUPPORTED)], - [N(NON_FIRST_FRAGMENTS_ALSO)], - SA, Ni, [KEi], TSi, TSr - - response <-- [N(IPCOMP_SUPPORTED)], - [N(USE_TRANSPORT_MODE)], - [N(ESP_TFC_PADDING_NOT_SUPPORTED)], - [N(NON_FIRST_FRAGMENTS_ALSO)], - SA, Nr, [KEr], TSi, TSr, - [N(ADDITIONAL_TS_POSSIBLE)] - -A.5. CREATE_CHILD_SA exchange for rekeying the IKE_SA - - request --> SA, Ni, [KEi] - - response <-- SA, Nr, [KEr] - -A.6. INFORMATIONAL exchange - - request --> [N+], - [D+], - [CP(CFG_REQUEST)] - - response <-- [N+], - [D+], - [CP(CFG_REPLY)] - - -Authors' Addresses - - Pasi Eronen - Nokia Research Center - P.O. Box 407 - FIN-00045 Nokia Group - Finland - - Email: pasi.eronen@nokia.com - - - - - - - - - -Eronen & Hoffman Expires November 5, 2006 [Page 56] - -Internet-Draft IKEv2 Clarifications May 2006 - - - Paul Hoffman - VPN Consortium - 127 Segre Place - Santa Cruz, CA 95060 - USA - - Email: paul.hoffman@vpnc.org - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Eronen & Hoffman Expires November 5, 2006 [Page 57] - -Internet-Draft IKEv2 Clarifications May 2006 - - -Full Copyright Statement - - Copyright (C) The Internet Society (2006). - - This document is subject to the rights, licenses and restrictions - contained in BCP 78, and except as set forth therein, the authors - retain all their rights. - - This document and the information contained herein are provided on an - "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS - OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET - ENGINEERING TASK FORCE DISCLAIM 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. - - -Intellectual Property - - The IETF takes no position regarding the validity or scope of any - Intellectual Property Rights or other rights that might be claimed to - pertain to the implementation or use of the technology described in - this document or the extent to which any license under such rights - might or might not be available; nor does it represent that it has - made any independent effort to identify any such rights. Information - on the procedures with respect to rights in RFC documents can be - found in BCP 78 and BCP 79. - - Copies of IPR disclosures made to the IETF Secretariat and any - assurances of licenses to be made available, or the result of an - attempt made to obtain a general license or permission for the use of - such proprietary rights by implementers or users of this - specification can be obtained from the IETF on-line IPR repository at - http://www.ietf.org/ipr. - - The IETF invites any interested party to bring to its attention any - copyrights, patents or patent applications, or other proprietary - rights that may cover technology that may be required to implement - this standard. Please address the information to the IETF at - ietf-ipr@ietf.org. - - -Acknowledgment - - Funding for the RFC Editor function is provided by the IETF - Administrative Support Activity (IASA). - - - - - -Eronen & Hoffman Expires November 5, 2006 [Page 58] - - diff --git a/src/charon/doc/standards/draft-eronen-ipsec-ikev2-eap-auth-05.txt b/src/charon/doc/standards/draft-eronen-ipsec-ikev2-eap-auth-05.txt deleted file mode 100644 index f5fd3cc0c..000000000 --- a/src/charon/doc/standards/draft-eronen-ipsec-ikev2-eap-auth-05.txt +++ /dev/null @@ -1,729 +0,0 @@ - - - -Network Working Group P. Eronen -Internet-Draft Nokia -Expires: December 28, 2006 H. Tschofenig - Siemens - June 26, 2006 - - - Extension for EAP Authentication in IKEv2 - draft-eronen-ipsec-ikev2-eap-auth-05.txt - -Status of this Memo - - By submitting this Internet-Draft, each author represents that any - applicable patent or other IPR claims of which he or she is aware - have been or will be disclosed, and any of which he or she becomes - aware will be disclosed, in accordance with Section 6 of BCP 79. - - 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 December 28, 2006. - -Copyright Notice - - Copyright (C) The Internet Society (2006). - -Abstract - - IKEv2 specifies that EAP authentication must be used together with - public key signature based responder authentication. This is - necessary with old EAP methods that provide only unilateral - authentication using, e.g., one-time passwords or token cards. - - This document specifies how EAP methods that provide mutual - authentication and key agreement can be used to provide extensible - - - -Eronen & Tschofenig Expires December 28, 2006 [Page 1] - -Internet-Draft Extension for EAP in IKEv2 June 2006 - - - responder authentication for IKEv2 based on other methods than public - key signatures. - - -1. Introduction - - The Extensible Authentication Protocol (EAP), defined in [4], is an - authentication framework which supports multiple authentication - mechanisms. Today, EAP has been implemented at end hosts and routers - that connect via switched circuits or dial-up lines using PPP [13], - IEEE 802 wired switches [9], and IEEE 802.11 wireless access points - [11]. - - One of the advantages of the EAP architecture is its flexibility. - EAP is used to select a specific authentication mechanism, typically - after the authenticator requests more information in order to - determine the specific authentication method to be used. Rather than - requiring the authenticator (e.g., wireless LAN access point) to be - updated to support each new authentication method, EAP permits the - use of a backend authentication server which may implement some or - all authentication methods. - - IKEv2 [3] is a component of IPsec used for performing mutual - authentication and establishing and maintaining security associations - for IPsec ESP and AH. In addition to supporting authentication using - public key signatures and shared secrets, IKEv2 also supports EAP - authentication. - - IKEv2 provides EAP authentication since it was recognized that public - key signatures and shared secrets are not flexible enough to meet the - requirements of many deployment scenarios. By using EAP, IKEv2 can - leverage existing authentication infrastructure and credential - databases, since EAP allows users to choose a method suitable for - existing credentials, and also makes separation of the IKEv2 - responder (VPN gateway) from the EAP authentication endpoint (backend - AAA server) easier. - - Some older EAP methods are designed for unilateral authentication - only (that is, EAP peer to EAP server). These methods are used in - conjunction with IKEv2 public key based authentication of the - responder to the initiator. It is expected that this approach is - especially useful for "road warrior" VPN gateways that use, for - instance, one-time passwords or token cards to authenticate the - clients. - - However, most newer EAP methods, such as those typically used with - IEEE 802.11i wireless LANs, provide mutual authentication and key - agreement. Currently, IKEv2 specifies that also these EAP methods - - - -Eronen & Tschofenig Expires December 28, 2006 [Page 2] - -Internet-Draft Extension for EAP in IKEv2 June 2006 - - - must be used together with public key signature based responder - authentication. - - In some environments, requiring the deployment of PKI for just this - purpose can be counterproductive. Deploying new infrastructure can - be expensive, and it may weaken security by creating new - vulnerabilities. Mutually authenticating EAP methods alone can - provide a sufficient level of security in many circumstances, and - indeed, IEEE 802.11i uses EAP without any PKI for authenticating the - WLAN access points. - - This document specifies how EAP methods that offer mutual - authentication and key agreement can be used to provide responder - authentication in IKEv2 completely based on EAP. - -1.1. Terminology - - 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 [2]. - - -2. Scenarios - - In this section we describe two scenarios for extensible - authentication within IKEv2. These scenarios are intended to be - illustrative examples rather than specifying how things should be - done. - - Figure 1 shows a configuration where the EAP and the IKEv2 endpoints - are co-located. Authenticating the IKEv2 responder using both EAP - and public key signatures is redundant. Offering EAP based - authentication has the advantage that multiple different - authentication and key exchange protocols are available with EAP with - different security properties (such as strong password based - protocols, protocols offering user identity confidentiality and many - more). As an example it is possible to use GSS-API support within - EAP [6] to support Kerberos based authentication which effectively - replaces the need for KINK [14]. - - +------+-----+ +------------+ - O | IKEv2 | | IKEv2 | - /|\ | Initiator |<---////////////////////--->| Responder | - / \ +------------+ IKEv2 +------------+ - User | EAP Peer | Exchange | EAP Server | - +------------+ +------------+ - - Figure 1: EAP and IKEv2 endpoints are co-located - - - -Eronen & Tschofenig Expires December 28, 2006 [Page 3] - -Internet-Draft Extension for EAP in IKEv2 June 2006 - - - Figure 2 shows a typical corporate network access scenario. The - initiator (client) interacts with the responder (VPN gateway) in the - corporate network. The EAP exchange within IKE runs between the - client and the home AAA server. As a result of a successful EAP - authentication protocol run, session keys are established and sent - from the AAA server to the VPN gateway, and then used to authenticate - the IKEv2 SA with AUTH payloads. - - The protocol used between the VPN gateway and AAA server could be, - for instance, Diameter [4] or RADIUS [5]. See Section 5 for related - security considerations. - - +-------------------------------+ - | Corporate network | - | | - +-----------+ +--------+ | - | IKEv2 | AAA | Home | | - IKEv2 +////----->+ Responder +<---------->+ AAA | | - Exchange / | (VPN GW) | (RADIUS/ | Server | | - / +-----------+ Diameter) +--------+ | - / | carrying EAP | - | | | - | +-------------------------------+ - v - +------+-----+ - o | IKEv2 | - /|\ | Initiator | - / \ | VPN client | - User +------------+ - - Figure 2: Corporate Network Access - - -3. Solution - - IKEv2 specifies that when the EAP method establishes a shared secret - key, that key is used by both the initiator and responder to generate - an AUTH payload (thus authenticating the IKEv2 SA set up by messages - 1 and 2). - - When used together with public key responder authentication, the - responder is in effect authenticated using two different methods: the - public key signature AUTH payload in message 4, and the EAP-based - AUTH payload later. - - If the initiator does not wish to use public key based responder - authentication, it includes an EAP_ONLY_AUTHENTICATION notification - payload (type TBD-BY-IANA) in message 3. The SPI size field is set - - - -Eronen & Tschofenig Expires December 28, 2006 [Page 4] - -Internet-Draft Extension for EAP in IKEv2 June 2006 - - - to zero, and there is no additional data associated with this - notification. - - If the responder supports this notification, it omits the public key - based AUTH payload and CERT payloads from message 4. - - If the responder does not support the EAP_ONLY_AUTHENTICATION - notification, it ignores the notification payload, and includes the - AUTH payload in message 4. In this case the initiator can, based on - its local policy, choose to either ignore the AUTH payload, or verify - it and any associated certificates as usual. - - Both the initiator and responder MUST verify that the EAP method - actually used provided mutual authentication and established a shared - secret key. The AUTH payloads sent after EAP Success MUST use the - EAP-generated key, and MUST NOT use SK_pi or SK_pr. - - An IKEv2 message exchange with this modification is shown below: - - - Initiator Responder - ----------- ----------- - HDR, SAi1, KEi, Ni, - [N(NAT_DETECTION_SOURCE_IP), - N(NAT_DETECTION_DESTINATION_IP)] --> - - <-- HDR, SAr1, KEr, Nr, [CERTREQ], - [N(NAT_DETECTION_SOURCE_IP), - N(NAT_DETECTION_DESTINATION_IP)] - - HDR, SK { IDi, [IDr], SAi2, TSi, TSr, - N(EAP_ONLY_AUTHENTICATION), - [CP(CFG_REQUEST)] } --> - - <-- HDR, SK { IDr, EAP(Request) } - - HDR, SK { EAP(Response) } --> - - <-- HDR, SK { EAP(Request) } - - HDR, SK { EAP(Response) } --> - - <-- HDR, SK { EAP(Success) } - - HDR, SK { AUTH } --> - - <-- HDR, SK { AUTH, SAr2, TSi, TSr, - [CP(CFG_REPLY] } - - - -Eronen & Tschofenig Expires December 28, 2006 [Page 5] - -Internet-Draft Extension for EAP in IKEv2 June 2006 - - - The NAT detection and Configuration payloads are shown for - informative purposes only; they do not change how EAP authentication - works. - - -4. IANA considerations - - This document defines a new IKEv2 Notification Payload type, - EAP_ONLY_AUTHENTICATION, described in Section 3. This payload must - be assigned a new type number from the "status types" range. - - This document does not define any new namespaces to be managed by - IANA. - - -5. Security Considerations - - Security considerations applicable to all EAP methods are discussed - in [1]. The EAP Key Management Framework [7] deals with issues that - arise when EAP is used as a part of a larger system. - -5.1. Authentication of IKEv2 SA - - It is important to note that the IKEv2 SA is not authenticated by - just running an EAP conversation: the crucial step is the AUTH - payload based on the EAP-generated key. Thus, EAP methods that do - not provide mutual authentication or establish a shared secret key - MUST NOT be used with the modifications presented in this document. - -5.2. Authentication with separated IKEv2 responder/EAP server - - As described in Section 2, the EAP conversation can terminate either - at the IKEv2 responder or at a backend AAA server. - - If the EAP method terminates at the IKEv2 responder then no key - transport via the AAA infrastructure is required. Pre-shared secret - and public key based authentication offered by IKEv2 is then replaced - by a wider range of authentication and key exchange methods. - - However, typically EAP will be used with a backend AAA server. See - [7] for a more complete discussion of the related security issues; - here we provide only a short summary. - - When a backend server is used, there are actually two authentication - exchanges: the EAP method between the client and the AAA server, and - another authentication between the AAA server and IKEv2 gateway. The - AAA server authenticates the client using the selected EAP method, - and they establish a session key. The AAA server then sends this key - - - -Eronen & Tschofenig Expires December 28, 2006 [Page 6] - -Internet-Draft Extension for EAP in IKEv2 June 2006 - - - to the IKEv2 gateway over a connection authenticated using, e.g., - IPsec or TLS. - - Some EAP methods do not have any concept of pass-through - authenticator (e.g., NAS or IKEv2 gateway) identity, and these two - authentications remain quite independent of each other. That is, - after the client has verified the AUTH payload sent by the IKEv2 - gateway, it knows that it is talking to SOME gateway trusted by the - home AAA server, but not which one. The situation is somewhat - similar if a single cryptographic hardware accelerator, containing a - single private key, would be shared between multiple IKEv2 gateways - (perhaps in some kind of cluster configuration). In particular, if - one of the gateways is compromised, it can impersonate any of the - other gateways towards the user (until the compromise is discovered - and access rights revoked). - - In some environments it is not desirable to trust the IKEv2 gateways - this much (also known as the "Lying NAS Problem"). EAP methods that - provide what is called "connection binding" or "channel binding" - transport some identity or identities of the gateway (or WLAN access - point/NAS) inside the EAP method. Then the AAA server can check that - it is indeed sending the key to the gateway expected by the client. - A potential solution is described in [16]. - - In some deployment configurations, AAA proxies may be present between - the IKEv2 gateway and the backend AAA server. These AAA proxies MUST - be trusted for secure operation, and therefore SHOULD be avoided when - possible; see [4] and [7] for more discussion. - -5.3. Protection of EAP payloads - - Although the EAP payloads are encrypted and integrity protected with - SK_e/SK_a, this does not provide any protection against active - attackers. Until the AUTH payload has been received and verified, a - man-in-the-middle can change the KEi/KEr payloads and eavesdrop or - modify the EAP payloads. - - In IEEE 802.11i WLANs, the EAP payloads are neither encrypted nor - integrity protected (by the link layer), so EAP methods are typically - designed to take that into account. - - In particular, EAP methods that are vulnerable to dictionary attacks - when used in WLANs are still vulnerable (to active attackers) when - run inside IKEv2. - -5.4. User identity confidentiality - - IKEv2 provides confidentiality for the initiator identity against - - - -Eronen & Tschofenig Expires December 28, 2006 [Page 7] - -Internet-Draft Extension for EAP in IKEv2 June 2006 - - - passive eavesdroppers, but not against active attackers. The - initiator announces its identity first (in message #3), before the - responder has been authenticated. The usage of EAP in IKEv2 does not - change this situation, since the ID payload in message #3 is used - instead of the EAP Identity Request/Response exchange. This is - somewhat unfortunate since when EAP is used with public key - authentication of the responder, it would be possible to provide - active user identity confidentiality for the initiator. - - IKEv2 protects the responder identity even against active attacks. - This property cannot be provided when using EAP. If public key - responder authentication is used in addition to EAP, the responder - reveals its identity before authenticating the initiator. If only - EAP is used (as proposed in this document), the situation depends on - the EAP method used (in some EAP methods, the server reveals its - identity first). - - Hence, if active user identity confidentiality for the initiator is - required then EAP methods that offer this functionality have to be - used (see [1], Section 7.3). - - -6. Acknowledgments - - This document borrows some text from [1], [3], and [4]. We would - also like to thank Hugo Krawczyk for interesting discussions about - this topic. - - -7. References - -7.1. Normative References - - [1] Aboba, B., Blunk, L., Vollbrecht, J., Carlson, J., and H. - Levkowetz, "Extensible Authentication Protocol (EAP)", RFC 3748, - June 2004. - - [2] Bradner, S., "Key words for use in RFCs to Indicate Requirement - Levels", RFC 2119, March 1997. - - [3] Kaufman, C., "Internet Key Exchange (IKEv2) Protocol", RFC 4306, - December 2005. - - [4] Eronen, P., Hiller, T., and G. Zorn, "Diameter Extensible - Authentication Protocol (EAP) Application", RFC 4072, - August 2005. - - - - - -Eronen & Tschofenig Expires December 28, 2006 [Page 8] - -Internet-Draft Extension for EAP in IKEv2 June 2006 - - -7.2. Informative References - - [5] Aboba, B. and P. Calhoun, "RADIUS (Remote Authentication Dial - In User Service) Support For Extensible Authentication Protocol - (EAP)", RFC 3579, September 2003. - - [6] Aboba, B. and D. Simon, "EAP GSS Authentication Protocol", - draft-aboba-pppext-eapgss-12 (work in progress), April 2002. - - [7] Aboba, B., "Extensible Authentication Protocol (EAP) Key - Management Framework", draft-ietf-eap-keying-13 (work in - progress), May 2006. - - [8] Forsberg, D., "Protocol for Carrying Authentication for Network - Access (PANA)", draft-ietf-pana-pana-11 (work in progress), - March 2006. - - [9] Institute of Electrical and Electronics Engineers, "Local and - Metropolitan Area Networks: Port-Based Network Access Control", - IEEE Standard 802.1X-2001, 2001. - - [10] Institute of Electrical and Electronics Engineers, "Information - technology - Telecommunications and information exchange - between systems - Local and metropolitan area networks - - Specific Requirements Part 11: Wireless LAN Medium Access - Control (MAC) and Physical Layer (PHY) Specifications", IEEE - Standard 802.11-1999, 1999. - - [11] Institute of Electrical and Electronics Engineers, "IEEE - Standard for Information technology - Telecommunications and - information exchange between systems - Local and metropolitan - area networks - Specific requirements - Part 11: Wireless - Medium Access Control (MAC) and Physical Layer (PHY) - specifications: Amendment 6: Medium Access Control (MAC) - Security Enhancements", IEEE Standard 802.11i-2004, July 2004. - - [12] Rigney, C., Willens, S., Rubens, A., and W. Simpson, "Remote - Authentication Dial In User Service (RADIUS)", RFC 2865, - June 2000. - - [13] Simpson, W., "The Point-to-Point Protocol (PPP)", STD 51, - RFC 1661, July 1994. - - [14] Sakane, S., Kamada, K., Thomas, M., and J. Vilhuber, - "Kerberized Internet Negotiation of Keys (KINK)", RFC 4430, - March 2006. - - [15] Tschofenig, H., "EAP IKEv2 Method", - - - -Eronen & Tschofenig Expires December 28, 2006 [Page 9] - -Internet-Draft Extension for EAP in IKEv2 June 2006 - - - draft-tschofenig-eap-ikev2-11 (work in progress), June 2006. - - [16] Arkko, J. and P. Eronen, "Authenticated Service Information for - the Extensible Authentication Protocol (EAP)", - draft-arkko-eap-service-identity-auth-04 (work in progress), - October 2005. - - -Appendix A. Alternative Approaches - - In this section we list alternatives which have been considered - during the work on this document. Finally, the solution presented in - Section 3 seems to fit better into IKEv2. - -A.1. Ignore AUTH payload at the initiator - - With this approach, the initiator simply ignores the AUTH payload in - message #4 (but obviously must check the second AUTH payload later!). - The main advantage of this approach is that no protocol modifications - are required and no signature verification is required. - - The initiator could signal the responder (using a NOTIFY payload) - that it did not verify the first AUTH payload. - -A.2. Unauthenticated PKs in AUTH payload (message 4) - - The first solution approach suggests the use of unauthenticated - public keys in the public key signature AUTH payload (for message 4). - - That is, the initiator verifies the signature in the AUTH payload, - but does not verify that the public key indeed belongs to the - intended party (using certificates)--since it doesn't have a PKI that - would allow this. This could be used with X.509 certificates (the - initiator ignores all other fields of the certificate except the - public key), or "Raw RSA Key" CERT payloads. - - This approach has the advantage that initiators that wish to perform - certificate-based responder authentication (in addition to EAP) may - do so, without requiring the responder to handle these cases - separately. - - If using RSA, the overhead of signature verification is quite small - (compared to g^xy calculation). - -A.3. Use EAP derived session keys for IKEv2 - - It has been proposed that when using an EAP methods that provides - mutual authentication and key agreement, the IKEv2 Diffie-Hellman - - - -Eronen & Tschofenig Expires December 28, 2006 [Page 10] - -Internet-Draft Extension for EAP in IKEv2 June 2006 - - - exchange could also be omitted. This would mean that the sessions - keys for IPsec SAs established later would rely only on EAP-provided - keys. - - It seems the only benefit of this approach is saving some computation - time (g^xy calculation). This approach requires designing a - completely new protocol (which would not resemble IKEv2 anymore) we - do not believe that it should be considered. Nevertheless, we - include it for completeness. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Eronen & Tschofenig Expires December 28, 2006 [Page 11] - -Internet-Draft Extension for EAP in IKEv2 June 2006 - - -Authors' Addresses - - Pasi Eronen - Nokia Research Center - P.O. Box 407 - FIN-00045 Nokia Group - Finland - - Email: pasi.eronen@nokia.com - - - Hannes Tschofenig - Siemens - Otto-Hahn-Ring 6 - Munich, Bayern 81739 - Germany - - Email: Hannes.Tschofenig@siemens.com - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Eronen & Tschofenig Expires December 28, 2006 [Page 12] - -Internet-Draft Extension for EAP in IKEv2 June 2006 - - -Intellectual Property Statement - - The IETF takes no position regarding the validity or scope of any - Intellectual Property Rights or other rights that might be claimed to - pertain to the implementation or use of the technology described in - this document or the extent to which any license under such rights - might or might not be available; nor does it represent that it has - made any independent effort to identify any such rights. Information - on the procedures with respect to rights in RFC documents can be - found in BCP 78 and BCP 79. - - Copies of IPR disclosures made to the IETF Secretariat and any - assurances of licenses to be made available, or the result of an - attempt made to obtain a general license or permission for the use of - such proprietary rights by implementers or users of this - specification can be obtained from the IETF on-line IPR repository at - http://www.ietf.org/ipr. - - The IETF invites any interested party to bring to its attention any - copyrights, patents or patent applications, or other proprietary - rights that may cover technology that may be required to implement - this standard. Please address the information to the IETF at - ietf-ipr@ietf.org. - - -Disclaimer of Validity - - This document and the information contained herein are provided on an - "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS - OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET - ENGINEERING TASK FORCE DISCLAIM 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. - - -Copyright Statement - - Copyright (C) The Internet Society (2006). This document is subject - to the rights, licenses and restrictions contained in BCP 78, and - except as set forth therein, the authors retain all their rights. - - -Acknowledgment - - Funding for the RFC Editor function is currently provided by the - Internet Society. - - - - -Eronen & Tschofenig Expires December 28, 2006 [Page 13] - - diff --git a/src/charon/doc/standards/draft-hoffman-ikev2-1-00.txt b/src/charon/doc/standards/draft-hoffman-ikev2-1-00.txt deleted file mode 100644 index cd6b0ec22..000000000 --- a/src/charon/doc/standards/draft-hoffman-ikev2-1-00.txt +++ /dev/null @@ -1,6720 +0,0 @@ - - - -Network Working Group P. Hoffman -Internet-Draft VPN Consortium -Expires: July 5, 2006 January 2006 - - - Internet Key Exchange Protocol: IKEv2.1 - draft-hoffman-ikev2-1-00.txt - -Status of this Memo - - By submitting this Internet-Draft, each author represents that any - applicable patent or other IPR claims of which he or she is aware - have been or will be disclosed, and any of which he or she becomes - aware will be disclosed, in accordance with Section 6 of BCP 79. - - 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 July 5, 2006. - -Copyright Notice - - Copyright (C) The Internet Society (2006). - -Abstract - - This document describes version 2.1 of the Internet Key Exchange - (IKE) protocol. IKEv2.1 is heavily based on IKEv2 from RFC 4306 - (edited by Charlie Kaufman), and includes all of the clarifications - from the "IKEv2 Clarifications" document (edited by Pasi Eronen and - Paul Hoffman). IKEv2.1 makes additional changes to those two - documents in places where IKEv2 was unclear and the clarifications - document did not commit to a particular protocol interpretation. - - - - - -Hoffman Expires July 5, 2006 [Page 1] - -Internet-Draft IKEv2 January 2006 - - -Table of Contents - - 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5 - 1.1. Usage Scenarios . . . . . . . . . . . . . . . . . . . . . 6 - 1.1.1. Security Gateway to Security Gateway Tunnel . . . . . 7 - 1.1.2. Endpoint-to-Endpoint Transport . . . . . . . . . . . 7 - 1.1.3. Endpoint to Security Gateway Tunnel . . . . . . . . . 8 - 1.1.4. Other Scenarios . . . . . . . . . . . . . . . . . . . 9 - 1.2. The Initial Exchanges . . . . . . . . . . . . . . . . . . 9 - 1.3. The CREATE_CHILD_SA Exchange . . . . . . . . . . . . . . 12 - 1.3.1. Creating New CHILD_SAs with the CREATE_CHILD_SA - Exchange . . . . . . . . . . . . . . . . . . . . . . 13 - 1.3.2. Rekeying IKE_SAs with the CREATE_CHILD_SA Exchange . 13 - 1.3.3. Rekeying CHILD_SAs with the CREATE_CHILD_SA - Exchange . . . . . . . . . . . . . . . . . . . . . . 14 - 1.4. The INFORMATIONAL Exchange . . . . . . . . . . . . . . . 15 - 1.5. Informational Messages outside of an IKE_SA . . . . . . . 16 - 1.6. Requirements Terminology . . . . . . . . . . . . . . . . 17 - 1.7. Introduction to IKEv2.1 . . . . . . . . . . . . . . . . . 17 - 2. IKE Protocol Details and Variations . . . . . . . . . . . . . 18 - 2.1. Use of Retransmission Timers . . . . . . . . . . . . . . 19 - 2.2. Use of Sequence Numbers for Message ID . . . . . . . . . 19 - 2.3. Window Size for Overlapping Requests . . . . . . . . . . 20 - 2.4. State Synchronization and Connection Timeouts . . . . . . 21 - 2.5. Version Numbers and Forward Compatibility . . . . . . . . 23 - 2.6. Cookies . . . . . . . . . . . . . . . . . . . . . . . . . 25 - 2.6.1. Interaction of COOKIE and INVALID_KE_PAYLOAD . . . . 27 - 2.7. Cryptographic Algorithm Negotiation . . . . . . . . . . . 28 - 2.8. Rekeying . . . . . . . . . . . . . . . . . . . . . . . . 29 - 2.8.1. Simultaneous CHILD_SA rekeying . . . . . . . . . . . 31 - 2.8.2. Rekeying the IKE_SA Versus Reauthentication . . . . . 33 - 2.9. Traffic Selector Negotiation . . . . . . . . . . . . . . 34 - 2.9.1. Traffic Selectors Violating Own Policy . . . . . . . 37 - 2.10. Nonces . . . . . . . . . . . . . . . . . . . . . . . . . 38 - 2.11. Address and Port Agility . . . . . . . . . . . . . . . . 38 - 2.12. Reuse of Diffie-Hellman Exponentials . . . . . . . . . . 38 - 2.13. Generating Keying Material . . . . . . . . . . . . . . . 39 - 2.14. Generating Keying Material for the IKE_SA . . . . . . . . 40 - 2.15. Authentication of the IKE_SA . . . . . . . . . . . . . . 41 - 2.16. Extensible Authentication Protocol Methods . . . . . . . 43 - 2.17. Generating Keying Material for CHILD_SAs . . . . . . . . 45 - 2.18. Rekeying IKE_SAs Using a CREATE_CHILD_SA Exchange . . . . 46 - 2.19. Requesting an Internal Address on a Remote Network . . . 47 - 2.20. Requesting the Peer's Version . . . . . . . . . . . . . . 48 - 2.21. Error Handling . . . . . . . . . . . . . . . . . . . . . 49 - 2.22. IPComp . . . . . . . . . . . . . . . . . . . . . . . . . 50 - 2.23. NAT Traversal . . . . . . . . . . . . . . . . . . . . . . 50 - 2.24. Explicit Congestion Notification (ECN) . . . . . . . . . 53 - - - -Hoffman Expires July 5, 2006 [Page 2] - -Internet-Draft IKEv2 January 2006 - - - 3. Header and Payload Formats . . . . . . . . . . . . . . . . . 53 - 3.1. The IKE Header . . . . . . . . . . . . . . . . . . . . . 53 - 3.2. Generic Payload Header . . . . . . . . . . . . . . . . . 56 - 3.3. Security Association Payload . . . . . . . . . . . . . . 58 - 3.3.1. Proposal Substructure . . . . . . . . . . . . . . . . 60 - 3.3.2. Transform Substructure . . . . . . . . . . . . . . . 62 - 3.3.3. Valid Transform Types by Protocol . . . . . . . . . . 64 - 3.3.4. Mandatory Transform IDs . . . . . . . . . . . . . . . 65 - 3.3.5. Transform Attributes . . . . . . . . . . . . . . . . 66 - 3.3.6. Attribute Negotiation . . . . . . . . . . . . . . . . 67 - 3.4. Key Exchange Payload . . . . . . . . . . . . . . . . . . 68 - 3.5. Identification Payloads . . . . . . . . . . . . . . . . . 69 - 3.6. Certificate Payload . . . . . . . . . . . . . . . . . . . 71 - 3.7. Certificate Request Payload . . . . . . . . . . . . . . . 74 - 3.8. Authentication Payload . . . . . . . . . . . . . . . . . 76 - 3.9. Nonce Payload . . . . . . . . . . . . . . . . . . . . . . 77 - 3.10. Notify Payload . . . . . . . . . . . . . . . . . . . . . 77 - 3.10.1. Notify Message Types . . . . . . . . . . . . . . . . 78 - 3.11. Delete Payload . . . . . . . . . . . . . . . . . . . . . 84 - 3.12. Vendor ID Payload . . . . . . . . . . . . . . . . . . . . 85 - 3.13. Traffic Selector Payload . . . . . . . . . . . . . . . . 86 - 3.13.1. Traffic Selector . . . . . . . . . . . . . . . . . . 88 - 3.14. Encrypted Payload . . . . . . . . . . . . . . . . . . . . 90 - 3.15. Configuration Payload . . . . . . . . . . . . . . . . . . 92 - 3.15.1. Configuration Attributes . . . . . . . . . . . . . . 94 - 3.15.2. Meaning of INTERNAL_IP4_SUBNET/INTERNAL_IP6_SUBNET . 97 - 3.15.3. Configuration payloads for IPv6 . . . . . . . . . . . 99 - 3.15.4. Address Assignment Failures . . . . . . . . . . . . . 100 - 3.16. Extensible Authentication Protocol (EAP) Payload . . . . 100 - 4. Conformance Requirements . . . . . . . . . . . . . . . . . . 102 - 5. Security Considerations . . . . . . . . . . . . . . . . . . . 104 - 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 107 - 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 107 - 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 108 - 8.1. Normative References . . . . . . . . . . . . . . . . . . 108 - 8.2. Informative References . . . . . . . . . . . . . . . . . 109 - Appendix A. Summary of changes from IKEv1 . . . . . . . . . . . 112 - Appendix B. Diffie-Hellman Groups . . . . . . . . . . . . . . . 114 - B.1. Group 1 - 768 Bit MODP . . . . . . . . . . . . . . . . . 114 - B.2. Group 2 - 1024 Bit MODP . . . . . . . . . . . . . . . . . 114 - Appendix C. Exchanges and Payloads . . . . . . . . . . . . . . . 115 - C.1. IKE_SA_INIT Exchange . . . . . . . . . . . . . . . . . . 115 - C.2. IKE_AUTH Exchange without EAP . . . . . . . . . . . . . . 116 - C.3. IKE_AUTH Exchange with EAP . . . . . . . . . . . . . . . 117 - C.4. CREATE_CHILD_SA Exchange for Creating or Rekeying - CHILD_SAs . . . . . . . . . . . . . . . . . . . . . . . . 118 - C.5. CREATE_CHILD_SA Exchange for Rekeying the IKE_SA . . . . 118 - C.6. INFORMATIONAL Exchange . . . . . . . . . . . . . . . . . 118 - - - -Hoffman Expires July 5, 2006 [Page 3] - -Internet-Draft IKEv2 January 2006 - - - Appendix D. Changes Between Internet Draft Versions . . . . . . 118 - D.1. Changes from IKEv2 to draft -00 . . . . . . . . . . . . . 118 - Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 119 - Intellectual Property and Copyright Statements . . . . . . . . . 119 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Hoffman Expires July 5, 2006 [Page 4] - -Internet-Draft IKEv2 January 2006 - - -1. Introduction - - {{ An introduction to IKEv2.1 is given at the end of Section 1. It - is put there (instead of here) to preserve the section numbering of - the original IKEv2 document. }} - - IP Security (IPsec) provides confidentiality, data integrity, access - control, and data source authentication to IP datagrams. These - services are provided by maintaining shared state between the source - and the sink of an IP datagram. This state defines, among other - things, the specific services provided to the datagram, which - cryptographic algorithms will be used to provide the services, and - the keys used as input to the cryptographic algorithms. - - Establishing this shared state in a manual fashion does not scale - well. Therefore, a protocol to establish this state dynamically is - needed. This memo describes such a protocol -- the Internet Key - Exchange (IKE). This is version 2.1 of IKE. Version 1 of IKE was - defined in RFCs 2407 [DOI], 2408 [ISAKMP], and 2409 [IKEV1]. IKEv2 - was defined in [IKEV2]. This single document is intended to replace - all three of those RFCs. - - Definitions of the primitive terms in this document (such as Security - Association or SA) can be found in [IPSECARCH]. {{ Clarif-7.2 }} It - should be noted that parts of IKEv2 and IKEv2.1 rely on some of the - processing rules in [IPSECARCH], as described in various sections of - this document. - - IKE performs mutual authentication between two parties and - establishes an IKE security association (SA) that includes shared - secret information that can be used to efficiently establish SAs for - Encapsulating Security Payload (ESP) [ESP] and/or Authentication - Header (AH) [AH] and a set of cryptographic algorithms to be used by - the SAs to protect the traffic that they carry. In this document, - the term "suite" or "cryptographic suite" refers to a complete set of - algorithms used to protect an SA. An initiator proposes one or more - suites by listing supported algorithms that can be combined into - suites in a mix-and-match fashion. IKE can also negotiate use of IP - Compression (IPComp) [IPCOMP] in connection with an ESP and/or AH SA. - We call the IKE SA an "IKE_SA". The SAs for ESP and/or AH that get - set up through that IKE_SA we call "CHILD_SAs". - - All IKE communications consist of pairs of messages: a request and a - response. The pair is called an "exchange". We call the first - messages establishing an IKE_SA IKE_SA_INIT and IKE_AUTH exchanges - and subsequent IKE exchanges CREATE_CHILD_SA or INFORMATIONAL - exchanges. In the common case, there is a single IKE_SA_INIT - exchange and a single IKE_AUTH exchange (a total of four messages) to - - - -Hoffman Expires July 5, 2006 [Page 5] - -Internet-Draft IKEv2 January 2006 - - - establish the IKE_SA and the first CHILD_SA. In exceptional cases, - there may be more than one of each of these exchanges. In all cases, - all IKE_SA_INIT exchanges MUST complete before any other exchange - type, then all IKE_AUTH exchanges MUST complete, and following that - any number of CREATE_CHILD_SA and INFORMATIONAL exchanges may occur - in any order. In some scenarios, only a single CHILD_SA is needed - between the IPsec endpoints, and therefore there would be no - additional exchanges. Subsequent exchanges MAY be used to establish - additional CHILD_SAs between the same authenticated pair of endpoints - and to perform housekeeping functions. - - IKE message flow always consists of a request followed by a response. - It is the responsibility of the requester to ensure reliability. If - the response is not received within a timeout interval, the requester - needs to retransmit the request (or abandon the connection). - - The first request/response of an IKE session (IKE_SA_INIT) negotiates - security parameters for the IKE_SA, sends nonces, and sends Diffie- - Hellman values. - - The second request/response (IKE_AUTH) transmits identities, proves - knowledge of the secrets corresponding to the two identities, and - sets up an SA for the first (and often only) AH and/or ESP CHILD_SA. - - The types of subsequent exchanges are CREATE_CHILD_SA (which creates - a CHILD_SA) and INFORMATIONAL (which deletes an SA, reports error - conditions, or does other housekeeping). Every request requires a - response. An INFORMATIONAL request with no payloads (other than the - empty Encrypted payload required by the syntax) is commonly used as a - check for liveness. These subsequent exchanges cannot be used until - the initial exchanges have completed. - - In the description that follows, we assume that no errors occur. - Modifications to the flow should errors occur are described in - Section 2.21. - -1.1. Usage Scenarios - - IKE is expected to be used to negotiate ESP and/or AH SAs in a number - of different scenarios, each with its own special requirements. - - - - - - - - - - - -Hoffman Expires July 5, 2006 [Page 6] - -Internet-Draft IKEv2 January 2006 - - -1.1.1. Security Gateway to Security Gateway Tunnel - - +-+-+-+-+-+ +-+-+-+-+-+ - ! ! IPsec ! ! - Protected !Tunnel ! tunnel !Tunnel ! Protected - Subnet <-->!Endpoint !<---------->!Endpoint !<--> Subnet - ! ! ! ! - +-+-+-+-+-+ +-+-+-+-+-+ - - Figure 1: Security Gateway to Security Gateway Tunnel - - In this scenario, neither endpoint of the IP connection implements - IPsec, but network nodes between them protect traffic for part of the - way. Protection is transparent to the endpoints, and depends on - ordinary routing to send packets through the tunnel endpoints for - processing. Each endpoint would announce the set of addresses - "behind" it, and packets would be sent in tunnel mode where the inner - IP header would contain the IP addresses of the actual endpoints. - -1.1.2. Endpoint-to-Endpoint Transport - - +-+-+-+-+-+ +-+-+-+-+-+ - ! ! IPsec transport ! ! - !Protected! or tunnel mode SA !Protected! - !Endpoint !<---------------------------------------->!Endpoint ! - ! ! ! ! - +-+-+-+-+-+ +-+-+-+-+-+ - - Figure 2: Endpoint to Endpoint - - In this scenario, both endpoints of the IP connection implement - IPsec, as required of hosts in [IPSECARCH]. Transport mode will - commonly be used with no inner IP header. If there is an inner IP - header, the inner addresses will be the same as the outer addresses. - A single pair of addresses will be negotiated for packets to be - protected by this SA. These endpoints MAY implement application - layer access controls based on the IPsec authenticated identities of - the participants. This scenario enables the end-to-end security that - has been a guiding principle for the Internet since [ARCHPRINC], - [TRANSPARENCY], and a method of limiting the inherent problems with - complexity in networks noted by [ARCHGUIDEPHIL]. Although this - scenario may not be fully applicable to the IPv4 Internet, it has - been deployed successfully in specific scenarios within intranets - using IKEv1. It should be more broadly enabled during the transition - to IPv6 and with the adoption of IKEv2. - - It is possible in this scenario that one or both of the protected - endpoints will be behind a network address translation (NAT) node, in - - - -Hoffman Expires July 5, 2006 [Page 7] - -Internet-Draft IKEv2 January 2006 - - - which case the tunneled packets will have to be UDP encapsulated so - that port numbers in the UDP headers can be used to identify - individual endpoints "behind" the NAT (see Section 2.23). - -1.1.3. Endpoint to Security Gateway Tunnel - - +-+-+-+-+-+ +-+-+-+-+-+ - ! ! IPsec ! ! Protected - !Protected! tunnel !Tunnel ! Subnet - !Endpoint !<------------------------>!Endpoint !<--- and/or - ! ! ! ! Internet - +-+-+-+-+-+ +-+-+-+-+-+ - - Figure 3: Endpoint to Security Gateway Tunnel - - In this scenario, a protected endpoint (typically a portable roaming - computer) connects back to its corporate network through an IPsec- - protected tunnel. It might use this tunnel only to access - information on the corporate network, or it might tunnel all of its - traffic back through the corporate network in order to take advantage - of protection provided by a corporate firewall against Internet-based - attacks. In either case, the protected endpoint will want an IP - address associated with the security gateway so that packets returned - to it will go to the security gateway and be tunneled back. This IP - address may be static or may be dynamically allocated by the security - gateway. {{ Clarif-6.1 }} In support of the latter case, IKEv2 - includes a mechanism (namely, configuration payloads) for the - initiator to request an IP address owned by the security gateway for - use for the duration of its SA. - - In this scenario, packets will use tunnel mode. On each packet from - the protected endpoint, the outer IP header will contain the source - IP address associated with its current location (i.e., the address - that will get traffic routed to the endpoint directly), while the - inner IP header will contain the source IP address assigned by the - security gateway (i.e., the address that will get traffic routed to - the security gateway for forwarding to the endpoint). The outer - destination address will always be that of the security gateway, - while the inner destination address will be the ultimate destination - for the packet. - - In this scenario, it is possible that the protected endpoint will be - behind a NAT. In that case, the IP address as seen by the security - gateway will not be the same as the IP address sent by the protected - endpoint, and packets will have to be UDP encapsulated in order to be - routed properly. - - - - - -Hoffman Expires July 5, 2006 [Page 8] - -Internet-Draft IKEv2 January 2006 - - -1.1.4. Other Scenarios - - Other scenarios are possible, as are nested combinations of the - above. One notable example combines aspects of 1.1.1 and 1.1.3. A - subnet may make all external accesses through a remote security - gateway using an IPsec tunnel, where the addresses on the subnet are - routed to the security gateway by the rest of the Internet. An - example would be someone's home network being virtually on the - Internet with static IP addresses even though connectivity is - provided by an ISP that assigns a single dynamically assigned IP - address to the user's security gateway (where the static IP addresses - and an IPsec relay are provided by a third party located elsewhere). - -1.2. The Initial Exchanges - - Communication using IKE always begins with IKE_SA_INIT and IKE_AUTH - exchanges (known in IKEv1 as Phase 1). These initial exchanges - normally consist of four messages, though in some scenarios that - number can grow. All communications using IKE consist of request/ - response pairs. We'll describe the base exchange first, followed by - variations. The first pair of messages (IKE_SA_INIT) negotiate - cryptographic algorithms, exchange nonces, and do a Diffie-Hellman - exchange [DH]. - - The second pair of messages (IKE_AUTH) authenticate the previous - messages, exchange identities and certificates, and establish the - first CHILD_SA. Parts of these messages are encrypted and integrity - protected with keys established through the IKE_SA_INIT exchange, so - the identities are hidden from eavesdroppers and all fields in all - the messages are authenticated. - - In the following descriptions, the payloads contained in the message - are indicated by names as listed below. - - - - - - - - - - - - - - - - - - -Hoffman Expires July 5, 2006 [Page 9] - -Internet-Draft IKEv2 January 2006 - - - Notation Payload - ----------------------------------------- - AUTH Authentication - CERT Certificate - CERTREQ Certificate Request - CP Configuration - D Delete - E Encrypted - EAP Extensible Authentication - HDR IKE Header - IDi Identification - Initiator - IDr Identification - Responder - KE Key Exchange - Ni, Nr Nonce - N Notify - SA Security Association - TSi Traffic Selector - Initiator - TSr Traffic Selector - Responder - V Vendor ID - - The details of the contents of each payload are described in section - 3. Payloads that may optionally appear will be shown in brackets, - such as [CERTREQ], indicate that optionally a certificate request - payload can be included. - - {{ Clarif-7.10 }} Many payloads contain fields marked as "RESERVED" - Some payloads in IKEv2 (and historically in IKEv1) are not aligned to - 4-byte boundaries. - - The initial exchanges are as follows: - - Initiator Responder - ------------------------------------------------------------------- - HDR, SAi1, KEi, Ni --> - - HDR contains the Security Parameter Indexes (SPIs), version numbers, - and flags of various sorts. The SAi1 payload states the - cryptographic algorithms the initiator supports for the IKE_SA. The - KE payload sends the initiator's Diffie-Hellman value. Ni is the - initiator's nonce. - - <-- HDR, SAr1, KEr, Nr, [CERTREQ] - - The responder chooses a cryptographic suite from the initiator's - offered choices and expresses that choice in the SAr1 payload, - completes the Diffie-Hellman exchange with the KEr payload, and sends - its nonce in the Nr payload. - - - - -Hoffman Expires July 5, 2006 [Page 10] - -Internet-Draft IKEv2 January 2006 - - - At this point in the negotiation, each party can generate SKEYSEED, - from which all keys are derived for that IKE_SA. All but the headers - of all the messages that follow are encrypted and integrity - protected. The keys used for the encryption and integrity protection - are derived from SKEYSEED and are known as SK_e (encryption) and SK_a - (authentication, a.k.a. integrity protection). A separate SK_e and - SK_a is computed for each direction. In addition to the keys SK_e - and SK_a derived from the DH value for protection of the IKE_SA, - another quantity SK_d is derived and used for derivation of further - keying material for CHILD_SAs. The notation SK { ... } indicates - that these payloads are encrypted and integrity protected using that - direction's SK_e and SK_a. - - HDR, SK {IDi, [CERT,] [CERTREQ,] - [IDr,] AUTH, SAi2, - TSi, TSr} --> - - The initiator asserts its identity with the IDi payload, proves - knowledge of the secret corresponding to IDi and integrity protects - the contents of the first message using the AUTH payload (see - Section 2.15). It might also send its certificate(s) in CERT - payload(s) and a list of its trust anchors in CERTREQ payload(s). If - any CERT payloads are included, the first certificate provided MUST - contain the public key used to verify the AUTH field. The optional - payload IDr enables the initiator to specify which of the responder's - identities it wants to talk to. This is useful when the machine on - which the responder is running is hosting multiple identities at the - same IP address. The initiator begins negotiation of a CHILD_SA - using the SAi2 payload. The final fields (starting with SAi2) are - described in the description of the CREATE_CHILD_SA exchange. - - <-- HDR, SK {IDr, [CERT,] AUTH, - SAr2, TSi, TSr} - - The responder asserts its identity with the IDr payload, optionally - sends one or more certificates (again with the certificate containing - the public key used to verify AUTH listed first), authenticates its - identity and protects the integrity of the second message with the - AUTH payload, and completes negotiation of a CHILD_SA with the - additional fields described below in the CREATE_CHILD_SA exchange. - - The recipients of messages 3 and 4 MUST verify that all signatures - and MACs are computed correctly and that the names in the ID payloads - correspond to the keys used to generate the AUTH payload. - - {{ Clarif-4.2}} If creating the CHILD_SA during the IKE_AUTH exchange - fails for some reason, the IKE_SA is still created as usual. The - list of responses in the IKE_AUTH exchange that do not prevent an - - - -Hoffman Expires July 5, 2006 [Page 11] - -Internet-Draft IKEv2 January 2006 - - - IKE_SA from being set up include at least the following: - NO_PROPOSAL_CHOSEN, TS_UNACCEPTABLE, SINGLE_PAIR_REQUIRED, - INTERNAL_ADDRESS_FAILURE, and FAILED_CP_REQUIRED. - - {{ Clarif-4.3 }} Note that IKE_AUTH messages do not contain KEi/KEr - or Ni/Nr payloads. Thus, the SA payload in IKE_AUTH exchange cannot - contain Transform Type 4 (Diffie-Hellman Group) with any other value - than NONE. Implementations MUST leave the transform out entirely in - this case. - -1.3. The CREATE_CHILD_SA Exchange - - {{ This is a heavy rewrite of most of this section. The major - organization changes are described in Clarif-4.1 and Clarif-5.1. }} - - The CREATE_CHILD_SA exchange is used to create new CHILD_SAs and to - rekey both IKE_SAs and CHILD_SAs. This exchange consists of a single - request/response pair, and some of its function was referred to as a - phase 2 exchange in IKEv1. It MAY be initiated by either end of the - IKE_SA after the initial exchanges are completed. - - All messages following the initial exchange are cryptographically - protected using the cryptographic algorithms and keys negotiated in - the first two messages of the IKE exchange. These subsequent - messages use the syntax of the Encrypted Payload described in - Section 3.14. All subsequent messages included an Encrypted Payload, - even if they are referred to in the text as "empty". For both - messages in the CREATE_CHILD_SA, the message following the header is - encrypted and the message including the header is integrity protected - using the cryptographic algorithms negotiated for the IKE_SA. - - The CREATE_CHILD_SA is used for rekeying IKE_SAs and CHILD_SAs. This - section describes the first part of rekeying, the creation of new - SAs; Section 2.8 covers the mechanics of rekeying, including moving - traffic from old to new SAs and the deletion of the old SAs. The two - sections must be read together to understand the entire process of - rekeying. - - Either endpoint may initiate a CREATE_CHILD_SA exchange, so in this - section the term initiator refers to the endpoint initiating this - exchange. An implementation MAY refuse all CREATE_CHILD_SA requests - within an IKE_SA. - - The CREATE_CHILD_SA request MAY optionally contain a KE payload for - an additional Diffie-Hellman exchange to enable stronger guarantees - of forward secrecy for the CHILD_SA. The keying material for the - CHILD_SA is a function of SK_d established during the establishment - of the IKE_SA, the nonces exchanged during the CREATE_CHILD_SA - - - -Hoffman Expires July 5, 2006 [Page 12] - -Internet-Draft IKEv2 January 2006 - - - exchange, and the Diffie-Hellman value (if KE payloads are included - in the CREATE_CHILD_SA exchange). - - If a CREATE_CHILD_SA exchange includes a KEi payload, at least one of - the SA offers MUST include the Diffie-Hellman group of the KEi. The - Diffie-Hellman group of the KEi MUST be an element of the group the - initiator expects the responder to accept (additional Diffie-Hellman - groups can be proposed). If the responder rejects the Diffie-Hellman - group of the KEi payload, the responder MUST reject the request and - indicate its preferred Diffie-Hellman group in the INVALID_KE_PAYLOAD - Notification payload. In the case of such a rejection, the - CREATE_CHILD_SA exchange fails, and the initiator will probably retry - the exchange with a Diffie-Hellman proposal and KEi in the group that - the responder gave in the INVALID_KE_PAYLOAD. - -1.3.1. Creating New CHILD_SAs with the CREATE_CHILD_SA Exchange - - A CHILD_SA may be created by sending a CREATE_CHILD_SA request. The - CREATE_CHILD_SA request for creating a new CHILD_SA is: - - Initiator Responder - ------------------------------------------------------------------- - HDR, SK {SA, Ni, [KEi], - TSi, TSr} --> - - The initiator sends SA offer(s) in the SA payload, a nonce in the Ni - payload, optionally a Diffie-Hellman value in the KEi payload, and - the proposed traffic selectors for the proposed CHILD_SA in the TSi - and TSr payloads. - - The CREATE_CHILD_SA response for creating a new CHILD_SA is: - - <-- HDR, SK {SA, Nr, [KEr], - TSi, TSr} - - The responder replies (using the same Message ID to respond) with the - accepted offer in an SA payload, and a Diffie-Hellman value in the - KEr payload if KEi was included in the request and the selected - cryptographic suite includes that group. - - The traffic selectors for traffic to be sent on that SA are specified - in the TS payloads in the response, which may be a subset of what the - initiator of the CHILD_SA proposed. - -1.3.2. Rekeying IKE_SAs with the CREATE_CHILD_SA Exchange - - The CREATE_CHILD_SA request for rekeying an IKE_SA is: - - - - -Hoffman Expires July 5, 2006 [Page 13] - -Internet-Draft IKEv2 January 2006 - - - Initiator Responder - ------------------------------------------------------------------- - HDR, SK {SA, Ni, KEi} --> - - The initiator sends SA offer(s) in the SA payload, a nonce in the Ni - payload, and a Diffie-Hellman value in the KEi payload. New - initiator and responder SPIs are supplied in the SPI fields. - - The CREATE_CHILD_SA response for rekeying an IKE_SA is: - - <-- HDR, SK {SA, Nr, KEr} - - The responder replies (using the same Message ID to respond) with the - accepted offer in an SA payload, and a Diffie-Hellman value in the - KEr payload if the selected cryptographic suite includes that group. - - The new IKE_SA has its message counters set to 0, regardless of what - they were in the earlier IKE_SA. The window size starts at 1 for any - new IKE_SA. - - KEi and KEr are required for rekeying an IKE_SA. - -1.3.3. Rekeying CHILD_SAs with the CREATE_CHILD_SA Exchange - - The CREATE_CHILD_SA request for rekeying a CHILD_SA is: - - Initiator Responder - ------------------------------------------------------------------- - HDR, SK {N, SA, Ni, [KEi], - TSi, TSr} --> - - The initiator sends SA offer(s) in the SA payload, a nonce in the Ni - payload, optionally a Diffie-Hellman value in the KEi payload, and - the proposed traffic selectors for the proposed CHILD_SA in the TSi - and TSr payloads. When rekeying an existing CHILD_SA, the leading N - payload of type REKEY_SA MUST be included and MUST give the SPI (as - they would be expected in the headers of inbound packets) of the SAs - being rekeyed. - - The CREATE_CHILD_SA response for rekeying a CHILD_SA is: - - <-- HDR, SK {SA, Nr, [KEr], - Si, TSr} - - The responder replies (using the same Message ID to respond) with the - accepted offer in an SA payload, and a Diffie-Hellman value in the - KEr payload if KEi was included in the request and the selected - cryptographic suite includes that group. - - - -Hoffman Expires July 5, 2006 [Page 14] - -Internet-Draft IKEv2 January 2006 - - - The traffic selectors for traffic to be sent on that SA are specified - in the TS payloads in the response, which may be a subset of what the - initiator of the CHILD_SA proposed. - -1.4. The INFORMATIONAL Exchange - - At various points during the operation of an IKE_SA, peers may desire - to convey control messages to each other regarding errors or - notifications of certain events. To accomplish this, IKE defines an - INFORMATIONAL exchange. INFORMATIONAL exchanges MUST ONLY occur - after the initial exchanges and are cryptographically protected with - the negotiated keys. - - Control messages that pertain to an IKE_SA MUST be sent under that - IKE_SA. Control messages that pertain to CHILD_SAs MUST be sent - under the protection of the IKE_SA which generated them (or its - successor if the IKE_SA was replaced for the purpose of rekeying). - - Messages in an INFORMATIONAL exchange contain zero or more - Notification, Delete, and Configuration payloads. The Recipient of - an INFORMATIONAL exchange request MUST send some response (else the - Sender will assume the message was lost in the network and will - retransmit it). That response MAY be a message with no payloads. - The request message in an INFORMATIONAL exchange MAY also contain no - payloads. This is the expected way an endpoint can ask the other - endpoint to verify that it is alive. - - {{ Clarif-5.6 }} ESP and AH SAs always exist in pairs, with one SA in - each direction. When an SA is closed, both members of the pair MUST - be closed (that is, deleted). When SAs are nested, as when data (and - IP headers if in tunnel mode) are encapsulated first with IPComp, - then with ESP, and finally with AH between the same pair of - endpoints, all of the SAs MUST be deleted together. Each endpoint - MUST close its incoming SAs and allow the other endpoint to close the - other SA in each pair. To delete an SA, an INFORMATIONAL exchange - with one or more delete payloads is sent listing the SPIs (as they - would be expected in the headers of inbound packets) of the SAs to be - deleted. The recipient MUST close the designated SAs. {{ Clarif-5.7 - }} Note that you never send delete payloads for the two sides of an - SA in a single message. If you have many SAs to delete at the same - time (such as for nested SAs), you include delete payloads for in - inbound half of each SA in your Informational exchange. - - Normally, the reply in the INFORMATIONAL exchange will contain delete - payloads for the paired SAs going in the other direction. There is - one exception. If by chance both ends of a set of SAs independently - decide to close them, each may send a delete payload and the two - requests may cross in the network. If a node receives a delete - - - -Hoffman Expires July 5, 2006 [Page 15] - -Internet-Draft IKEv2 January 2006 - - - request for SAs for which it has already issued a delete request, it - MUST delete the outgoing SAs while processing the request and the - incoming SAs while processing the response. In that case, the - responses MUST NOT include delete payloads for the deleted SAs, since - that would result in duplicate deletion and could in theory delete - the wrong SA. - - {{ Demoted the SHOULD }} Half-closed connections are anomalous and, - and a node with auditing capability will probably audit their - existence if they persist. Note that this specification nowhere - specifies time periods, so it is up to individual endpoints to decide - how long to wait. A node MAY refuse to accept incoming data on half- - closed connections but MUST NOT unilaterally close them and reuse the - SPIs. If connection state becomes sufficiently messed up, a node MAY - close the IKE_SA; doing so will implicitly close all SAs negotiated - under it. It can then rebuild the SAs it needs on a clean base under - a new IKE_SA. {{ Clarif-5.8 }} The response to a request that deletes - the IKE_SA is an empty Informational response. - - The INFORMATIONAL exchange is defined as: - - Initiator Responder - ------------------------------------------------------------------- - HDR, SK {[N,] [D,] - [CP,] ...} --> - <-- HDR, SK {[N,] [D,] - [CP], ...} - - The processing of an INFORMATIONAL exchange is determined by its - component payloads. - -1.5. Informational Messages outside of an IKE_SA - - If an encrypted IKE packet arrives on port 500 or 4500 with an - unrecognized SPI, it could be because the receiving node has recently - crashed and lost state or because of some other system malfunction or - attack. If the receiving node has an active IKE_SA to the IP address - from whence the packet came, it MAY send a notification of the - wayward packet over that IKE_SA in an INFORMATIONAL exchange. If it - does not have such an IKE_SA, it MAY send an Informational message - without cryptographic protection to the source IP address. Such a - message is not part of an informational exchange, and the receiving - node MUST NOT respond to it. Doing so could cause a message loop. - - {{ Clarif-7.7 }} There are two cases when such a one-way notification - is sent: INVALID_IKE_SPI and INVALID_SPI. These notifications are - sent outside of an IKE_SA. Note that such notifications are - explicitly not Informational exchanges; these are one-way messages - - - -Hoffman Expires July 5, 2006 [Page 16] - -Internet-Draft IKEv2 January 2006 - - - that must not be responded to. In case of INVALID_IKE_SPI, the - message sent is a response message, and thus it is sent to the IP - address and port from whence it came with the same IKE SPIs and the - Message ID copied. In case of INVALID_SPI, however, there are no IKE - SPI values that would be meaningful to the recipient of such a - notification. Using zero values or random values are both - acceptable. - -1.6. Requirements Terminology - - Keywords "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT" and - "MAY" that appear in this document are to be interpreted as described - in [MUSTSHOULD]. - - The term "Expert Review" is to be interpreted as defined in - [IANACONS]. - -1.7. Introduction to IKEv2.1 - - IKEv2.1 is very similar to IKEv2. Most of the differences between - this document at [IKEV2] are clarifications, mostly based on - [Clarif]. The changes listed in that document were discussed in the - IPsec Working Group and, after the Working Group was disbanded, on - the IPsec mailing list. That document contains detailed explanations - of areas that were unclear in IKEv2, and is thus useful to - implementers of IKEv2 and IKEv2.1. - - In the body of this document, notes that are enclosed in double curly - braces {{ such as this }} point out changes from IKEv2. Changes that - come from [Clarif] are marked with the section from that document, - such as "{{ Clarif-2.10 }}". - - This document also make the figures and references a bit more regular - than in IKEv2. - - IKEv2 developers have noted that the SHOULD-level requirements are - often unclear in that they don't say when it is OK to not obey the - requirements. They also have noted that there are MUST-level - requirements that are not related to interoperability. This document - has more explanation of some of these SHOULD-level requirements, and - some SHOULD-level and MUST-level requirements have been changed to - better match the definitions in [MUSTSHOULD]. All non-capitalized - uses of the words SHOULD and MUST now mean their normal English - sense, not the interoperability sense of [MUSTSHOULD]. - - IKEv2 (and IKEv1) developers have noted that there is a great deal of - material in the tables of codes in Section 3.10. This leads to - implementers not having all the needed information in the main body - - - -Hoffman Expires July 5, 2006 [Page 17] - -Internet-Draft IKEv2 January 2006 - - - of the docment. A later version of this document may move much of - the material from those tables into the associated parts of the main - body of the document. - - A later version of this document will probably have all the {{ }} - comments removed from the body of the document and instead appear in - an appendix. - - -2. IKE Protocol Details and Variations - - IKE normally listens and sends on UDP port 500, though IKE messages - may also be received on UDP port 4500 with a slightly different - format (see Section 2.23). Since UDP is a datagram (unreliable) - protocol, IKE includes in its definition recovery from transmission - errors, including packet loss, packet replay, and packet forgery. - IKE is designed to function so long as (1) at least one of a series - of retransmitted packets reaches its destination before timing out; - and (2) the channel is not so full of forged and replayed packets so - as to exhaust the network or CPU capacities of either endpoint. Even - in the absence of those minimum performance requirements, IKE is - designed to fail cleanly (as though the network were broken). - - Although IKEv2 messages are intended to be short, they contain - structures with no hard upper bound on size (in particular, X.509 - certificates), and IKEv2 itself does not have a mechanism for - fragmenting large messages. IP defines a mechanism for fragmentation - of oversize UDP messages, but implementations vary in the maximum - message size supported. Furthermore, use of IP fragmentation opens - an implementation to denial of service attacks [DOSUDPPROT]. - Finally, some NAT and/or firewall implementations may block IP - fragments. - - All IKEv2 implementations MUST be able to send, receive, and process - IKE messages that are up to 1280 bytes long, and they SHOULD be able - to send, receive, and process messages that are up to 3000 bytes - long. {{ Demoted the SHOULD }} IKEv2 implementations need to be aware - of the maximum UDP message size supported and MAY shorten messages by - leaving out some certificates or cryptographic suite proposals if - that will keep messages below the maximum. Use of the "Hash and URL" - formats rather than including certificates in exchanges where - possible can avoid most problems. {{ Demoted the SHOULD }} - Implementations and configuration need to keep in mind, however, that - if the URL lookups are possible only after the IPsec SA is - established, recursion issues could prevent this technique from - working. - - - - - -Hoffman Expires July 5, 2006 [Page 18] - -Internet-Draft IKEv2 January 2006 - - -2.1. Use of Retransmission Timers - - All messages in IKE exist in pairs: a request and a response. The - setup of an IKE_SA normally consists of two request/response pairs. - Once the IKE_SA is set up, either end of the security association may - initiate requests at any time, and there can be many requests and - responses "in flight" at any given moment. But each message is - labeled as either a request or a response, and for each request/ - response pair one end of the security association is the initiator - and the other is the responder. - - For every pair of IKE messages, the initiator is responsible for - retransmission in the event of a timeout. The responder MUST never - retransmit a response unless it receives a retransmission of the - request. In that event, the responder MUST ignore the retransmitted - request except insofar as it triggers a retransmission of the - response. The initiator MUST remember each request until it receives - the corresponding response. The responder MUST remember each - response until it receives a request whose sequence number is larger - than the sequence number in the response plus its window size (see - Section 2.3). - - IKE is a reliable protocol, in the sense that the initiator MUST - retransmit a request until either it receives a corresponding reply - OR it deems the IKE security association to have failed and it - discards all state associated with the IKE_SA and any CHILD_SAs - negotiated using that IKE_SA. - - {{ Clarif-7.5 }} All packets sent on port 4500 MUST begin with the - prefix of four zeros; otherwise, the receiver won't know how to - handle them. - -2.2. Use of Sequence Numbers for Message ID - - Every IKE message contains a Message ID as part of its fixed header. - This Message ID is used to match up requests and responses, and to - identify retransmissions of messages. - - The Message ID is a 32-bit quantity, which is zero for the first IKE - request in each direction. {{ Clarif-3.11 }} When the IKE_AUTH - exchange does not use EAP, the IKE_SA initial setup messages will - always be numbered 0 and 1. When EAP is used, each pair of messages - have their message numbers incremented; the first pair of AUTH - messages will have an ID of 1, the second will be 2, and so on. - - Each endpoint in the IKE Security Association maintains two "current" - Message IDs: the next one to be used for a request it initiates and - the next one it expects to see in a request from the other end. - - - -Hoffman Expires July 5, 2006 [Page 19] - -Internet-Draft IKEv2 January 2006 - - - These counters increment as requests are generated and received. - Responses always contain the same message ID as the corresponding - request. That means that after the initial exchange, each integer n - may appear as the message ID in four distinct messages: the nth - request from the original IKE initiator, the corresponding response, - the nth request from the original IKE responder, and the - corresponding response. If the two ends make very different numbers - of requests, the Message IDs in the two directions can be very - different. There is no ambiguity in the messages, however, because - the (I)nitiator and (R)esponse bits in the message header specify - which of the four messages a particular one is. - - {{ Clarif-2.2 }} The Message ID for IKE_SA_INIT messages is always - zero, including for retries of the message due to responses such as - COOKIE and INVALID_KE_PAYLOAD. - - Note that Message IDs are cryptographically protected and provide - protection against message replays. In the unlikely event that - Message IDs grow too large to fit in 32 bits, the IKE_SA MUST be - closed. Rekeying an IKE_SA resets the sequence numbers. - - {{ Clarif-2.3 }} When a responder receives an IKE_SA_INIT request, it - has to determine whether the packet is a retransmission belonging to - an existing "half-open" IKE_SA (in which case the responder - retransmits the same response), or a new request (in which case the - responder creates a new IKE_SA and sends a fresh response). It is - not sufficient to use the initiator's SPI and/or IP address to - differentiate between the two cases because two different peers - behind a single NAT could choose the same initiator SPI. Instead, a - robust responder will do the IKE_SA lookup using the whole packet, - its hash, or the Ni payload. - -2.3. Window Size for Overlapping Requests - - In order to maximize IKE throughput, an IKE endpoint MAY issue - multiple requests before getting a response to any of them if the - other endpoint has indicated its ability to handle such requests. - For simplicity, an IKE implementation MAY choose to process requests - strictly in order and/or wait for a response to one request before - issuing another. Certain rules must be followed to ensure - interoperability between implementations using different strategies. - - After an IKE_SA is set up, either end can initiate one or more - requests. These requests may pass one another over the network. An - IKE endpoint MUST be prepared to accept and process a request while - it has a request outstanding in order to avoid a deadlock in this - situation. {{ Changed the SHOULD to MUST }} An IKE endpoint MUST be - prepared to accept and process multiple requests while it has a - - - -Hoffman Expires July 5, 2006 [Page 20] - -Internet-Draft IKEv2 January 2006 - - - request outstanding. - - An IKE endpoint MUST wait for a response to each of its messages - before sending a subsequent message unless it has received a - SET_WINDOW_SIZE Notify message from its peer informing it that the - peer is prepared to maintain state for multiple outstanding messages - in order to allow greater throughput. - - An IKE endpoint MUST NOT exceed the peer's stated window size for - transmitted IKE requests. In other words, if the responder stated - its window size is N, then when the initiator needs to make a request - X, it MUST wait until it has received responses to all requests up - through request X-N. An IKE endpoint MUST keep a copy of (or be able - to regenerate exactly) each request it has sent until it receives the - corresponding response. An IKE endpoint MUST keep a copy of (or be - able to regenerate exactly) the number of previous responses equal to - its declared window size in case its response was lost and the - initiator requests its retransmission by retransmitting the request. - - An IKE endpoint supporting a window size greater than one should be - capable of processing incoming requests out of order to maximize - performance in the event of network failures or packet reordering. - - {{ Clarif-7.3 }} The window size is assumed to be a (possibly - configurable) property of a particular implementation, and is not - related to congestion control (unlike the window size in TCP, for - example). In particular, it is not defined what the responder should - do when it receives a SET_WINDOW_SIZE notification containing a - smaller value than is currently in effect. Thus, there is currently - no way to reduce the window size of an existing IKE_SA; you can only - increase it. When rekeying an IKE_SA, the new IKE_SA starts with - window size 1 until it is explicitly increased by sending a new - SET_WINDOW_SIZE notification. - -2.4. State Synchronization and Connection Timeouts - - An IKE endpoint is allowed to forget all of its state associated with - an IKE_SA and the collection of corresponding CHILD_SAs at any time. - This is the anticipated behavior in the event of an endpoint crash - and restart. It is important when an endpoint either fails or - reinitializes its state that the other endpoint detect those - conditions and not continue to waste network bandwidth by sending - packets over discarded SAs and having them fall into a black hole. - - Since IKE is designed to operate in spite of Denial of Service (DoS) - attacks from the network, an endpoint MUST NOT conclude that the - other endpoint has failed based on any routing information (e.g., - ICMP messages) or IKE messages that arrive without cryptographic - - - -Hoffman Expires July 5, 2006 [Page 21] - -Internet-Draft IKEv2 January 2006 - - - protection (e.g., Notify messages complaining about unknown SPIs). - An endpoint MUST conclude that the other endpoint has failed only - when repeated attempts to contact it have gone unanswered for a - timeout period or when a cryptographically protected INITIAL_CONTACT - notification is received on a different IKE_SA to the same - authenticated identity. {{ Demoted the SHOULD }} An endpoint should - suspect that the other endpoint has failed based on routing - information and initiate a request to see whether the other endpoint - is alive. To check whether the other side is alive, IKE specifies an - empty INFORMATIONAL message that (like all IKE requests) requires an - acknowledgement (note that within the context of an IKE_SA, an - "empty" message consists of an IKE header followed by an Encrypted - payload that contains no payloads). If a cryptographically protected - message has been received from the other side recently, unprotected - notifications MAY be ignored. Implementations MUST limit the rate at - which they take actions based on unprotected messages. - - Numbers of retries and lengths of timeouts are not covered in this - specification because they do not affect interoperability. It is - suggested that messages be retransmitted at least a dozen times over - a period of at least several minutes before giving up on an SA, but - different environments may require different rules. To be a good - network citizen, retranmission times MUST increase exponentially to - avoid flooding the network and making an existing congestion - situation worse. If there has only been outgoing traffic on all of - the SAs associated with an IKE_SA, it is essential to confirm - liveness of the other endpoint to avoid black holes. If no - cryptographically protected messages have been received on an IKE_SA - or any of its CHILD_SAs recently, the system needs to perform a - liveness check in order to prevent sending messages to a dead peer. - Receipt of a fresh cryptographically protected message on an IKE_SA - or any of its CHILD_SAs ensures liveness of the IKE_SA and all of its - CHILD_SAs. Note that this places requirements on the failure modes - of an IKE endpoint. An implementation MUST NOT continue sending on - any SA if some failure prevents it from receiving on all of the - associated SAs. If CHILD_SAs can fail independently from one another - without the associated IKE_SA being able to send a delete message, - then they MUST be negotiated by separate IKE_SAs. - - There is a Denial of Service attack on the initiator of an IKE_SA - that can be avoided if the initiator takes the proper care. Since - the first two messages of an SA setup are not cryptographically - protected, an attacker could respond to the initiator's message - before the genuine responder and poison the connection setup attempt. - To prevent this, the initiator MAY be willing to accept multiple - responses to its first message, treat each as potentially legitimate, - respond to it, and then discard all the invalid half-open connections - when it receives a valid cryptographically protected response to any - - - -Hoffman Expires July 5, 2006 [Page 22] - -Internet-Draft IKEv2 January 2006 - - - one of its requests. Once a cryptographically valid response is - received, all subsequent responses should be ignored whether or not - they are cryptographically valid. - - Note that with these rules, there is no reason to negotiate and agree - upon an SA lifetime. If IKE presumes the partner is dead, based on - repeated lack of acknowledgement to an IKE message, then the IKE SA - and all CHILD_SAs set up through that IKE_SA are deleted. - - An IKE endpoint may at any time delete inactive CHILD_SAs to recover - resources used to hold their state. If an IKE endpoint chooses to - delete CHILD_SAs, it MUST send Delete payloads to the other end - notifying it of the deletion. It MAY similarly time out the IKE_SA. - {{ Clarified the SHOULD }} Closing the IKE_SA implicitly closes all - associated CHILD_SAs. In this case, an IKE endpoint SHOULD send a - Delete payload indicating that it has closed the IKE_SA unless the - other endpoint is no longer responding. - -2.5. Version Numbers and Forward Compatibility - - {{ The version number is changed in the following paragraph, and the - discussion of handling of multiple versions is also changed - throughout the section. }} - - This document describes version 2.1 of IKE, meaning the major version - number is 2 and the minor version number is 1. It is likely that - some implementations will want to support version 1.0 and version 2.0 - and version 2.1, and in the future, other versions. - - The major version number should be incremented only if the packet - formats or required actions have changed so dramatically that an - older version node would not be able to interoperate with a newer - version node if it simply ignored the fields it did not understand - and took the actions specified in the older specification. The minor - version number indicates new capabilities, and MUST be ignored by a - node with a smaller minor version number, but used for informational - purposes by the node with the larger minor version number. For - example, it might indicate the ability to process a newly defined - notification message. The node with the larger minor version number - would simply note that its correspondent would not be able to - understand that message and therefore would not send it. - - In the discussion of clarifications to IKEv2, it became clear that - there was a need for additional "MUST" and "SHOULD" requirements. - Some of those changes are reflected in IKEv2.1. Thus, the node with - the higher version number may also need to note that its - correspondent may not be following the same required actions, which - could affect interoperability. - - - -Hoffman Expires July 5, 2006 [Page 23] - -Internet-Draft IKEv2 January 2006 - - - {{ Promoted the SHOULD }} If an endpoint receives a message with a - higher major version number, it MUST drop the message and MUST send - an unauthenticated notification message containing the highest - version number it supports. If an endpoint supports major version n, - and major version m, it MUST support all versions between n and m. - If it receives a message with a major version that it supports, it - MUST respond with that version number. In order to prevent two nodes - from being tricked into corresponding with a lower major version - number than the maximum that they both support, IKE has a flag that - indicates that the node is capable of speaking a higher major version - number. - - Thus, the major version number in the IKE header indicates the - version number of the message, not the highest version number that - the transmitter supports. If the initiator is capable of speaking - versions n, n+1, and n+2, and the responder is capable of speaking - versions n and n+1, then they will negotiate speaking n+1, where the - initiator will set the flag indicating its ability to speak a higher - version. If they mistakenly (perhaps through an active attacker - sending error messages) negotiate to version n, then both will notice - that the other side can support a higher version number, and they - MUST break the connection and reconnect using version n+1. - - Note that IKEv1 does not follow these rules, because there is no way - in v1 of noting that you are capable of speaking a higher version - number. So an active attacker can trick two v2-capable nodes into - speaking v1. {{ Demoted the SHOULD }} When a v2-capable node - negotiates down to v1, it should note that fact in its logs. - - Also for forward compatibility, all fields marked RESERVED MUST be - set to zero by an implementation running version 2.0 or later, and - their content MUST be ignored by an implementation running version - 2.0 or later ("Be conservative in what you send and liberal in what - you receive"). In this way, future versions of the protocol can use - those fields in a way that is guaranteed to be ignored by - implementations that do not understand them. Similarly, payload - types that are not defined are reserved for future use; - implementations of a version where they are undefined MUST skip over - those payloads and ignore their contents. - - IKEv2 adds a "critical" flag to each payload header for further - flexibility for forward compatibility. If the critical flag is set - and the payload type is unrecognized, the message MUST be rejected - and the response to the IKE request containing that payload MUST - include a Notify payload UNSUPPORTED_CRITICAL_PAYLOAD, indicating an - unsupported critical payload was included. If the critical flag is - not set and the payload type is unsupported, that payload MUST be - ignored. - - - -Hoffman Expires July 5, 2006 [Page 24] - -Internet-Draft IKEv2 January 2006 - - - {{ Demoted the SHOULD }}Although new payload types may be added in - the future and may appear interleaved with the fields defined in this - specification, implementations MUST send the payloads defined in this - specification in the order shown in the figures in Section 2 and - implementations MAY reject as invalid a message with those payloads - in any other order. - -2.6. Cookies - - The term "cookies" originates with Karn and Simpson [PHOTURIS] in - Photuris, an early proposal for key management with IPsec, and it has - persisted. The Internet Security Association and Key Management - Protocol (ISAKMP) [ISAKMP] fixed message header includes two eight- - octet fields titled "cookies", and that syntax is used by both IKEv1 - and IKEv2 though in IKEv2 they are referred to as the IKE SPI and - there is a new separate field in a Notify payload holding the cookie. - The initial two eight-octet fields in the header are used as a - connection identifier at the beginning of IKE packets. {{ Promoted - the SHOULD }} Each endpoint chooses one of the two SPIs and MUST - choose them so as to be unique identifiers of an IKE_SA. An SPI - value of zero is special and indicates that the remote SPI value is - not yet known by the sender. - - Unlike ESP and AH where only the recipient's SPI appears in the - header of a message, in IKE the sender's SPI is also sent in every - message. Since the SPI chosen by the original initiator of the - IKE_SA is always sent first, an endpoint with multiple IKE_SAs open - that wants to find the appropriate IKE_SA using the SPI it assigned - must look at the I(nitiator) Flag bit in the header to determine - whether it assigned the first or the second eight octets. - - In the first message of an initial IKE exchange, the initiator will - not know the responder's SPI value and will therefore set that field - to zero. - - An expected attack against IKE is state and CPU exhaustion, where the - target is flooded with session initiation requests from forged IP - addresses. This attack can be made less effective if an - implementation of a responder uses minimal CPU and commits no state - to an SA until it knows the initiator can receive packets at the - address from which it claims to be sending them. To accomplish this, - a responder SHOULD -- when it detects a large number of half-open - IKE_SAs -- reject initial IKE messages unless they contain a Notify - payload of type COOKIE. {{ Clarified the SHOULD }} If the responder - wants to set up an SA, it SHOULD instead send an unprotected IKE - message as a response and include COOKIE Notify payload with the - cookie data to be returned. Initiators who receive such responses - MUST retry the IKE_SA_INIT with a Notify payload of type COOKIE - - - -Hoffman Expires July 5, 2006 [Page 25] - -Internet-Draft IKEv2 January 2006 - - - containing the responder supplied cookie data as the first payload - and all other payloads unchanged. The initial exchange will then be - as follows: - - Initiator Responder - ------------------------------------------------------------------- - HDR(A,0), SAi1, KEi, Ni --> - <-- HDR(A,0), N(COOKIE) - HDR(A,0), N(COOKIE), SAi1, - KEi, Ni --> - <-- HDR(A,B), SAr1, KEr, - Nr, [CERTREQ] - HDR(A,B), SK {IDi, [CERT,] - [CERTREQ,] [IDr,] AUTH, - SAi2, TSi, TSr} --> - <-- HDR(A,B), SK {IDr, [CERT,] - AUTH, SAr2, TSi, TSr} - - The first two messages do not affect any initiator or responder state - except for communicating the cookie. In particular, the message - sequence numbers in the first four messages will all be zero and the - message sequence numbers in the last two messages will be one. 'A' - is the SPI assigned by the initiator, while 'B' is the SPI assigned - by the responder. - - {{ Clarif-2.1 }} Because the responder's SPI identifies security- - related state held by the responder, and in this case no state is - created, the responder sends a zero value for the responder's SPI. - - {{ Demoted the SHOULD }} An IKE implementation should implement its - responder cookie generation in such a way as to not require any saved - state to recognize its valid cookie when the second IKE_SA_INIT - message arrives. The exact algorithms and syntax they use to - generate cookies do not affect interoperability and hence are not - specified here. The following is an example of how an endpoint could - use cookies to implement limited DOS protection. - - A good way to do this is to set the responder cookie to be: - - Cookie = <VersionIDofSecret> | Hash(Ni | IPi | SPIi | <secret>) - - where <secret> is a randomly generated secret known only to the - responder and periodically changed and | indicates concatenation. - <VersionIDofSecret> should be changed whenever <secret> is - regenerated. The cookie can be recomputed when the IKE_SA_INIT - arrives the second time and compared to the cookie in the received - message. If it matches, the responder knows that the cookie was - generated since the last change to <secret> and that IPi must be the - - - -Hoffman Expires July 5, 2006 [Page 26] - -Internet-Draft IKEv2 January 2006 - - - same as the source address it saw the first time. Incorporating SPIi - into the calculation ensures that if multiple IKE_SAs are being set - up in parallel they will all get different cookies (assuming the - initiator chooses unique SPIi's). Incorporating Ni into the hash - ensures that an attacker who sees only message 2 can't successfully - forge a message 3. - - If a new value for <secret> is chosen while there are connections in - the process of being initialized, an IKE_SA_INIT might be returned - with other than the current <VersionIDofSecret>. The responder in - that case MAY reject the message by sending another response with a - new cookie or it MAY keep the old value of <secret> around for a - short time and accept cookies computed from either one. {{ Demoted - the SHOULD NOT }} The responder should not accept cookies - indefinitely after <secret> is changed, since that would defeat part - of the denial of service protection. {{ Demoted the SHOULD }} The - responder should change the value of <secret> frequently, especially - if under attack. - - {{ Clarif-2.1 }} In addition to cookies, there are several cases - where the IKE_SA_INIT exchange does not result in the creation of an - IKE_SA (such as INVALID_KE_PAYLOAD or NO_PROPOSAL_CHOSEN). In such a - case, sending a zero value for the Responder's SPI is correct. If - the responder sends a non-zero responder SPI, the initiator should - not reject the response for only that reason. - - {{ Clarif-2.5 }} When one party receives an IKE_SA_INIT request - containing a cookie whose contents do not match the value expected, - that party MUST ignore the cookie and process the message as if no - cookie had been included; usually this means sending a response - containing a new cookie. - -2.6.1. Interaction of COOKIE and INVALID_KE_PAYLOAD - - {{ This section added by Clarif-2.4 }} - - There are two common reasons why the initiator may have to retry the - IKE_SA_INIT exchange: the responder requests a cookie or wants a - different Diffie-Hellman group than was included in the KEi payload. - If the initiator receives a cookie from the responder, the initiator - needs to decide whether or not tp include the cookie in only the next - retry of the IKE_SA_INIT request, or in all subsequent retries as - well. - - If the initiator includes the cookie only in the next retry, one - additional roundtrip may be needed in some cases. An additional - roundtrip is needed also if the initiator includes the cookie in all - retries, but the responder does not support this. For instance, if - - - -Hoffman Expires July 5, 2006 [Page 27] - -Internet-Draft IKEv2 January 2006 - - - the responder includes the SAi1 and KEi payloads in cookie - calculation, it will reject the request by sending a new cookie. - - If both peers support including the cookie in all retries, a slightly - shorter exchange can happen. Implementations MUST support this - shorter exchange, but MUST NOT assume other implementations also - supports this shorter exchange. - -2.7. Cryptographic Algorithm Negotiation - - The payload type known as "SA" indicates a proposal for a set of - choices of IPsec protocols (IKE, ESP, and/or AH) for the SA as well - as cryptographic algorithms associated with each protocol. - - An SA payload consists of one or more proposals. Each proposal - includes one or more protocols (usually one). Each protocol contains - one or more transforms -- each specifying a cryptographic algorithm. - Each transform contains zero or more attributes (attributes are - needed only if the transform identifier does not completely specify - the cryptographic algorithm). - - This hierarchical structure was designed to efficiently encode - proposals for cryptographic suites when the number of supported - suites is large because multiple values are acceptable for multiple - transforms. The responder MUST choose a single suite, which MAY be - any subset of the SA proposal following the rules below: - - Each proposal contains one or more protocols. If a proposal is - accepted, the SA response MUST contain the same protocols in the same - order as the proposal. The responder MUST accept a single proposal - or reject them all and return an error. (Example: if a single - proposal contains ESP and AH and that proposal is accepted, both ESP - and AH MUST be accepted. If ESP and AH are included in separate - proposals, the responder MUST accept only one of them). - - Each IPsec protocol proposal contains one or more transforms. Each - transform contains a transform type. The accepted cryptographic - suite MUST contain exactly one transform of each type included in the - proposal. For example: if an ESP proposal includes transforms - ENCR_3DES, ENCR_AES w/keysize 128, ENCR_AES w/keysize 256, - AUTH_HMAC_MD5, and AUTH_HMAC_SHA, the accepted suite MUST contain one - of the ENCR_ transforms and one of the AUTH_ transforms. Thus, six - combinations are acceptable. - - Since the initiator sends its Diffie-Hellman value in the - IKE_SA_INIT, it must guess the Diffie-Hellman group that the - responder will select from its list of supported groups. If the - initiator guesses wrong, the responder will respond with a Notify - - - -Hoffman Expires July 5, 2006 [Page 28] - -Internet-Draft IKEv2 January 2006 - - - payload of type INVALID_KE_PAYLOAD indicating the selected group. In - this case, the initiator MUST retry the IKE_SA_INIT with the - corrected Diffie-Hellman group. The initiator MUST again propose its - full set of acceptable cryptographic suites because the rejection - message was unauthenticated and otherwise an active attacker could - trick the endpoints into negotiating a weaker suite than a stronger - one that they both prefer. - -2.8. Rekeying - - {{ Demoted the SHOULD }} IKE, ESP, and AH security associations use - secret keys that should be used only for a limited amount of time and - to protect a limited amount of data. This limits the lifetime of the - entire security association. When the lifetime of a security - association expires, the security association MUST NOT be used. If - there is demand, new security associations MAY be established. - Reestablishment of security associations to take the place of ones - that expire is referred to as "rekeying". - - To allow for minimal IPsec implementations, the ability to rekey SAs - without restarting the entire IKE_SA is optional. An implementation - MAY refuse all CREATE_CHILD_SA requests within an IKE_SA. If an SA - has expired or is about to expire and rekeying attempts using the - mechanisms described here fail, an implementation MUST close the - IKE_SA and any associated CHILD_SAs and then MAY start new ones. {{ - Demoted the SHOULD }} Implementations should support in-place - rekeying of SAs, since doing so offers better performance and is - likely to reduce the number of packets lost during the transition. - - To rekey a CHILD_SA within an existing IKE_SA, create a new, - equivalent SA (see Section 2.17 below), and when the new one is - established, delete the old one. To rekey an IKE_SA, establish a new - equivalent IKE_SA (see Section 2.18 below) with the peer to whom the - old IKE_SA is shared using a CREATE_CHILD_SA within the existing - IKE_SA. An IKE_SA so created inherits all of the original IKE_SA's - CHILD_SAs. Use the new IKE_SA for all control messages needed to - maintain the CHILD_SAs created by the old IKE_SA, and delete the old - IKE_SA. The Delete payload to delete itself MUST be the last request - sent over an IKE_SA. - - {{ Demoted the SHOULD }} SAs should be rekeyed proactively, i.e., the - new SA should be established before the old one expires and becomes - unusable. Enough time should elapse between the time the new SA is - established and the old one becomes unusable so that traffic can be - switched over to the new SA. - - A difference between IKEv1 and IKEv2 is that in IKEv1 SA lifetimes - were negotiated. In IKEv2, each end of the SA is responsible for - - - -Hoffman Expires July 5, 2006 [Page 29] - -Internet-Draft IKEv2 January 2006 - - - enforcing its own lifetime policy on the SA and rekeying the SA when - necessary. If the two ends have different lifetime policies, the end - with the shorter lifetime will end up always being the one to request - the rekeying. If an SA bundle has been inactive for a long time and - if an endpoint would not initiate the SA in the absence of traffic, - the endpoint MAY choose to close the SA instead of rekeying it when - its lifetime expires. {{ Demoted the SHOULD }} It should do so if - there has been no traffic since the last time the SA was rekeyed. - - Note that IKEv2 deliberately allows parallel SAs with the same - traffic selectors between common endpoints. One of the purposes of - this is to support traffic quality of service (QoS) differences among - the SAs (see [DIFFSERVFIELD], [DIFFSERVARCH], and section 4.1 of - [DIFFTUNNEL]). Hence unlike IKEv1, the combination of the endpoints - and the traffic selectors may not uniquely identify an SA between - those endpoints, so the IKEv1 rekeying heuristic of deleting SAs on - the basis of duplicate traffic selectors SHOULD NOT be used. - - {{ Demoted the SHOULD }} The node that initiated the surviving - rekeyed SA should delete the replaced SA after the new one is - established. - - There are timing windows -- particularly in the presence of lost - packets -- where endpoints may not agree on the state of an SA. The - responder to a CREATE_CHILD_SA MUST be prepared to accept messages on - an SA before sending its response to the creation request, so there - is no ambiguity for the initiator. The initiator MAY begin sending - on an SA as soon as it processes the response. The initiator, - however, cannot receive on a newly created SA until it receives and - processes the response to its CREATE_CHILD_SA request. How, then, is - the responder to know when it is OK to send on the newly created SA? - - From a technical correctness and interoperability perspective, the - responder MAY begin sending on an SA as soon as it sends its response - to the CREATE_CHILD_SA request. In some situations, however, this - could result in packets unnecessarily being dropped, so an - implementation MAY want to defer such sending. - - The responder can be assured that the initiator is prepared to - receive messages on an SA if either (1) it has received a - cryptographically valid message on the new SA, or (2) the new SA - rekeys an existing SA and it receives an IKE request to close the - replaced SA. {{ Clarif-5.10 }} When rekeying an SA, the responder - SHOULD continue to send traffic on the old SA until one of those - events occurs. When establishing a new SA, the responder MAY defer - sending messages on a new SA until either it receives one or a - timeout has occurred. {{ Demoted the SHOULD }} If an initiator - receives a message on an SA for which it has not received a response - - - -Hoffman Expires July 5, 2006 [Page 30] - -Internet-Draft IKEv2 January 2006 - - - to its CREATE_CHILD_SA request, it should interpret that as a likely - packet loss and retransmit the CREATE_CHILD_SA request. An initiator - MAY send a dummy message on a newly created SA if it has no messages - queued in order to assure the responder that the initiator is ready - to receive messages. - - {{ Clarif-5.9 }} Throughout this document, "initiator" refers to the - party who initiated the exchange being described, and "original - initiator" refers to the party who initiated the whole IKE_SA. The - "original initiator" always refers to the party who initiated the - exchange which resulted in the current IKE_SA. In other words, if - the the "original responder" starts rekeying the IKE_SA, that party - becomes the "original initiator" of the new IKE_SA. - -2.8.1. Simultaneous CHILD_SA rekeying - - {{ The first two paragraphs were moved, and the rest was added, based - on Clarif-5.12 }} - - If the two ends have the same lifetime policies, it is possible that - both will initiate a rekeying at the same time (which will result in - redundant SAs). To reduce the probability of this happening, the - timing of rekeying requests SHOULD be jittered (delayed by a random - amount of time after the need for rekeying is noticed). - - This form of rekeying may temporarily result in multiple similar SAs - between the same pairs of nodes. When there are two SAs eligible to - receive packets, a node MUST accept incoming packets through either - SA. If redundant SAs are created though such a collision, the SA - created with the lowest of the four nonces used in the two exchanges - SHOULD be closed by the endpoint that created it. {{ Clarif-5.11 }} - "Lowest" means an octet-by-octet, lexicographical comparison (instead - of, for instance, comparing the nonces as large integers). In other - words, start by comparing the first octet; if they're equal, move to - the next octet, and so on. If you reach the end of one nonce, that - nonce is the lower one. - - The following is an explanation on the impact this has on - implementations. Assume that hosts A and B have an existing IPsec SA - pair with SPIs (SPIa1,SPIb1), and both start rekeying it at the same - time: - - Host A Host B - ------------------------------------------------------------------- - send req1: N(REKEY_SA,SPIa1), - SA(..,SPIa2,..),Ni1,.. --> - <-- send req2: N(REKEY_SA,SPIb1), - SA(..,SPIb2,..),Ni2 - - - -Hoffman Expires July 5, 2006 [Page 31] - -Internet-Draft IKEv2 January 2006 - - - recv req2 <-- - - At this point, A knows there is a simultaneous rekeying going on. - However, it cannot yet know which of the exchanges will have the - lowest nonce, so it will just note the situation and respond as - usual. - - send resp2: SA(..,SPIa3,..), - Nr1,.. --> - --> recv req1 - - Now B also knows that simultaneous rekeying is going on. It responds - as usual. - - <-- send resp1: SA(..,SPIb3,..), - Nr2,.. - recv resp1 <-- - --> recv resp2 - - At this point, there are three CHILD_SA pairs between A and B (the - old one and two new ones). A and B can now compare the nonces. - Suppose that the lowest nonce was Nr1 in message resp2; in this case, - B (the sender of req2) deletes the redundant new SA, and A (the node - that initiated the surviving rekeyed SA), deletes the old one. - - send req3: D(SPIa1) --> - <-- send req4: D(SPIb2) - --> recv req3 - <-- send resp4: D(SPIb1) - recv req4 <-- - send resp4: D(SPIa3) --> - - The rekeying is now finished. - - However, there is a second possible sequence of events that can - happen if some packets are lost in the network, resulting in - retransmissions. The rekeying begins as usual, but A's first packet - (req1) is lost. - - - - - - - - - - - - - -Hoffman Expires July 5, 2006 [Page 32] - -Internet-Draft IKEv2 January 2006 - - - Host A Host B - ------------------------------------------------------------------- - send req1: N(REKEY_SA,SPIa1), - SA(..,SPIa2,..), - Ni1,.. --> (lost) - <-- send req2: N(REKEY_SA,SPIb1), - SA(..,SPIb2,..),Ni2 - recv req2 <-- - send resp2: SA(..,SPIa3,..), - Nr1,.. --> - --> recv resp2 - <-- send req3: D(SPIb1) - recv req3 <-- - send resp3: D(SPIa1) --> - --> recv resp3 - - From B's point of view, the rekeying is now completed, and since it - has not yet received A's req1, it does not even know that these was - simultaneous rekeying. However, A will continue retransmitting the - message, and eventually it will reach B. - - resend req1 --> - --> recv req1 - - To B, it looks like A is trying to rekey an SA that no longer exists; - thus, B responds to the request with something non-fatal such as - NO_PROPOSAL_CHOSEN. - - <-- send resp1: N(NO_PROPOSAL_CHOSEN) - recv resp1 <-- - - When A receives this error, it already knows there was simultaneous - rekeying, so it can ignore the error message. - -2.8.2. Rekeying the IKE_SA Versus Reauthentication - - {{ Added this section from Clarif-5.2 }} - - Rekeying the IKE_SA and reauthentication are different concepts in - IKEv2. Rekeying the IKE_SA establishes new keys for the IKE_SA and - resets the Message ID counters, but it does not authenticate the - parties again (no AUTH or EAP payloads are involved). - - Although rekeying the IKE_SA may be important in some environments, - reauthentication (the verification that the parties still have access - to the long-term credentials) is often more important. - - IKEv2 does not have any special support for reauthentication. - - - -Hoffman Expires July 5, 2006 [Page 33] - -Internet-Draft IKEv2 January 2006 - - - Reauthentication is done by creating a new IKE_SA from scratch (using - IKE_SA_INIT/IKE_AUTH exchanges, without any REKEY_SA notify - payloads), creating new CHILD_SAs within the new IKE_SA (without - REKEY_SA notify payloads), and finally deleting the old IKE_SA (which - deletes the old CHILD_SAs as well). - - This means that reauthentication also establishes new keys for the - IKE_SA and CHILD_SAs. Therefore, while rekeying can be performed - more often than reauthentication, the situation where "authentication - lifetime" is shorter than "key lifetime" does not make sense. - - While creation of a new IKE_SA can be initiated by either party - (initiator or responder in the original IKE_SA), the use of EAP - authentication and/or configuration payloads means in practice that - reauthentication has to be initiated by the same party as the - original IKE_SA. IKEv2 does not currently allow the responder to - request reauthentication in this case; however, there is ongoing work - to add this functionality [REAUTH]. - -2.9. Traffic Selector Negotiation - - {{ Clarif-7.2 }} When an RFC4301-compliant IPsec subsystem receives - an IP packet and matches a "protect" selector in its Security Policy - Database (SPD), the subsystem protects that packet with IPsec. When - no SA exists yet, it is the task of IKE to create it. Maintenance of - a system's SPD is outside the scope of IKE (see [PFKEY] for an - example protocol), though some implementations might update their SPD - in connection with the running of IKE (for an example scenario, see - Section 1.1.3). - - Traffic Selector (TS) payloads allow endpoints to communicate some of - the information from their SPD to their peers. TS payloads specify - the selection criteria for packets that will be forwarded over the - newly set up SA. This can serve as a consistency check in some - scenarios to assure that the SPDs are consistent. In others, it - guides the dynamic update of the SPD. - - Two TS payloads appear in each of the messages in the exchange that - creates a CHILD_SA pair. Each TS payload contains one or more - Traffic Selectors. Each Traffic Selector consists of an address - range (IPv4 or IPv6), a port range, and an IP protocol ID. In - support of the scenario described in Section 1.1.3, an initiator may - request that the responder assign an IP address and tell the - initiator what it is. {{ Clarif-6.1 }} That request is done using - configuration payloads, not traffic selectors. An address in a TSi - payload in a response does not mean that the responder has assigned - that address to the initiator: it only means that if packets matching - these traffic selectors are sent by the initiator, IPsec processing - - - -Hoffman Expires July 5, 2006 [Page 34] - -Internet-Draft IKEv2 January 2006 - - - can be performed as agreed for this SA. - - IKEv2 allows the responder to choose a subset of the traffic proposed - by the initiator. This could happen when the configurations of the - two endpoints are being updated but only one end has received the new - information. Since the two endpoints may be configured by different - people, the incompatibility may persist for an extended period even - in the absence of errors. It also allows for intentionally different - configurations, as when one end is configured to tunnel all addresses - and depends on the other end to have the up-to-date list. - - The first of the two TS payloads is known as TSi (Traffic Selector- - initiator). The second is known as TSr (Traffic Selector-responder). - TSi specifies the source address of traffic forwarded from (or the - destination address of traffic forwarded to) the initiator of the - CHILD_SA pair. TSr specifies the destination address of the traffic - forwarded to (or the source address of the traffic forwarded from) - the responder of the CHILD_SA pair. For example, if the original - initiator request the creation of a CHILD_SA pair, and wishes to - tunnel all traffic from subnet 192.0.1.* on the initiator's side to - subnet 192.0.2.* on the responder's side, the initiator would include - a single traffic selector in each TS payload. TSi would specify the - address range (192.0.1.0 - 192.0.1.255) and TSr would specify the - address range (192.0.2.0 - 192.0.2.255). Assuming that proposal was - acceptable to the responder, it would send identical TS payloads - back. (Note: The IP address range 192.0.2.* has been reserved for - use in examples in RFCs and similar documents. This document needed - two such ranges, and so also used 192.0.1.*. This should not be - confused with any actual address.) - - The responder is allowed to narrow the choices by selecting a subset - of the traffic, for instance by eliminating or narrowing the range of - one or more members of the set of traffic selectors, provided the set - does not become the NULL set. - - It is possible for the responder's policy to contain multiple smaller - ranges, all encompassed by the initiator's traffic selector, and with - the responder's policy being that each of those ranges should be sent - over a different SA. Continuing the example above, the responder - might have a policy of being willing to tunnel those addresses to and - from the initiator, but might require that each address pair be on a - separately negotiated CHILD_SA. If the initiator generated its - request in response to an incoming packet from 192.0.1.43 to - 192.0.2.123, there would be no way for the responder to determine - which pair of addresses should be included in this tunnel, and it - would have to make a guess or reject the request with a status of - SINGLE_PAIR_REQUIRED. - - - - -Hoffman Expires July 5, 2006 [Page 35] - -Internet-Draft IKEv2 January 2006 - - - {{ Clarif-4.11 }} Few implementations will have policies that require - separate SAs for each address pair. Because of this, if only some - part (or parts) of the TSi/TSr proposed by the initiator is (are) - acceptable to the responder, responders SHOULD narrow TSi/TSr to an - acceptable subset rather than use SINGLE_PAIR_REQUIRED. - - To enable the responder to choose the appropriate range in this case, - if the initiator has requested the SA due to a data packet, the - initiator SHOULD include as the first traffic selector in each of TSi - and TSr a very specific traffic selector including the addresses in - the packet triggering the request. In the example, the initiator - would include in TSi two traffic selectors: the first containing the - address range (192.0.1.43 - 192.0.1.43) and the source port and IP - protocol from the packet and the second containing (192.0.1.0 - - 192.0.1.255) with all ports and IP protocols. The initiator would - similarly include two traffic selectors in TSr. - - If the responder's policy does not allow it to accept the entire set - of traffic selectors in the initiator's request, but does allow him - to accept the first selector of TSi and TSr, then the responder MUST - narrow the traffic selectors to a subset that includes the - initiator's first choices. In this example, the responder might - respond with TSi being (192.0.1.43 - 192.0.1.43) with all ports and - IP protocols. - - If the initiator creates the CHILD_SA pair not in response to an - arriving packet, but rather, say, upon startup, then there may be no - specific addresses the initiator prefers for the initial tunnel over - any other. In that case, the first values in TSi and TSr MAY be - ranges rather than specific values, and the responder chooses a - subset of the initiator's TSi and TSr that are acceptable. If more - than one subset is acceptable but their union is not, the responder - MUST accept some subset and MAY include a Notify payload of type - ADDITIONAL_TS_POSSIBLE to indicate that the initiator might want to - try again. This case will occur only when the initiator and - responder are configured differently from one another. If the - initiator and responder agree on the granularity of tunnels, the - initiator will never request a tunnel wider than the responder will - accept. {{ Demoted the SHOULD }} Such misconfigurations should be - recorded in error logs. - - {{ Clarif-4.10 }} A concise summary of the narrowing process is: - - o If the responder's policy does not allow any part of the traffic - covered by TSi/TSr, it responds with TS_UNACCEPTABLE. - - o If the responder's policy allows the entire set of traffic covered - by TSi/TSr, no narrowing is necessary, and the responder can - - - -Hoffman Expires July 5, 2006 [Page 36] - -Internet-Draft IKEv2 January 2006 - - - return the same TSi/TSr values. - - o Otherwise, narrowing is needed. If the responder's policy allows - all traffic covered by TSi[1]/TSr[1] (the first traffic selectors - in TSi/TSr) but not entire TSi/TSr, the responder narrows to an - acceptable subset of TSi/TSr that includes TSi[1]/TSr[1]. - - o If the responder's policy does not allow all traffic covered by - TSi[1]/TSr[1], but does allow some parts of TSi/TSr, it narrows to - an acceptable subset of TSi/TSr. - - In the last two cases, there may be several subsets that are - acceptable (but their union is not); in this case, the responder - arbitrarily chooses one of them, and includes ADDITIONAL_TS_POSSIBLE - notification in the response. - -2.9.1. Traffic Selectors Violating Own Policy - - {{ Clarif-4.12 }} - - When creating a new SA, the initiator should not propose traffic - selectors that violate its own policy. If this rule is not followed, - valid traffic may be dropped. - - This is best illustrated by an example. Suppose that host A has a - policy whose effect is that traffic to 192.0.1.66 is sent via host B - encrypted using AES, and traffic to all other hosts in 192.0.1.0/24 - is also sent via B, but must use 3DES. Suppose also that host B - accepts any combination of AES and 3DES. - - If host A now proposes an SA that uses 3DES, and includes TSr - containing (192.0.1.0-192.0.1.0.255), this will be accepted by host - B. Now, host B can also use this SA to send traffic from 192.0.1.66, - but those packets will be dropped by A since it requires the use of - AES for those traffic. Even if host A creates a new SA only for - 192.0.1.66 that uses AES, host B may freely continue to use the first - SA for the traffic. In this situation, when proposing the SA, host A - should have followed its own policy, and included a TSr containing - ((192.0.1.0-192.0.1.65),(192.0.1.67-192.0.1.255)) instead. - - In general, if (1) the initiator makes a proposal "for traffic X - (TSi/TSr), do SA", and (2) for some subset X' of X, the initiator - does not actually accept traffic X' with SA, and (3) the initiator - would be willing to accept traffic X' with some SA' (!=SA), valid - traffic can be unnecessarily dropped since the responder can apply - either SA or SA' to traffic X'. - - - - - -Hoffman Expires July 5, 2006 [Page 37] - -Internet-Draft IKEv2 January 2006 - - -2.10. Nonces - - The IKE_SA_INIT messages each contain a nonce. These nonces are used - as inputs to cryptographic functions. The CREATE_CHILD_SA request - and the CREATE_CHILD_SA response also contain nonces. These nonces - are used to add freshness to the key derivation technique used to - obtain keys for CHILD_SA, and to ensure creation of strong pseudo- - random bits from the Diffie-Hellman key. Nonces used in IKEv2 MUST - be randomly chosen, MUST be at least 128 bits in size, and MUST be at - least half the key size of the negotiated prf. ("prf" refers to - "pseudo-random function", one of the cryptographic algorithms - negotiated in the IKE exchange.) {{ Clarif-7.4 }} However, the - initiator chooses the nonce before the outcome of the negotiation is - known. Because of that, the nonce has to be long enough for all the - PRFs being proposed. If the same random number source is used for - both keys and nonces, care must be taken to ensure that the latter - use does not compromise the former. - -2.11. Address and Port Agility - - IKE runs over UDP ports 500 and 4500, and implicitly sets up ESP and - AH associations for the same IP addresses it runs over. The IP - addresses and ports in the outer header are, however, not themselves - cryptographically protected, and IKE is designed to work even through - Network Address Translation (NAT) boxes. An implementation MUST - accept incoming requests even if the source port is not 500 or 4500, - and MUST respond to the address and port from which the request was - received. It MUST specify the address and port at which the request - was received as the source address and port in the response. IKE - functions identically over IPv4 or IPv6. - -2.12. Reuse of Diffie-Hellman Exponentials - - IKE generates keying material using an ephemeral Diffie-Hellman - exchange in order to gain the property of "perfect forward secrecy". - This means that once a connection is closed and its corresponding - keys are forgotten, even someone who has recorded all of the data - from the connection and gets access to all of the long-term keys of - the two endpoints cannot reconstruct the keys used to protect the - conversation without doing a brute force search of the session key - space. - - Achieving perfect forward secrecy requires that when a connection is - closed, each endpoint MUST forget not only the keys used by the - connection but also any information that could be used to recompute - those keys. In particular, it MUST forget the secrets used in the - Diffie-Hellman calculation and any state that may persist in the - state of a pseudo-random number generator that could be used to - - - -Hoffman Expires July 5, 2006 [Page 38] - -Internet-Draft IKEv2 January 2006 - - - recompute the Diffie-Hellman secrets. - - Since the computing of Diffie-Hellman exponentials is computationally - expensive, an endpoint may find it advantageous to reuse those - exponentials for multiple connection setups. There are several - reasonable strategies for doing this. An endpoint could choose a new - exponential only periodically though this could result in less-than- - perfect forward secrecy if some connection lasts for less than the - lifetime of the exponential. Or it could keep track of which - exponential was used for each connection and delete the information - associated with the exponential only when some corresponding - connection was closed. This would allow the exponential to be reused - without losing perfect forward secrecy at the cost of maintaining - more state. - - Decisions as to whether and when to reuse Diffie-Hellman exponentials - is a private decision in the sense that it will not affect - interoperability. An implementation that reuses exponentials MAY - choose to remember the exponential used by the other endpoint on past - exchanges and if one is reused to avoid the second half of the - calculation. - -2.13. Generating Keying Material - - In the context of the IKE_SA, four cryptographic algorithms are - negotiated: an encryption algorithm, an integrity protection - algorithm, a Diffie-Hellman group, and a pseudo-random function - (prf). The pseudo-random function is used for the construction of - keying material for all of the cryptographic algorithms used in both - the IKE_SA and the CHILD_SAs. - - We assume that each encryption algorithm and integrity protection - algorithm uses a fixed-size key and that any randomly chosen value of - that fixed size can serve as an appropriate key. For algorithms that - accept a variable length key, a fixed key size MUST be specified as - part of the cryptographic transform negotiated. For algorithms for - which not all values are valid keys (such as DES or 3DES with key - parity), the algorithm by which keys are derived from arbitrary - values MUST be specified by the cryptographic transform. For - integrity protection functions based on Hashed Message Authentication - Code (HMAC), the fixed key size is the size of the output of the - underlying hash function. When the prf function takes a variable - length key, variable length data, and produces a fixed-length output - (e.g., when using HMAC), the formulas in this document apply. When - the key for the prf function has fixed length, the data provided as a - key is truncated or padded with zeros as necessary unless exceptional - processing is explained following the formula. - - - - -Hoffman Expires July 5, 2006 [Page 39] - -Internet-Draft IKEv2 January 2006 - - - Keying material will always be derived as the output of the - negotiated prf algorithm. Since the amount of keying material needed - may be greater than the size of the output of the prf algorithm, we - will use the prf iteratively. We will use the terminology prf+ to - describe the function that outputs a pseudo-random stream based on - the inputs to a prf as follows: (where | indicates concatenation) - - prf+ (K,S) = T1 | T2 | T3 | T4 | ... - - where: - T1 = prf (K, S | 0x01) - T2 = prf (K, T1 | S | 0x02) - T3 = prf (K, T2 | S | 0x03) - T4 = prf (K, T3 | S | 0x04) - - continuing as needed to compute all required keys. The keys are - taken from the output string without regard to boundaries (e.g., if - the required keys are a 256-bit Advanced Encryption Standard (AES) - key and a 160-bit HMAC key, and the prf function generates 160 bits, - the AES key will come from T1 and the beginning of T2, while the HMAC - key will come from the rest of T2 and the beginning of T3). - - The constant concatenated to the end of each string feeding the prf - is a single octet. prf+ in this document is not defined beyond 255 - times the size of the prf output. - -2.14. Generating Keying Material for the IKE_SA - - The shared keys are computed as follows. A quantity called SKEYSEED - is calculated from the nonces exchanged during the IKE_SA_INIT - exchange and the Diffie-Hellman shared secret established during that - exchange. SKEYSEED is used to calculate seven other secrets: SK_d - used for deriving new keys for the CHILD_SAs established with this - IKE_SA; SK_ai and SK_ar used as a key to the integrity protection - algorithm for authenticating the component messages of subsequent - exchanges; SK_ei and SK_er used for encrypting (and of course - decrypting) all subsequent exchanges; and SK_pi and SK_pr, which are - used when generating an AUTH payload. - - SKEYSEED and its derivatives are computed as follows: - - SKEYSEED = prf(Ni | Nr, g^ir) - - {SK_d | SK_ai | SK_ar | SK_ei | SK_er | SK_pi | SK_pr } - = prf+ (SKEYSEED, Ni | Nr | SPIi | SPIr ) - - (indicating that the quantities SK_d, SK_ai, SK_ar, SK_ei, SK_er, - SK_pi, and SK_pr are taken in order from the generated bits of the - - - -Hoffman Expires July 5, 2006 [Page 40] - -Internet-Draft IKEv2 January 2006 - - - prf+). g^ir is the shared secret from the ephemeral Diffie-Hellman - exchange. g^ir is represented as a string of octets in big endian - order padded with zeros if necessary to make it the length of the - modulus. Ni and Nr are the nonces, stripped of any headers. If the - negotiated prf takes a fixed-length key and the lengths of Ni and Nr - do not add up to that length, half the bits must come from Ni and - half from Nr, taking the first bits of each. - - The two directions of traffic flow use different keys. The keys used - to protect messages from the original initiator are SK_ai and SK_ei. - The keys used to protect messages in the other direction are SK_ar - and SK_er. Each algorithm takes a fixed number of bits of keying - material, which is specified as part of the algorithm. For integrity - algorithms based on a keyed hash, the key size is always equal to the - length of the output of the underlying hash function. - -2.15. Authentication of the IKE_SA - - When not using extensible authentication (see Section 2.16), the - peers are authenticated by having each sign (or MAC using a shared - secret as the key) a block of data. For the responder, the octets to - be signed start with the first octet of the first SPI in the header - of the second message and end with the last octet of the last payload - in the second message. Appended to this (for purposes of computing - the signature) are the initiator's nonce Ni (just the value, not the - payload containing it), and the value prf(SK_pr,IDr') where IDr' is - the responder's ID payload excluding the fixed header. Note that - neither the nonce Ni nor the value prf(SK_pr,IDr') are transmitted. - Similarly, the initiator signs the first message, starting with the - first octet of the first SPI in the header and ending with the last - octet of the last payload. Appended to this (for purposes of - computing the signature) are the responder's nonce Nr, and the value - prf(SK_pi,IDi'). In the above calculation, IDi' and IDr' are the - entire ID payloads excluding the fixed header. It is critical to the - security of the exchange that each side sign the other side's nonce. - - {{ Clarif-3.1 }} - - The initiator's signed octets can be described as: - - InitiatorSignedOctets = RealMessage1 | NonceRData | MACedIDForI - GenIKEHDR = [ four octets 0 if using port 4500 ] | RealIKEHDR - RealIKEHDR = SPIi | SPIr | . . . | Length - RealMessage1 = RealIKEHDR | RestOfMessage1 - NonceRPayload = PayloadHeader | NonceRData - InitiatorIDPayload = PayloadHeader | RestOfIDPayload - RestOfInitIDPayload = IDType | RESERVED | InitIDData - MACedIDForI = prf(SK_pi, RestOfInitIDPayload) - - - -Hoffman Expires July 5, 2006 [Page 41] - -Internet-Draft IKEv2 January 2006 - - - The responder's signed octets can be described as: - - ResponderSignedOctets = RealMessage2 | NonceIData | MACedIDForR - GenIKEHDR = [ four octets 0 if using port 4500 ] | RealIKEHDR - RealIKEHDR = SPIi | SPIr | . . . | Length - RealMessage2 = RealIKEHDR | RestOfMessage2 - NonceIPayload = PayloadHeader | NonceIData - ResponderIDPayload = PayloadHeader | RestOfIDPayload - RestOfRespIDPayload = IDType | RESERVED | InitIDData - MACedIDForR = prf(SK_pr, RestOfRespIDPayload) - - Note that all of the payloads are included under the signature, - including any payload types not defined in this document. If the - first message of the exchange is sent twice (the second time with a - responder cookie and/or a different Diffie-Hellman group), it is the - second version of the message that is signed. - - Optionally, messages 3 and 4 MAY include a certificate, or - certificate chain providing evidence that the key used to compute a - digital signature belongs to the name in the ID payload. The - signature or MAC will be computed using algorithms dictated by the - type of key used by the signer, and specified by the Auth Method - field in the Authentication payload. There is no requirement that - the initiator and responder sign with the same cryptographic - algorithms. The choice of cryptographic algorithms depends on the - type of key each has. In particular, the initiator may be using a - shared key while the responder may have a public signature key and - certificate. It will commonly be the case (but it is not required) - that if a shared secret is used for authentication that the same key - is used in both directions. Note that it is a common but typically - insecure practice to have a shared key derived solely from a user- - chosen password without incorporating another source of randomness. - - This is typically insecure because user-chosen passwords are unlikely - to have sufficient unpredictability to resist dictionary attacks and - these attacks are not prevented in this authentication method. - (Applications using password-based authentication for bootstrapping - and IKE_SA should use the authentication method in Section 2.16, - which is designed to prevent off-line dictionary attacks.) {{ Demoted - the SHOULD }} The pre-shared key needs to contain as much - unpredictability as the strongest key being negotiated. In the case - of a pre-shared key, the AUTH value is computed as: - - AUTH = prf(prf(Shared Secret,"Key Pad for IKEv2"), <msg octets>) - - where the string "Key Pad for IKEv2" is 17 ASCII characters without - null termination. The shared secret can be variable length. The pad - string is added so that if the shared secret is derived from a - - - -Hoffman Expires July 5, 2006 [Page 42] - -Internet-Draft IKEv2 January 2006 - - - password, the IKE implementation need not store the password in - cleartext, but rather can store the value prf(Shared Secret,"Key Pad - for IKEv2"), which could not be used as a password equivalent for - protocols other than IKEv2. As noted above, deriving the shared - secret from a password is not secure. This construction is used - because it is anticipated that people will do it anyway. The - management interface by which the Shared Secret is provided MUST - accept ASCII strings of at least 64 octets and MUST NOT add a null - terminator before using them as shared secrets. It MUST also accept - a HEX encoding of the Shared Secret. The management interface MAY - accept other encodings if the algorithm for translating the encoding - to a binary string is specified. - - {{ Clarif-3.8 }} If the negotiated prf takes a fixed-size key, the - shared secret MUST be of that fixed size. This requirement means - that it is difficult to use these PRFs with shared key authentication - because it limits the shared secrets that can be used. Thus, PRFs - that require a fixed-size key SHOULD NOT be used with shared key - authentication. For example, PRF_AES128_CBC [PRFAES128CBC] - originally used fixed key sizes; that RFC has been updated to handle - variable key sizes in [PRFAES128CBC-bis]. Note that Section 2.13 - also contains text that is related to PRFs with fixed key size. - However, the text in that section applies only to the prf+ - construction. - -2.16. Extensible Authentication Protocol Methods - - In addition to authentication using public key signatures and shared - secrets, IKE supports authentication using methods defined in RFC - 3748 [EAP]. Typically, these methods are asymmetric (designed for a - user authenticating to a server), and they may not be mutual. For - this reason, these protocols are typically used to authenticate the - initiator to the responder and MUST be used in conjunction with a - public key signature based authentication of the responder to the - initiator. These methods are often associated with mechanisms - referred to as "Legacy Authentication" mechanisms. - - While this memo references [EAP] with the intent that new methods can - be added in the future without updating this specification, some - simpler variations are documented here and in Section 3.16. [EAP] - defines an authentication protocol requiring a variable number of - messages. Extensible Authentication is implemented in IKE as - additional IKE_AUTH exchanges that MUST be completed in order to - initialize the IKE_SA. - - An initiator indicates a desire to use extensible authentication by - leaving out the AUTH payload from message 3. By including an IDi - payload but not an AUTH payload, the initiator has declared an - - - -Hoffman Expires July 5, 2006 [Page 43] - -Internet-Draft IKEv2 January 2006 - - - identity but has not proven it. If the responder is willing to use - an extensible authentication method, it will place an Extensible - Authentication Protocol (EAP) payload in message 4 and defer sending - SAr2, TSi, and TSr until initiator authentication is complete in a - subsequent IKE_AUTH exchange. In the case of a minimal extensible - authentication, the initial SA establishment will appear as follows: - - Initiator Responder - ------------------------------------------------------------------- - HDR, SAi1, KEi, Ni --> - <-- HDR, SAr1, KEr, Nr, [CERTREQ] - HDR, SK {IDi, [CERTREQ,] - [IDr,] SAi2, - TSi, TSr} --> - <-- HDR, SK {IDr, [CERT,] AUTH, - EAP } - HDR, SK {EAP} --> - <-- HDR, SK {EAP (success)} - HDR, SK {AUTH} --> - <-- HDR, SK {AUTH, SAr2, TSi, TSr } - - {{ Clarif-3.11 }} As described in Section 2.2, when EAP is used, each - pair of IKE_SA initial setup messages will have their message numbers - incremented; the first pair of AUTH messages will have an ID of 1, - the second will be 2, and so on. - - For EAP methods that create a shared key as a side effect of - authentication, that shared key MUST be used by both the initiator - and responder to generate AUTH payloads in messages 7 and 8 using the - syntax for shared secrets specified in Section 2.15. The shared key - from EAP is the field from the EAP specification named MSK. The - shared key generated during an IKE exchange MUST NOT be used for any - other purpose. - - EAP methods that do not establish a shared key SHOULD NOT be used, as - they are subject to a number of man-in-the-middle attacks [EAPMITM] - if these EAP methods are used in other protocols that do not use a - server-authenticated tunnel. Please see the Security Considerations - section for more details. If EAP methods that do not generate a - shared key are used, the AUTH payloads in messages 7 and 8 MUST be - generated using SK_pi and SK_pr, respectively. - - {{ Demoted the SHOULD }} The initiator of an IKE_SA using EAP needs - to be capable of extending the initial protocol exchange to at least - ten IKE_AUTH exchanges in the event the responder sends notification - messages and/or retries the authentication prompt. Once the protocol - exchange defined by the chosen EAP authentication method has - successfully terminated, the responder MUST send an EAP payload - - - -Hoffman Expires July 5, 2006 [Page 44] - -Internet-Draft IKEv2 January 2006 - - - containing the Success message. Similarly, if the authentication - method has failed, the responder MUST send an EAP payload containing - the Failure message. The responder MAY at any time terminate the IKE - exchange by sending an EAP payload containing the Failure message. - - Following such an extended exchange, the EAP AUTH payloads MUST be - included in the two messages following the one containing the EAP - Success message. - - {{ Clarif-3.5 }} When the initiator authentication uses EAP, it is - possible that the contents of the IDi payload is used only for AAA - routing purposes and selecting which EAP method to use. This value - may be different from the identity authenticated by the EAP method. - It is important that policy lookups and access control decisions use - the actual authenticated identity. Often the EAP server is - implemented in a separate AAA server that communicates with the IKEv2 - responder. In this case, the authenticated identity has to be sent - from the AAA server to the IKEv2 responder. - - {{ Clarif-3.9 }} The information in Section 2.17 about PRFs with - fixed-size keys also applies to EAP authentication. For instance, a - PRF that requires a 128-bit key cannot be used with EAP because - specifies that the MSK is at least 512 bits long. - -2.17. Generating Keying Material for CHILD_SAs - - A single CHILD_SA is created by the IKE_AUTH exchange, and additional - CHILD_SAs can optionally be created in CREATE_CHILD_SA exchanges. - Keying material for them is generated as follows: - - KEYMAT = prf+(SK_d, Ni | Nr) - - Where Ni and Nr are the nonces from the IKE_SA_INIT exchange if this - request is the first CHILD_SA created or the fresh Ni and Nr from the - CREATE_CHILD_SA exchange if this is a subsequent creation. - - For CREATE_CHILD_SA exchanges including an optional Diffie-Hellman - exchange, the keying material is defined as: - - KEYMAT = prf+(SK_d, g^ir (new) | Ni | Nr ) - - where g^ir (new) is the shared secret from the ephemeral Diffie- - Hellman exchange of this CREATE_CHILD_SA exchange (represented as an - octet string in big endian order padded with zeros in the high-order - bits if necessary to make it the length of the modulus). - - A single CHILD_SA negotiation may result in multiple security - associations. ESP and AH SAs exist in pairs (one in each direction), - - - -Hoffman Expires July 5, 2006 [Page 45] - -Internet-Draft IKEv2 January 2006 - - - and four SAs could be created in a single CHILD_SA negotiation if a - combination of ESP and AH is being negotiated. - - Keying material MUST be taken from the expanded KEYMAT in the - following order: - - o All keys for SAs carrying data from the initiator to the responder - are taken before SAs going in the reverse direction. - - o If multiple IPsec protocols are negotiated, keying material is - taken in the order in which the protocol headers will appear in - the encapsulated packet. - - o If a single protocol has both encryption and authentication keys, - the encryption key is taken from the first octets of KEYMAT and - the authentication key is taken from the next octets. - - Each cryptographic algorithm takes a fixed number of bits of keying - material specified as part of the algorithm. - -2.18. Rekeying IKE_SAs Using a CREATE_CHILD_SA Exchange - - The CREATE_CHILD_SA exchange can be used to rekey an existing IKE_SA - (see Section 2.8). {{ Clarif-5.3 }} New initiator and responder SPIs - are supplied in the SPI fields in the Proposal structures inside the - Security Association (SA) payloads (not the SPI fields in the IKE - header). The TS payloads are omitted when rekeying an IKE_SA. - SKEYSEED for the new IKE_SA is computed using SK_d from the existing - IKE_SA as follows: - - SKEYSEED = prf(SK_d (old), [g^ir (new)] | Ni | Nr) - - where g^ir (new) is the shared secret from the ephemeral Diffie- - Hellman exchange of this CREATE_CHILD_SA exchange (represented as an - octet string in big endian order padded with zeros if necessary to - make it the length of the modulus) and Ni and Nr are the two nonces - stripped of any headers. - - {{ Clarif-5.5 }} The old and new IKE_SA may have selected a different - PRF. Because the rekeying exchange belongs to the old IKE_SA, it is - the old IKE_SA's PRF that is used. Note that this may not work if - the new IKE_SA's PRF has a fixed key size because the output of the - PRF may not be of the correct size. - - The new IKE_SA MUST reset its message counters to 0. - - SK_d, SK_ai, SK_ar, SK_ei, and SK_er are computed from SKEYSEED as - specified in Section 2.14. - - - -Hoffman Expires July 5, 2006 [Page 46] - -Internet-Draft IKEv2 January 2006 - - -2.19. Requesting an Internal Address on a Remote Network - - Most commonly occurring in the endpoint-to-security-gateway scenario, - an endpoint may need an IP address in the network protected by the - security gateway and may need to have that address dynamically - assigned. A request for such a temporary address can be included in - any request to create a CHILD_SA (including the implicit request in - message 3) by including a CP payload. - - This function provides address allocation to an IPsec Remote Access - Client (IRAC) trying to tunnel into a network protected by an IPsec - Remote Access Server (IRAS). Since the IKE_AUTH exchange creates an - IKE_SA and a CHILD_SA, the IRAC MUST request the IRAS-controlled - address (and optionally other information concerning the protected - network) in the IKE_AUTH exchange. The IRAS may procure an address - for the IRAC from any number of sources such as a DHCP/BOOTP server - or its own address pool. - - Initiator Responder - ------------------------------------------------------------------- - HDR, SK {IDi, [CERT,] - [CERTREQ,] [IDr,] AUTH, - CP(CFG_REQUEST), SAi2, - TSi, TSr} --> - <-- HDR, SK {IDr, [CERT,] AUTH, - CP(CFG_REPLY), SAr2, - TSi, TSr} - - In all cases, the CP payload MUST be inserted before the SA payload. - In variations of the protocol where there are multiple IKE_AUTH - exchanges, the CP payloads MUST be inserted in the messages - containing the SA payloads. - - CP(CFG_REQUEST) MUST contain at least an INTERNAL_ADDRESS attribute - (either IPv4 or IPv6) but MAY contain any number of additional - attributes the initiator wants returned in the response. - - For example, message from initiator to responder: - - {{ Clarif-6.3 }} - - CP(CFG_REQUEST)= - INTERNAL_ADDRESS() - TSi = (0, 0-65535,0.0.0.0-255.255.255.255) - TSr = (0, 0-65535,0.0.0.0-255.255.255.255) - - NOTE: Traffic Selectors contain (protocol, port range, address - range). - - - -Hoffman Expires July 5, 2006 [Page 47] - -Internet-Draft IKEv2 January 2006 - - - Message from responder to initiator: - - CP(CFG_REPLY)= - INTERNAL_ADDRESS(192.0.2.202) - INTERNAL_NETMASK(255.255.255.0) - INTERNAL_SUBNET(192.0.2.0/255.255.255.0) - TSi = (0, 0-65535,192.0.2.202-192.0.2.202) - TSr = (0, 0-65535,192.0.2.0-192.0.2.255) - - All returned values will be implementation dependent. As can be seen - in the above example, the IRAS MAY also send other attributes that - were not included in CP(CFG_REQUEST) and MAY ignore the non- - mandatory attributes that it does not support. - - The responder MUST NOT send a CFG_REPLY without having first received - a CP(CFG_REQUEST) from the initiator, because we do not want the IRAS - to perform an unnecessary configuration lookup if the IRAC cannot - process the REPLY. In the case where the IRAS's configuration - requires that CP be used for a given identity IDi, but IRAC has - failed to send a CP(CFG_REQUEST), IRAS MUST fail the request, and - terminate the IKE exchange with a FAILED_CP_REQUIRED error. - -2.20. Requesting the Peer's Version - - An IKE peer wishing to inquire about the other peer's IKE software - version information MAY use the method below. This is an example of - a configuration request within an INFORMATIONAL exchange, after the - IKE_SA and first CHILD_SA have been created. - - An IKE implementation MAY decline to give out version information - prior to authentication or even after authentication to prevent - trolling in case some implementation is known to have some security - weakness. In that case, it MUST either return an empty string or no - CP payload if CP is not supported. - - Initiator Responder - ------------------------------------------------------------------- - HDR, SK{CP(CFG_REQUEST)} --> - <-- HDR, SK{CP(CFG_REPLY)} - - CP(CFG_REQUEST)= - APPLICATION_VERSION("") - - CP(CFG_REPLY) APPLICATION_VERSION("foobar v1.3beta, (c) Foo Bar - Inc.") - - - - - - -Hoffman Expires July 5, 2006 [Page 48] - -Internet-Draft IKEv2 January 2006 - - -2.21. Error Handling - - There are many kinds of errors that can occur during IKE processing. - If a request is received that is badly formatted or unacceptable for - reasons of policy (e.g., no matching cryptographic algorithms), the - response MUST contain a Notify payload indicating the error. If an - error occurs outside the context of an IKE request (e.g., the node is - getting ESP messages on a nonexistent SPI), the node SHOULD initiate - an INFORMATIONAL exchange with a Notify payload describing the - problem. - - Errors that occur before a cryptographically protected IKE_SA is - established must be handled very carefully. There is a trade-off - between wanting to be helpful in diagnosing a problem and responding - to it and wanting to avoid being a dupe in a denial of service attack - based on forged messages. - - If a node receives a message on UDP port 500 or 4500 outside the - context of an IKE_SA known to it (and not a request to start one), it - may be the result of a recent crash of the node. If the message is - marked as a response, the node MAY audit the suspicious event but - MUST NOT respond. If the message is marked as a request, the node - MAY audit the suspicious event and MAY send a response. If a - response is sent, the response MUST be sent to the IP address and - port from whence it came with the same IKE SPIs and the Message ID - copied. The response MUST NOT be cryptographically protected and - MUST contain a Notify payload indicating INVALID_IKE_SPI. - - A node receiving such an unprotected Notify payload MUST NOT respond - and MUST NOT change the state of any existing SAs. The message might - be a forgery or might be a response the genuine correspondent was - tricked into sending. {{ Demoted two SHOULDs }} A node should treat - such a message (and also a network message like ICMP destination - unreachable) as a hint that there might be problems with SAs to that - IP address and should initiate a liveness test for any such IKE_SA. - An implementation SHOULD limit the frequency of such tests to avoid - being tricked into participating in a denial of service attack. - - A node receiving a suspicious message from an IP address with which - it has an IKE_SA MAY send an IKE Notify payload in an IKE - INFORMATIONAL exchange over that SA. {{ Demoted the SHOULD }} The - recipient MUST NOT change the state of any SAs as a result but may - wish to audit the event to aid in diagnosing malfunctions. A node - MUST limit the rate at which it will send messages in response to - unprotected messages. - - - - - - -Hoffman Expires July 5, 2006 [Page 49] - -Internet-Draft IKEv2 January 2006 - - -2.22. IPComp - - Use of IP compression [IPCOMP] can be negotiated as part of the setup - of a CHILD_SA. While IP compression involves an extra header in each - packet and a compression parameter index (CPI), the virtual - "compression association" has no life outside the ESP or AH SA that - contains it. Compression associations disappear when the - corresponding ESP or AH SA goes away. It is not explicitly mentioned - in any DELETE payload. - - Negotiation of IP compression is separate from the negotiation of - cryptographic parameters associated with a CHILD_SA. A node - requesting a CHILD_SA MAY advertise its support for one or more - compression algorithms through one or more Notify payloads of type - IPCOMP_SUPPORTED. The response MAY indicate acceptance of a single - compression algorithm with a Notify payload of type IPCOMP_SUPPORTED. - These payloads MUST NOT occur in messages that do not contain SA - payloads. - - Although there has been discussion of allowing multiple compression - algorithms to be accepted and to have different compression - algorithms available for the two directions of a CHILD_SA, - implementations of this specification MUST NOT accept an IPComp - algorithm that was not proposed, MUST NOT accept more than one, and - MUST NOT compress using an algorithm other than one proposed and - accepted in the setup of the CHILD_SA. - - A side effect of separating the negotiation of IPComp from - cryptographic parameters is that it is not possible to propose - multiple cryptographic suites and propose IP compression with some of - them but not others. - -2.23. NAT Traversal - - Network Address Translation (NAT) gateways are a controversial - subject. This section briefly describes what they are and how they - are likely to act on IKE traffic. Many people believe that NATs are - evil and that we should not design our protocols so as to make them - work better. IKEv2 does specify some unintuitive processing rules in - order that NATs are more likely to work. - - NATs exist primarily because of the shortage of IPv4 addresses, - though there are other rationales. IP nodes that are "behind" a NAT - have IP addresses that are not globally unique, but rather are - assigned from some space that is unique within the network behind the - NAT but that are likely to be reused by nodes behind other NATs. - Generally, nodes behind NATs can communicate with other nodes behind - the same NAT and with nodes with globally unique addresses, but not - - - -Hoffman Expires July 5, 2006 [Page 50] - -Internet-Draft IKEv2 January 2006 - - - with nodes behind other NATs. There are exceptions to that rule. - When those nodes make connections to nodes on the real Internet, the - NAT gateway "translates" the IP source address to an address that - will be routed back to the gateway. Messages to the gateway from the - Internet have their destination addresses "translated" to the - internal address that will route the packet to the correct endnode. - - NATs are designed to be "transparent" to endnodes. Neither software - on the node behind the NAT nor the node on the Internet requires - modification to communicate through the NAT. Achieving this - transparency is more difficult with some protocols than with others. - Protocols that include IP addresses of the endpoints within the - payloads of the packet will fail unless the NAT gateway understands - the protocol and modifies the internal references as well as those in - the headers. Such knowledge is inherently unreliable, is a network - layer violation, and often results in subtle problems. - - Opening an IPsec connection through a NAT introduces special - problems. If the connection runs in transport mode, changing the IP - addresses on packets will cause the checksums to fail and the NAT - cannot correct the checksums because they are cryptographically - protected. Even in tunnel mode, there are routing problems because - transparently translating the addresses of AH and ESP packets - requires special logic in the NAT and that logic is heuristic and - unreliable in nature. For that reason, IKEv2 can negotiate UDP - encapsulation of IKE and ESP packets. This encoding is slightly less - efficient but is easier for NATs to process. In addition, firewalls - may be configured to pass IPsec traffic over UDP but not ESP/AH or - vice versa. - - It is a common practice of NATs to translate TCP and UDP port numbers - as well as addresses and use the port numbers of inbound packets to - decide which internal node should get a given packet. For this - reason, even though IKE packets MUST be sent from and to UDP port - 500, they MUST be accepted coming from any port and responses MUST be - sent to the port from whence they came. This is because the ports - may be modified as the packets pass through NATs. Similarly, IP - addresses of the IKE endpoints are generally not included in the IKE - payloads because the payloads are cryptographically protected and - could not be transparently modified by NATs. - - Port 4500 is reserved for UDP-encapsulated ESP and IKE. When working - through a NAT, it is generally better to pass IKE packets over port - 4500 because some older NATs handle IKE traffic on port 500 cleverly - in an attempt to transparently establish IPsec connections between - endpoints that don't handle NAT traversal themselves. Such NATs may - interfere with the straightforward NAT traversal envisioned by this - document. {{ Clarif-7.6 }} An IPsec endpoint that discovers a NAT - - - -Hoffman Expires July 5, 2006 [Page 51] - -Internet-Draft IKEv2 January 2006 - - - between it and its correspondent MUST send all subsequent traffic - from port 4500, which NATs should not treat specially (as they might - with port 500). - - The specific requirements for supporting NAT traversal [NATREQ] are - listed below. Support for NAT traversal is optional. In this - section only, requirements listed as MUST apply only to - implementations supporting NAT traversal. - - o IKE MUST listen on port 4500 as well as port 500. IKE MUST - respond to the IP address and port from which packets arrived. - - o Both IKE initiator and responder MUST include in their IKE_SA_INIT - packets Notify payloads of type NAT_DETECTION_SOURCE_IP and - NAT_DETECTION_DESTINATION_IP. Those payloads can be used to - detect if there is NAT between the hosts, and which end is behind - the NAT. The location of the payloads in the IKE_SA_INIT packets - are just after the Ni and Nr payloads (before the optional CERTREQ - payload). - - o If none of the NAT_DETECTION_SOURCE_IP payload(s) received matches - the hash of the source IP and port found from the IP header of the - packet containing the payload, it means that the other end is - behind NAT (i.e., someone along the route changed the source - address of the original packet to match the address of the NAT - box). In this case, this end should allow dynamic update of the - other ends IP address, as described later. - - o If the NAT_DETECTION_DESTINATION_IP payload received does not - match the hash of the destination IP and port found from the IP - header of the packet containing the payload, it means that this - end is behind a NAT. In this case, this end SHOULD start sending - keepalive packets as explained in [UDPENCAPS]. - - o The IKE initiator MUST check these payloads if present and if they - do not match the addresses in the outer packet MUST tunnel all - future IKE and ESP packets associated with this IKE_SA over UDP - port 4500. - - o To tunnel IKE packets over UDP port 4500, the IKE header has four - octets of zero prepended and the result immediately follows the - UDP header. To tunnel ESP packets over UDP port 4500, the ESP - header immediately follows the UDP header. Since the first four - bytes of the ESP header contain the SPI, and the SPI cannot - validly be zero, it is always possible to distinguish ESP and IKE - messages. - - - - - -Hoffman Expires July 5, 2006 [Page 52] - -Internet-Draft IKEv2 January 2006 - - - o The original source and destination IP address required for the - transport mode TCP and UDP packet checksum fixup (see [UDPENCAPS]) - are obtained from the Traffic Selectors associated with the - exchange. In the case of NAT traversal, the Traffic Selectors - MUST contain exactly one IP address, which is then used as the - original IP address. - - o There are cases where a NAT box decides to remove mappings that - are still alive (for example, the keepalive interval is too long, - or the NAT box is rebooted). To recover in these cases, hosts - that are not behind a NAT SHOULD send all packets (including - retransmission packets) to the IP address and port from the last - valid authenticated packet from the other end (i.e., dynamically - update the address). {{ Promoted the SHOULD }} A host behind a NAT - MUST NOT do this because it opens a DoS attack possibility. Any - authenticated IKE packet or any authenticated UDP-encapsulated ESP - packet can be used to detect that the IP address or the port has - changed. - - Note that similar but probably not identical actions will likely be - needed to make IKE work with Mobile IP, but such processing is not - addressed by this document. - -2.24. Explicit Congestion Notification (ECN) - - When IPsec tunnels behave as originally specified in [IPSECARCH-OLD], - ECN usage is not appropriate for the outer IP headers because tunnel - decapsulation processing discards ECN congestion indications to the - detriment of the network. ECN support for IPsec tunnels for IKEv1- - based IPsec requires multiple operating modes and negotiation (see - [ECN]). IKEv2 simplifies this situation by requiring that ECN be - usable in the outer IP headers of all tunnel-mode IPsec SAs created - by IKEv2. Specifically, tunnel encapsulators and decapsulators for - all tunnel-mode SAs created by IKEv2 MUST support the ECN full- - functionality option for tunnels specified in [ECN] and MUST - implement the tunnel encapsulation and decapsulation processing - specified in [IPSECARCH] to prevent discarding of ECN congestion - indications. - - -3. Header and Payload Formats - -3.1. The IKE Header - - IKE messages use UDP ports 500 and/or 4500, with one IKE message per - UDP datagram. Information from the beginning of the packet through - the UDP header is largely ignored except that the IP addresses and - UDP ports from the headers are reversed and used for return packets. - - - -Hoffman Expires July 5, 2006 [Page 53] - -Internet-Draft IKEv2 January 2006 - - - When sent on UDP port 500, IKE messages begin immediately following - the UDP header. When sent on UDP port 4500, IKE messages have - prepended four octets of zero. These four octets of zero are not - part of the IKE message and are not included in any of the length - fields or checksums defined by IKE. Each IKE message begins with the - IKE header, denoted HDR in this memo. Following the header are one - or more IKE payloads each identified by a "Next Payload" field in the - preceding payload. Payloads are processed in the order in which they - appear in an IKE message by invoking the appropriate processing - routine according to the "Next Payload" field in the IKE header and - subsequently according to the "Next Payload" field in the IKE payload - itself until a "Next Payload" field of zero indicates that no - payloads follow. If a payload of type "Encrypted" is found, that - payload is decrypted and its contents parsed as additional payloads. - An Encrypted payload MUST be the last payload in a packet and an - Encrypted payload MUST NOT contain another Encrypted payload. - - The Recipient SPI in the header identifies an instance of an IKE - security association. It is therefore possible for a single instance - of IKE to multiplex distinct sessions with multiple peers. - - All multi-octet fields representing integers are laid out in big - endian order (aka most significant byte first, or network byte - order). - - The format of the IKE header is shown in Figure 4. - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! IKE_SA Initiator's SPI ! - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! IKE_SA Responder's SPI ! - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload ! MjVer ! MnVer ! Exchange Type ! Flags ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Message ID ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 4: IKE Header Format - - o Initiator's SPI (8 octets) - A value chosen by the initiator to - identify a unique IKE security association. This value MUST NOT - be zero. - - - -Hoffman Expires July 5, 2006 [Page 54] - -Internet-Draft IKEv2 January 2006 - - - o Responder's SPI (8 octets) - A value chosen by the responder to - identify a unique IKE security association. This value MUST be - zero in the first message of an IKE Initial Exchange (including - repeats of that message including a cookie). {{ The phrase "and - MUST NOT be zero in any other message" was removed; Clarif-2.1 }} - - o Next Payload (1 octet) - Indicates the type of payload that - immediately follows the header. The format and value of each - payload are defined below. - - o Major Version (4 bits) - Indicates the major version of the IKE - protocol in use. Implementations based on this version of IKE - MUST set the Major Version to 2. Implementations based on - previous versions of IKE and ISAKMP MUST set the Major Version to - 1. Implementations based on this version of IKE MUST reject or - ignore messages containing a version number greater than 2. - - o Minor Version (4 bits) - Indicates the minor version of the IKE - protocol in use. Implementations based on this version of IKE - MUST set the Minor Version to 0. They MUST ignore the minor - version number of received messages. - - o Exchange Type (1 octet) - Indicates the type of exchange being - used. This constrains the payloads sent in each message and - orderings of messages in an exchange. - - Exchange Type Value - ---------------------------------- - RESERVED 0-33 - IKE_SA_INIT 34 - IKE_AUTH 35 - CREATE_CHILD_SA 36 - INFORMATIONAL 37 - RESERVED TO IANA 38-239 - Reserved for private use 240-255 - - o Flags (1 octet) - Indicates specific options that are set for the - message. Presence of options are indicated by the appropriate bit - in the flags field being set. The bits are defined LSB first, so - bit 0 would be the least significant bit of the Flags octet. In - the description below, a bit being 'set' means its value is '1', - while 'cleared' means its value is '0'. - - * X(reserved) (bits 0-2) - These bits MUST be cleared when - sending and MUST be ignored on receipt. - - * I(nitiator) (bit 3 of Flags) - This bit MUST be set in messages - sent by the original initiator of the IKE_SA and MUST be - - - -Hoffman Expires July 5, 2006 [Page 55] - -Internet-Draft IKEv2 January 2006 - - - cleared in messages sent by the original responder. It is used - by the recipient to determine which eight octets of the SPI - were generated by the recipient. - - * V(ersion) (bit 4 of Flags) - This bit indicates that the - transmitter is capable of speaking a higher major version - number of the protocol than the one indicated in the major - version number field. Implementations of IKEv2 must clear this - bit when sending and MUST ignore it in incoming messages. - - * R(esponse) (bit 5 of Flags) - This bit indicates that this - message is a response to a message containing the same message - ID. This bit MUST be cleared in all request messages and MUST - be set in all responses. An IKE endpoint MUST NOT generate a - response to a message that is marked as being a response. - - * X(reserved) (bits 6-7 of Flags) - These bits MUST be cleared - when sending and MUST be ignored on receipt. - - o Message ID (4 octets) - Message identifier used to control - retransmission of lost packets and matching of requests and - responses. It is essential to the security of the protocol - because it is used to prevent message replay attacks. See - Section 2.1 and Section 2.2. - - o Length (4 octets) - Length of total message (header + payloads) in - octets. - -3.2. Generic Payload Header - - Each IKE payload defined in Section 3.3 through Section 3.16 begins - with a generic payload header, shown in Figure 5. Figures for each - payload below will include the generic payload header, but for - brevity the description of each field will be omitted. - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload !C! RESERVED ! Payload Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 5: Generic Payload Header - - The Generic Payload Header fields are defined as follows: - - o Next Payload (1 octet) - Identifier for the payload type of the - next payload in the message. If the current payload is the last - in the message, then this field will be 0. This field provides a - - - -Hoffman Expires July 5, 2006 [Page 56] - -Internet-Draft IKEv2 January 2006 - - - "chaining" capability whereby additional payloads can be added to - a message by appending it to the end of the message and setting - the "Next Payload" field of the preceding payload to indicate the - new payload's type. An Encrypted payload, which must always be - the last payload of a message, is an exception. It contains data - structures in the format of additional payloads. In the header of - an Encrypted payload, the Next Payload field is set to the payload - type of the first contained payload (instead of 0). The payload - type values are: - - Next Payload Type Notation Value - -------------------------------------------------- - No Next Payload 0 - RESERVED 1-32 - Security Association SA 33 - Key Exchange KE 34 - Identification - Initiator IDi 35 - Identification - Responder IDr 36 - Certificate CERT 37 - Certificate Request CERTREQ 38 - Authentication AUTH 39 - Nonce Ni, Nr 40 - Notify N 41 - Delete D 42 - Vendor ID V 43 - Traffic Selector - Initiator TSi 44 - Traffic Selector - Responder TSr 45 - Encrypted E 46 - Configuration CP 47 - Extensible Authentication EAP 48 - RESERVED TO IANA 49-127 - PRIVATE USE 128-255 - - (Payload type values 1-32 should not be assigned in the - future so that there is no overlap with the code assignments - for IKEv1.) - - o Critical (1 bit) - MUST be set to zero if the sender wants the - recipient to skip this payload if it does not understand the - payload type code in the Next Payload field of the previous - payload. MUST be set to one if the sender wants the recipient to - reject this entire message if it does not understand the payload - type. MUST be ignored by the recipient if the recipient - understands the payload type code. MUST be set to zero for - payload types defined in this document. Note that the critical - bit applies to the current payload rather than the "next" payload - whose type code appears in the first octet. The reasoning behind - not setting the critical bit for payloads defined in this document - - - -Hoffman Expires July 5, 2006 [Page 57] - -Internet-Draft IKEv2 January 2006 - - - is that all implementations MUST understand all payload types - defined in this document and therefore must ignore the Critical - bit's value. Skipped payloads are expected to have valid Next - Payload and Payload Length fields. - - o RESERVED (7 bits) - MUST be sent as zero; MUST be ignored on - receipt. - - o Payload Length (2 octets) - Length in octets of the current - payload, including the generic payload header. - -3.3. Security Association Payload - - The Security Association Payload, denoted SA in this memo, is used to - negotiate attributes of a security association. Assembly of Security - Association Payloads requires great peace of mind. An SA payload MAY - contain multiple proposals. If there is more than one, they MUST be - ordered from most preferred to least preferred. Each proposal may - contain multiple IPsec protocols (where a protocol is IKE, ESP, or - AH), each protocol MAY contain multiple transforms, and each - transform MAY contain multiple attributes. When parsing an SA, an - implementation MUST check that the total Payload Length is consistent - with the payload's internal lengths and counts. Proposals, - Transforms, and Attributes each have their own variable length - encodings. They are nested such that the Payload Length of an SA - includes the combined contents of the SA, Proposal, Transform, and - Attribute information. The length of a Proposal includes the lengths - of all Transforms and Attributes it contains. The length of a - Transform includes the lengths of all Attributes it contains. - - The syntax of Security Associations, Proposals, Transforms, and - Attributes is based on ISAKMP; however the semantics are somewhat - different. The reason for the complexity and the hierarchy is to - allow for multiple possible combinations of algorithms to be encoded - in a single SA. Sometimes there is a choice of multiple algorithms, - whereas other times there is a combination of algorithms. For - example, an initiator might want to propose using (AH w/MD5 and ESP - w/3DES) OR (ESP w/MD5 and 3DES). - - One of the reasons the semantics of the SA payload has changed from - ISAKMP and IKEv1 is to make the encodings more compact in common - cases. - - The Proposal structure contains within it a Proposal # and an IPsec - protocol ID. Each structure MUST have the same Proposal # as the - previous one or be one (1) greater. The first Proposal MUST have a - Proposal # of one (1). If two successive structures have the same - Proposal number, it means that the proposal consists of the first - - - -Hoffman Expires July 5, 2006 [Page 58] - -Internet-Draft IKEv2 January 2006 - - - structure AND the second. So a proposal of AH AND ESP would have two - proposal structures, one for AH and one for ESP and both would have - Proposal #1. A proposal of AH OR ESP would have two proposal - structures, one for AH with Proposal #1 and one for ESP with Proposal - #2. - - Each Proposal/Protocol structure is followed by one or more transform - structures. The number of different transforms is generally - determined by the Protocol. AH generally has a single transform: an - integrity check algorithm. ESP generally has two: an encryption - algorithm and an integrity check algorithm. IKE generally has four - transforms: a Diffie-Hellman group, an integrity check algorithm, a - prf algorithm, and an encryption algorithm. If an algorithm that - combines encryption and integrity protection is proposed, it MUST be - proposed as an encryption algorithm and an integrity protection - algorithm MUST NOT be proposed. For each Protocol, the set of - permissible transforms is assigned transform ID numbers, which appear - in the header of each transform. - - If there are multiple transforms with the same Transform Type, the - proposal is an OR of those transforms. If there are multiple - Transforms with different Transform Types, the proposal is an AND of - the different groups. For example, to propose ESP with (3DES or - IDEA) and (HMAC_MD5 or HMAC_SHA), the ESP proposal would contain two - Transform Type 1 candidates (one for 3DES and one for IDEA) and two - Transform Type 2 candidates (one for HMAC_MD5 and one for HMAC_SHA). - This effectively proposes four combinations of algorithms. If the - initiator wanted to propose only a subset of those, for example (3DES - and HMAC_MD5) or (IDEA and HMAC_SHA), there is no way to encode that - as multiple transforms within a single Proposal. Instead, the - initiator would have to construct two different Proposals, each with - two transforms. - - A given transform MAY have one or more Attributes. Attributes are - necessary when the transform can be used in more than one way, as - when an encryption algorithm has a variable key size. The transform - would specify the algorithm and the attribute would specify the key - size. Most transforms do not have attributes. A transform MUST NOT - have multiple attributes of the same type. To propose alternate - values for an attribute (for example, multiple key sizes for the AES - encryption algorithm), and implementation MUST include multiple - Transforms with the same Transform Type each with a single Attribute. - - Note that the semantics of Transforms and Attributes are quite - different from those in IKEv1. In IKEv1, a single Transform carried - multiple algorithms for a protocol with one carried in the Transform - and the others carried in the Attributes. - - - - -Hoffman Expires July 5, 2006 [Page 59] - -Internet-Draft IKEv2 January 2006 - - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload !C! RESERVED ! Payload Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ <Proposals> ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 6: Security Association Payload - - o Proposals (variable) - One or more proposal substructures. - - The payload type for the Security Association Payload is thirty three - (33). - -3.3.1. Proposal Substructure - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! 0 (last) or 2 ! RESERVED ! Proposal Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Proposal # ! Protocol ID ! SPI Size !# of Transforms! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ~ SPI (variable) ~ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ <Transforms> ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 7: Proposal Substructure - - o 0 (last) or 2 (more) (1 octet) - Specifies whether this is the - last Proposal Substructure in the SA. This syntax is inherited - from ISAKMP, but is unnecessary because the last Proposal could be - identified from the length of the SA. The value (2) corresponds - to a Payload Type of Proposal in IKEv1, and the first four octets - of the Proposal structure are designed to look somewhat like the - header of a Payload. - - o RESERVED (1 octet) - MUST be sent as zero; MUST be ignored on - receipt. - - o Proposal Length (2 octets) - Length of this proposal, including - all transforms and attributes that follow. - - - -Hoffman Expires July 5, 2006 [Page 60] - -Internet-Draft IKEv2 January 2006 - - - o Proposal # (1 octet) - When a proposal is made, the first proposal - in an SA payload MUST be #1, and subsequent proposals MUST either - be the same as the previous proposal (indicating an AND of the two - proposals) or one more than the previous proposal (indicating an - OR of the two proposals). When a proposal is accepted, all of the - proposal numbers in the SA payload MUST be the same and MUST match - the number on the proposal sent that was accepted. - - o Protocol ID (1 octet) - Specifies the IPsec protocol identifier - for the current negotiation. The defined values are: - - Protocol Protocol ID - ----------------------------------- - RESERVED 0 - IKE 1 - AH 2 - ESP 3 - RESERVED TO IANA 4-200 - PRIVATE USE 201-255 - - o SPI Size (1 octet) - For an initial IKE_SA negotiation, this field - MUST be zero; the SPI is obtained from the outer header. During - subsequent negotiations, it is equal to the size, in octets, of - the SPI of the corresponding protocol (8 for IKE, 4 for ESP and - AH). - - o # of Transforms (1 octet) - Specifies the number of transforms in - this proposal. - - o SPI (variable) - The sending entity's SPI. Even if the SPI Size - is not a multiple of 4 octets, there is no padding applied to the - payload. When the SPI Size field is zero, this field is not - present in the Security Association payload. - - o Transforms (variable) - One or more transform substructures. - - - - - - - - - - - - - - - - -Hoffman Expires July 5, 2006 [Page 61] - -Internet-Draft IKEv2 January 2006 - - -3.3.2. Transform Substructure - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! 0 (last) or 3 ! RESERVED ! Transform Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - !Transform Type ! RESERVED ! Transform ID ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ Transform Attributes ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 8: Transform Substructure - - o 0 (last) or 3 (more) (1 octet) - Specifies whether this is the - last Transform Substructure in the Proposal. This syntax is - inherited from ISAKMP, but is unnecessary because the last - Proposal could be identified from the length of the SA. The value - (3) corresponds to a Payload Type of Transform in IKEv1, and the - first four octets of the Transform structure are designed to look - somewhat like the header of a Payload. - - o RESERVED - MUST be sent as zero; MUST be ignored on receipt. - - o Transform Length - The length (in octets) of the Transform - Substructure including Header and Attributes. - - o Transform Type (1 octet) - The type of transform being specified - in this transform. Different protocols support different - transform types. For some protocols, some of the transforms may - be optional. If a transform is optional and the initiator wishes - to propose that the transform be omitted, no transform of the - given type is included in the proposal. If the initiator wishes - to make use of the transform optional to the responder, it - includes a transform substructure with transform ID = 0 as one of - the options. - - o Transform ID (2 octets) - The specific instance of the transform - type being proposed. - - The tranform type values are: - - - - - - - - -Hoffman Expires July 5, 2006 [Page 62] - -Internet-Draft IKEv2 January 2006 - - - Description Trans. Used In - Type - ------------------------------------------------------------------ - RESERVED 0 - Encryption Algorithm (ENCR) 1 IKE and ESP - Pseudo-random Function (PRF) 2 IKE - Integrity Algorithm (INTEG) 3 IKE, AH, optional in ESP - Diffie-Hellman Group (D-H) 4 IKE, optional in AH & ESP - Extended Sequence Numbers (ESN) 5 AH and ESP - RESERVED TO IANA 6-240 - PRIVATE USE 241-255 - - For Transform Type 1 (Encryption Algorithm), defined Transform IDs - are: - - Name Number Defined In - --------------------------------------------------- - RESERVED 0 - ENCR_DES_IV64 1 (RFC1827) - ENCR_DES 2 (RFC2405), [DES] - ENCR_3DES 3 (RFC2451) - ENCR_RC5 4 (RFC2451) - ENCR_IDEA 5 (RFC2451), [IDEA] - ENCR_CAST 6 (RFC2451) - ENCR_BLOWFISH 7 (RFC2451) - ENCR_3IDEA 8 (RFC2451) - ENCR_DES_IV32 9 - RESERVED 10 - ENCR_NULL 11 (RFC2410) - ENCR_AES_CBC 12 (RFC3602) - ENCR_AES_CTR 13 (RFC3664) - RESERVED TO IANA 14-1023 - PRIVATE USE 1024-65535 - - For Transform Type 2 (Pseudo-random Function), defined Transform IDs - are: - - Name Number Defined In - ------------------------------------------------------ - RESERVED 0 - PRF_HMAC_MD5 1 (RFC2104), [MD5] - PRF_HMAC_SHA1 2 (RFC2104), [SHA] - PRF_HMAC_TIGER 3 (RFC2104) - PRF_AES128_XCBC 4 (RFC3664) - RESERVED TO IANA 5-1023 - PRIVATE USE 1024-65535 - - For Transform Type 3 (Integrity Algorithm), defined Transform IDs - - - -Hoffman Expires July 5, 2006 [Page 63] - -Internet-Draft IKEv2 January 2006 - - - are: - - Name Number Defined In - ---------------------------------------- - NONE 0 - AUTH_HMAC_MD5_96 1 (RFC2403) - AUTH_HMAC_SHA1_96 2 (RFC2404) - AUTH_DES_MAC 3 - AUTH_KPDK_MD5 4 (RFC1826) - AUTH_AES_XCBC_96 5 (RFC3566) - RESERVED TO IANA 6-1023 - PRIVATE USE 1024-65535 - - For Transform Type 4 (Diffie-Hellman Group), defined Transform IDs - are: - - Name Number - -------------------------------------- - NONE 0 - Defined in Appendix B 1 - 2 - RESERVED 3 - 4 - Defined in [ADDGROUP] 5 - RESERVED TO IANA 6 - 13 - Defined in [ADDGROUP] 14 - 18 - RESERVED TO IANA 19 - 1023 - PRIVATE USE 1024-65535 - - For Transform Type 5 (Extended Sequence Numbers), defined Transform - IDs are: - - Name Number - -------------------------------------------- - No Extended Sequence Numbers 0 - Extended Sequence Numbers 1 - RESERVED 2 - 65535 - -3.3.3. Valid Transform Types by Protocol - - The number and type of transforms that accompany an SA payload are - dependent on the protocol in the SA itself. An SA payload proposing - the establishment of an SA has the following mandatory and optional - transform types. A compliant implementation MUST understand all - mandatory and optional types for each protocol it supports (though it - need not accept proposals with unacceptable suites). A proposal MAY - omit the optional types if the only value for them it will accept is - NONE. - - - - - -Hoffman Expires July 5, 2006 [Page 64] - -Internet-Draft IKEv2 January 2006 - - - Protocol Mandatory Types Optional Types - --------------------------------------------------- - IKE ENCR, PRF, INTEG, D-H - ESP ENCR, ESN INTEG, D-H - AH INTEG, ESN D-H - -3.3.4. Mandatory Transform IDs - - The specification of suites that MUST and SHOULD be supported for - interoperability has been removed from this document because they are - likely to change more rapidly than this document evolves. - - An important lesson learned from IKEv1 is that no system should only - implement the mandatory algorithms and expect them to be the best - choice for all customers. For example, at the time that this - document was written, many IKEv1 implementers were starting to - migrate to AES in Cipher Block Chaining (CBC) mode for Virtual - Private Network (VPN) applications. Many IPsec systems based on - IKEv2 will implement AES, additional Diffie-Hellman groups, and - additional hash algorithms, and some IPsec customers already require - these algorithms in addition to the ones listed above. - - It is likely that IANA will add additional transforms in the future, - and some users may want to use private suites, especially for IKE - where implementations should be capable of supporting different - parameters, up to certain size limits. In support of this goal, all - implementations of IKEv2 SHOULD include a management facility that - allows specification (by a user or system administrator) of Diffie- - Hellman (DH) parameters (the generator, modulus, and exponent lengths - and values) for new DH groups. Implementations SHOULD provide a - management interface through which these parameters and the - associated transform IDs may be entered (by a user or system - administrator), to enable negotiating such groups. - - All implementations of IKEv2 MUST include a management facility that - enables a user or system administrator to specify the suites that are - acceptable for use with IKE. Upon receipt of a payload with a set of - transform IDs, the implementation MUST compare the transmitted - transform IDs against those locally configured via the management - controls, to verify that the proposed suite is acceptable based on - local policy. The implementation MUST reject SA proposals that are - not authorized by these IKE suite controls. Note that cryptographic - suites that MUST be implemented need not be configured as acceptable - to local policy. - - - - - - - -Hoffman Expires July 5, 2006 [Page 65] - -Internet-Draft IKEv2 January 2006 - - -3.3.5. Transform Attributes - - Each transform in a Security Association payload may include - attributes that modify or complete the specification of the - transform. These attributes are type/value pairs and are defined - below. For example, if an encryption algorithm has a variable-length - key, the key length to be used may be specified as an attribute. - Attributes can have a value with a fixed two octet length or a - variable-length value. For the latter, the attribute is encoded as - type/length/value. - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - !A! Attribute Type ! AF=0 Attribute Length ! - !F! ! AF=1 Attribute Value ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! AF=0 Attribute Value ! - ! AF=1 Not Transmitted ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 9: Data Attributes - - o Attribute Type (2 octets) - Unique identifier for each type of - attribute (see below). The most significant bit of this field is - the Attribute Format bit (AF). It indicates whether the data - attributes follow the Type/Length/Value (TLV) format or a - shortened Type/Value (TV) format. If the AF bit is zero (0), then - the Data Attributes are of the Type/Length/Value (TLV) form. If - the AF bit is a one (1), then the Data Attributes are of the Type/ - Value form. - - o Attribute Length (2 octets) - Length in octets of the Attribute - Value. When the AF bit is a one (1), the Attribute Value is only - 2 octets and the Attribute Length field is not present. - - o Attribute Value (variable length) - Value of the Attribute - associated with the Attribute Type. If the AF bit is a zero (0), - this field has a variable length defined by the Attribute Length - field. If the AF bit is a one (1), the Attribute Value has a - length of 2 octets. - - o Key Length - When using an Encryption Algorithm that has a - variable-length key, this attribute specifies the key length in - bits (MUST use network byte order). This attribute MUST NOT be - used when the specified Encryption Algorithm uses a fixed-length - key. - - - - -Hoffman Expires July 5, 2006 [Page 66] - -Internet-Draft IKEv2 January 2006 - - - Note that only a single attribute type (Key Length) is defined, and - it is fixed length. The variable-length encoding specification is - included only for future extensions. {{ Clarif-7.11 removed the - sentence that listed, incorrectly, the algorithms defined in the - document that accept attributes. }} - - Attributes described as basic MUST NOT be encoded using the variable- - length encoding. Variable-length attributes MUST NOT be encoded as - basic even if their value can fit into two octets. NOTE: This is a - change from IKEv1, where increased flexibility may have simplified - the composer of messages but certainly complicated the parser. - - Attribute Type Value Attribute Format - ------------------------------------------------------------ - RESERVED 0-13 - Key Length (in bits) 14 TV - RESERVED 15-17 - RESERVED TO IANA 18-16383 - PRIVATE USE 16384-32767 - Values 0-13 and 15-17 were used in a similar context in - IKEv1, and should not be assigned except to matching values. - -3.3.6. Attribute Negotiation - - During security association negotiation initiators present offers to - responders. Responders MUST select a single complete set of - parameters from the offers (or reject all offers if none are - acceptable). If there are multiple proposals, the responder MUST - choose a single proposal number and return all of the Proposal - substructures with that Proposal number. If there are multiple - Transforms with the same type, the responder MUST choose a single - one. Any attributes of a selected transform MUST be returned - unmodified. The initiator of an exchange MUST check that the - accepted offer is consistent with one of its proposals, and if not - that response MUST be rejected. - - Negotiating Diffie-Hellman groups presents some special challenges. - SA offers include proposed attributes and a Diffie-Hellman public - number (KE) in the same message. If in the initial exchange the - initiator offers to use one of several Diffie-Hellman groups, it - SHOULD pick the one the responder is most likely to accept and - include a KE corresponding to that group. If the guess turns out to - be wrong, the responder will indicate the correct group in the - response and the initiator SHOULD pick an element of that group for - its KE value when retrying the first message. It SHOULD, however, - continue to propose its full supported set of groups in order to - prevent a man-in-the-middle downgrade attack. - - - - -Hoffman Expires July 5, 2006 [Page 67] - -Internet-Draft IKEv2 January 2006 - - - Implementation Note: - - Certain negotiable attributes can have ranges or could have multiple - acceptable values. These include the key length of a variable key - length symmetric cipher. To further interoperability and to support - upgrading endpoints independently, implementers of this protocol - SHOULD accept values that they deem to supply greater security. For - instance, if a peer is configured to accept a variable-length cipher - with a key length of X bits and is offered that cipher with a larger - key length, the implementation SHOULD accept the offer if it supports - use of the longer key. - - Support of this capability allows an implementation to express a - concept of "at least" a certain level of security-- "a key length of - _at least_ X bits for cipher Y". - -3.4. Key Exchange Payload - - The Key Exchange Payload, denoted KE in this memo, is used to - exchange Diffie-Hellman public numbers as part of a Diffie-Hellman - key exchange. The Key Exchange Payload consists of the IKE generic - payload header followed by the Diffie-Hellman public value itself. - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload !C! RESERVED ! Payload Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! DH Group # ! RESERVED ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ Key Exchange Data ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 10: Key Exchange Payload Format - - A key exchange payload is constructed by copying one's Diffie-Hellman - public value into the "Key Exchange Data" portion of the payload. - The length of the Diffie-Hellman public value MUST be equal to the - length of the prime modulus over which the exponentiation was - performed, prepending zero bits to the value if necessary. - - The DH Group # identifies the Diffie-Hellman group in which the Key - Exchange Data was computed (see Section 3.3.2). If the selected - proposal uses a different Diffie-Hellman group, the message MUST be - rejected with a Notify payload of type INVALID_KE_PAYLOAD. - - - - -Hoffman Expires July 5, 2006 [Page 68] - -Internet-Draft IKEv2 January 2006 - - - The payload type for the Key Exchange payload is thirty four (34). - -3.5. Identification Payloads - - The Identification Payloads, denoted IDi and IDr in this memo, allow - peers to assert an identity to one another. This identity may be - used for policy lookup, but does not necessarily have to match - anything in the CERT payload; both fields may be used by an - implementation to perform access control decisions. {{ Clarif-7.1 }} - When using the ID_IPV4_ADDR/ID_IPV6_ADDR identity types in IDi/IDr - payloads, IKEv2 does not require this address to match the address in - the IP header of IKEv2 packets, or anything in the TSi/TSr payloads. - The contents of IDi/IDr is used purely to fetch the policy and - authentication data related to the other party. - - NOTE: In IKEv1, two ID payloads were used in each direction to hold - Traffic Selector (TS) information for data passing over the SA. In - IKEv2, this information is carried in TS payloads (see Section 3.13). - - The Identification Payload consists of the IKE generic payload header - followed by identification fields as follows: - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload !C! RESERVED ! Payload Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ID Type ! RESERVED | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ Identification Data ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 11: Identification Payload Format - - o ID Type (1 octet) - Specifies the type of Identification being - used. - - o RESERVED - MUST be sent as zero; MUST be ignored on receipt. - - o Identification Data (variable length) - Value, as indicated by the - Identification Type. The length of the Identification Data is - computed from the size in the ID payload header. - - The payload types for the Identification Payload are thirty five (35) - for IDi and thirty six (36) for IDr. - - - - -Hoffman Expires July 5, 2006 [Page 69] - -Internet-Draft IKEv2 January 2006 - - - The following table lists the assigned values for the Identification - Type field: - - ID Type Value - ------------------------------------------------------------------- - RESERVED 0 - - ID_IPV4_ADDR 1 - A single four (4) octet IPv4 address. - - ID_FQDN 2 - A fully-qualified domain name string. An example of a ID_FQDN - is, "example.com". The string MUST not contain any terminators - (e.g., NULL, CR, etc.). - - ID_RFC822_ADDR 3 - A fully-qualified RFC822 email address string, An example of a - ID_RFC822_ADDR is, "jsmith@example.com". The string MUST not - contain any terminators. - - RESERVED TO IANA 4 - - ID_IPV6_ADDR 5 - A single sixteen (16) octet IPv6 address. - - RESERVED TO IANA 6 - 8 - - ID_DER_ASN1_DN 9 - The binary Distinguished Encoding Rules (DER) encoding of an - ASN.1 X.500 Distinguished Name [X.501]. - - ID_DER_ASN1_GN 10 - The binary DER encoding of an ASN.1 X.500 GeneralName [X.509]. - - ID_KEY_ID 11 - An opaque octet stream which may be used to pass vendor- - specific information necessary to do certain proprietary - types of identification. - - RESERVED TO IANA 12-200 - - PRIVATE USE 201-255 - - Two implementations will interoperate only if each can generate a - type of ID acceptable to the other. To assure maximum - interoperability, implementations MUST be configurable to send at - least one of ID_IPV4_ADDR, ID_FQDN, ID_RFC822_ADDR, or ID_KEY_ID, and - MUST be configurable to accept all of these types. Implementations - - - -Hoffman Expires July 5, 2006 [Page 70] - -Internet-Draft IKEv2 January 2006 - - - SHOULD be capable of generating and accepting all of these types. - IPv6-capable implementations MUST additionally be configurable to - accept ID_IPV6_ADDR. IPv6-only implementations MAY be configurable - to send only ID_IPV6_ADDR. - - {{ Clarif-3.4 }} EAP [EAP] does not mandate the use of any particular - type of identifier, but often EAP is used with Network Access - Identifiers (NAIs) defined in [NAI]. Although NAIs look a bit like - email addresses (e.g., "joe@example.com"), the syntax is not exactly - the same as the syntax of email address in [MAILFORMAT]. For those - NAIs that include the realm component, the ID_RFC822_ADDR - identification type SHOULD be used. Responder implementations should - not attempt to verify that the contents actually conform to the exact - syntax given in [MAILFORMAT], but instead should accept any - reasonable-looking NAI. For NAIs that do not include the realm - component,the ID_KEY_ID identification type SHOULD be used. - -3.6. Certificate Payload - - The Certificate Payload, denoted CERT in this memo, provides a means - to transport certificates or other authentication-related information - via IKE. Certificate payloads SHOULD be included in an exchange if - certificates are available to the sender unless the peer has - indicated an ability to retrieve this information from elsewhere - using an HTTP_CERT_LOOKUP_SUPPORTED Notify payload. Note that the - term "Certificate Payload" is somewhat misleading, because not all - authentication mechanisms use certificates and data other than - certificates may be passed in this payload. - - The Certificate Payload is defined as follows: - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload !C! RESERVED ! Payload Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Cert Encoding ! ! - +-+-+-+-+-+-+-+-+ ! - ~ Certificate Data ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 12: Certificate Payload Format - - o Certificate Encoding (1 octet) - This field indicates the type of - certificate or certificate-related information contained in the - Certificate Data field. - - - - -Hoffman Expires July 5, 2006 [Page 71] - -Internet-Draft IKEv2 January 2006 - - - Certificate Encoding Value - ------------------------------------------------- - RESERVED 0 - PKCS #7 wrapped X.509 certificate 1 - PGP Certificate 2 - DNS Signed Key 3 - X.509 Certificate - Signature 4 - Kerberos Token 6 - Certificate Revocation List (CRL) 7 - Authority Revocation List (ARL) 8 - SPKI Certificate 9 - X.509 Certificate - Attribute 10 - Raw RSA Key 11 - Hash and URL of X.509 certificate 12 - Hash and URL of X.509 bundle 13 - RESERVED to IANA 14 - 200 - PRIVATE USE 201 - 255 - - o Certificate Data (variable length) - Actual encoding of - certificate data. The type of certificate is indicated by the - Certificate Encoding field. - - The payload type for the Certificate Payload is thirty seven (37). - - Specific syntax is for some of the certificate type codes above is - not defined in this document. The types whose syntax is defined in - this document are: - - o X.509 Certificate - Signature (4) contains a DER encoded X.509 - certificate whose public key is used to validate the sender's AUTH - payload. - - o Certificate Revocation List (7) contains a DER encoded X.509 - certificate revocation list. - - o {{ Added "DER-encoded RSAPublicKey structure" from Clarif-3.7 }} - Raw RSA Key (11) contains a PKCS #1 encoded RSA key, that is, a - DER-encoded RSAPublicKey structure (see [RSA] and [PKCS1]). - - o Hash and URL encodings (12-13) allow IKE messages to remain short - by replacing long data structures with a 20 octet SHA-1 hash (see - [SHA]) of the replaced value followed by a variable-length URL - that resolves to the DER encoded data structure itself. This - improves efficiency when the endpoints have certificate data - cached and makes IKE less subject to denial of service attacks - that become easier to mount when IKE messages are large enough to - require IP fragmentation [DOSUDPPROT]. - - - - -Hoffman Expires July 5, 2006 [Page 72] - -Internet-Draft IKEv2 January 2006 - - - Use the following ASN.1 definition for an X.509 bundle: - - CertBundle - { iso(1) identified-organization(3) dod(6) internet(1) - security(5) mechanisms(5) pkix(7) id-mod(0) - id-mod-cert-bundle(34) } - - DEFINITIONS EXPLICIT TAGS ::= - BEGIN - - IMPORTS - Certificate, CertificateList - FROM PKIX1Explicit88 - { iso(1) identified-organization(3) dod(6) - internet(1) security(5) mechanisms(5) pkix(7) - id-mod(0) id-pkix1-explicit(18) } ; - - CertificateOrCRL ::= CHOICE { - cert [0] Certificate, - crl [1] CertificateList } - - CertificateBundle ::= SEQUENCE OF CertificateOrCRL - - END - - Implementations MUST be capable of being configured to send and - accept up to four X.509 certificates in support of authentication, - and also MUST be capable of being configured to send and accept the - first two Hash and URL formats (with HTTP URLs). Implementations - SHOULD be capable of being configured to send and accept Raw RSA - keys. If multiple certificates are sent, the first certificate MUST - contain the public key used to sign the AUTH payload. The other - certificates may be sent in any order. - - {{ Clarif-3.7 }} Because the contents and use of some of the - certificate types are not defined, they SHOULD NOT be used. In - specific, implementations SHOULD NOT use the following types unless - they are later defined in a standards-track document: - - PKCS #7 wrapped X.509 certificate 1 - PGP Certificate 2 - DNS Signed Key 3 - Kerberos Token 6 - SPKI Certificate 9 - - - - - - - -Hoffman Expires July 5, 2006 [Page 73] - -Internet-Draft IKEv2 January 2006 - - -3.7. Certificate Request Payload - - The Certificate Request Payload, denoted CERTREQ in this memo, - provides a means to request preferred certificates via IKE and can - appear in the IKE_INIT_SA response and/or the IKE_AUTH request. - Certificate Request payloads MAY be included in an exchange when the - sender needs to get the certificate of the receiver. If multiple CAs - are trusted and the cert encoding does not allow a list, then - multiple Certificate Request payloads SHOULD be transmitted. - - The Certificate Request Payload is defined as follows: - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload !C! RESERVED ! Payload Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Cert Encoding ! ! - +-+-+-+-+-+-+-+-+ ! - ~ Certification Authority ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 13: Certificate Request Payload Format - - o Certificate Encoding (1 octet) - Contains an encoding of the type - or format of certificate requested. Values are listed in - Section 3.6. - - o Certification Authority (variable length) - Contains an encoding - of an acceptable certification authority for the type of - certificate requested. - - The payload type for the Certificate Request Payload is thirty eight - (38). - - The Certificate Encoding field has the same values as those defined - in Section 3.6. The Certification Authority field contains an - indicator of trusted authorities for this certificate type. The - Certification Authority value is a concatenated list of SHA-1 hashes - of the public keys of trusted Certification Authorities (CAs). Each - is encoded as the SHA-1 hash of the Subject Public Key Info element - (see section 4.1.2.7 of [PKIX]) from each Trust Anchor certificate. - The twenty-octet hashes are concatenated and included with no other - formatting. - - {{ Clarif-3.7 }} The contents of the "Certification Authority" field - are defined only for X.509 certificates, which are types 4, 10, 12, - - - -Hoffman Expires July 5, 2006 [Page 74] - -Internet-Draft IKEv2 January 2006 - - - and 13. Other values SHOULD NOT be used until standards-track - specifications that specify their use are published. - - Note that the term "Certificate Request" is somewhat misleading, in - that values other than certificates are defined in a "Certificate" - payload and requests for those values can be present in a Certificate - Request Payload. The syntax of the Certificate Request payload in - such cases is not defined in this document. - - The Certificate Request Payload is processed by inspecting the "Cert - Encoding" field to determine whether the processor has any - certificates of this type. If so, the "Certification Authority" - field is inspected to determine if the processor has any certificates - that can be validated up to one of the specified certification - authorities. This can be a chain of certificates. - - If an end-entity certificate exists that satisfies the criteria - specified in the CERTREQ, a certificate or certificate chain SHOULD - be sent back to the certificate requestor if the recipient of the - CERTREQ: - - o is configured to use certificate authentication, - - o is allowed to send a CERT payload, - - o has matching CA trust policy governing the current negotiation, - and - - o has at least one time-wise and usage appropriate end-entity - certificate chaining to a CA provided in the CERTREQ. - - Certificate revocation checking must be considered during the - chaining process used to select a certificate. Note that even if two - peers are configured to use two different CAs, cross-certification - relationships should be supported by appropriate selection logic. - - The intent is not to prevent communication through the strict - adherence of selection of a certificate based on CERTREQ, when an - alternate certificate could be selected by the sender that would - still enable the recipient to successfully validate and trust it - through trust conveyed by cross-certification, CRLs, or other out-of- - band configured means. Thus, the processing of a CERTREQ should be - seen as a suggestion for a certificate to select, not a mandated one. - If no certificates exist, then the CERTREQ is ignored. This is not - an error condition of the protocol. There may be cases where there - is a preferred CA sent in the CERTREQ, but an alternate might be - acceptable (perhaps after prompting a human operator). - - - - -Hoffman Expires July 5, 2006 [Page 75] - -Internet-Draft IKEv2 January 2006 - - -3.8. Authentication Payload - - The Authentication Payload, denoted AUTH in this memo, contains data - used for authentication purposes. The syntax of the Authentication - data varies according to the Auth Method as specified below. - - The Authentication Payload is defined as follows: - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload !C! RESERVED ! Payload Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Auth Method ! RESERVED ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ Authentication Data ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 14: Authentication Payload Format - - o Auth Method (1 octet) - Specifies the method of authentication - used. Values defined are: - - * RSA Digital Signature (1) - Computed as specified in - Section 2.15 using an RSA private key over a PKCS#1 padded hash - (see [RSA] and [PKCS1]). {{ Clarif-3.2 }} To promote - interoperability, implementations that support this type SHOULD - support signatures that use SHA-1 as the hash function and - SHOULD use SHA-1 as the default hash function when generating - signatures. {{ Clarif-3.3 }} A newer version of PKCS#1 (v2.1) - defines two different encoding methods (ways of "padding the - hash") for signatures. However, IKEv2 and this document point - specifically to the PKCS#1 v2.0 which has only one encoding - method for signatures (EMSA-PKCS1- v1_5). - - * Shared Key Message Integrity Code (2) - Computed as specified - in Section 2.15 using the shared key associated with the - identity in the ID payload and the negotiated prf function - - * DSS Digital Signature (3) - Computed as specified in - Section 2.15 using a DSS private key (see [DSS]) over a SHA-1 - hash. - - * The values 0 and 4-200 are reserved to IANA. The values 201- - 255 are available for private use. - - - - -Hoffman Expires July 5, 2006 [Page 76] - -Internet-Draft IKEv2 January 2006 - - - o Authentication Data (variable length) - see Section 2.15. - - The payload type for the Authentication Payload is thirty nine (39). - -3.9. Nonce Payload - - The Nonce Payload, denoted Ni and Nr in this memo for the initiator's - and responder's nonce respectively, contains random data used to - guarantee liveness during an exchange and protect against replay - attacks. - - The Nonce Payload is defined as follows: - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload !C! RESERVED ! Payload Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ Nonce Data ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 15: Nonce Payload Format - - o Nonce Data (variable length) - Contains the random data generated - by the transmitting entity. - - The payload type for the Nonce Payload is forty (40). - - The size of a Nonce MUST be between 16 and 256 octets inclusive. - Nonce values MUST NOT be reused. - -3.10. Notify Payload - - The Notify Payload, denoted N in this document, is used to transmit - informational data, such as error conditions and state transitions, - to an IKE peer. A Notify Payload may appear in a response message - (usually specifying why a request was rejected), in an INFORMATIONAL - Exchange (to report an error not in an IKE request), or in any other - message to indicate sender capabilities or to modify the meaning of - the request. - - The Notify Payload is defined as follows: - - - - - - - -Hoffman Expires July 5, 2006 [Page 77] - -Internet-Draft IKEv2 January 2006 - - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload !C! RESERVED ! Payload Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Protocol ID ! SPI Size ! Notify Message Type ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ Security Parameter Index (SPI) ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ Notification Data ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 16: Notify Payload Format - - o Protocol ID (1 octet) - If this notification concerns an existing - SA, this field indicates the type of that SA. For IKE_SA - notifications, this field MUST be one (1). For notifications - concerning IPsec SAs this field MUST contain either (2) to - indicate AH or (3) to indicate ESP. {{ Clarif-7.8 }} For - notifications that do not relate to an existing SA, this field - MUST be sent as zero and MUST be ignored on receipt; this is only - true for the INVALID_SELECTORS and REKEY_SA notifications. . All - other values for this field are reserved to IANA for future - assignment. - - o SPI Size (1 octet) - Length in octets of the SPI as defined by the - IPsec protocol ID or zero if no SPI is applicable. For a - notification concerning the IKE_SA, the SPI Size MUST be zero. - - o Notify Message Type (2 octets) - Specifies the type of - notification message. - - o SPI (variable length) - Security Parameter Index. - - o Notification Data (variable length) - Informational or error data - transmitted in addition to the Notify Message Type. Values for - this field are type specific (see below). - - The payload type for the Notify Payload is forty one (41). - -3.10.1. Notify Message Types - - Notification information can be error messages specifying why an SA - could not be established. It can also be status data that a process - - - -Hoffman Expires July 5, 2006 [Page 78] - -Internet-Draft IKEv2 January 2006 - - - managing an SA database wishes to communicate with a peer process. - The table below lists the Notification messages and their - corresponding values. The number of different error statuses was - greatly reduced from IKEv1 both for simplification and to avoid - giving configuration information to probers. - - Types in the range 0 - 16383 are intended for reporting errors. An - implementation receiving a Notify payload with one of these types - that it does not recognize in a response MUST assume that the - corresponding request has failed entirely. {{ Demoted the SHOULD }} - Unrecognized error types in a request and status types in a request - or response MUST be ignored, and they should be logged. - - Notify payloads with status types MAY be added to any message and - MUST be ignored if not recognized. They are intended to indicate - capabilities, and as part of SA negotiation are used to negotiate - non-cryptographic parameters. - - NOTIFY messages: error types Value - ------------------------------------------------------------------- - - RESERVED 0 - - UNSUPPORTED_CRITICAL_PAYLOAD 1 - Sent if the payload has the "critical" bit set and the payload - type is not recognized. Notification Data contains the one-octet - payload type. - - INVALID_IKE_SPI 4 - Indicates an IKE message was received with an unrecognized - destination SPI. This usually indicates that the recipient has - rebooted and forgotten the existence of an IKE_SA. - - INVALID_MAJOR_VERSION 5 - Indicates the recipient cannot handle the version of IKE - specified in the header. The closest version number that the - recipient can support will be in the reply header. - - INVALID_SYNTAX 7 - Indicates the IKE message that was received was invalid because - some type, length, or value was out of range or because the - request was rejected for policy reasons. To avoid a denial of - service attack using forged messages, this status may only be - returned for and in an encrypted packet if the message ID and - cryptographic checksum were valid. To avoid leaking information - to someone probing a node, this status MUST be sent in response - to any error not covered by one of the other status types. - {{ Demoted the SHOULD }} To aid debugging, more detailed error - - - -Hoffman Expires July 5, 2006 [Page 79] - -Internet-Draft IKEv2 January 2006 - - - information should be written to a console or log. - - INVALID_MESSAGE_ID 9 - Sent when an IKE message ID outside the supported window is - received. This Notify MUST NOT be sent in a response; the invalid - request MUST NOT be acknowledged. Instead, inform the other side - by initiating an INFORMATIONAL exchange with Notification data - containing the four octet invalid message ID. Sending this - notification is optional, and notifications of this type MUST be - rate limited. - - INVALID_SPI 11 - MAY be sent in an IKE INFORMATIONAL exchange when a node receives - an ESP or AH packet with an invalid SPI. The Notification Data - contains the SPI of the invalid packet. This usually indicates a - node has rebooted and forgotten an SA. If this Informational - Message is sent outside the context of an IKE_SA, it should only - be used by the recipient as a "hint" that something might be - wrong (because it could easily be forged). - - NO_PROPOSAL_CHOSEN 14 - None of the proposed crypto suites was acceptable. - - INVALID_KE_PAYLOAD 17 - The D-H Group # field in the KE payload is not the group # - selected by the responder for this exchange. There are two octets - of data associated with this notification: the accepted D-H Group - # in big endian order. - - AUTHENTICATION_FAILED 24 - Sent in the response to an IKE_AUTH message when for some reason - the authentication failed. There is no associated data. - - SINGLE_PAIR_REQUIRED 34 - This error indicates that a CREATE_CHILD_SA request is - unacceptable because its sender is only willing to accept traffic - selectors specifying a single pair of addresses. The requestor is - expected to respond by requesting an SA for only the specific - traffic it is trying to forward. - - NO_ADDITIONAL_SAS 35 - This error indicates that a CREATE_CHILD_SA request is - unacceptable because the responder is unwilling to accept any - more CHILD_SAs on this IKE_SA. Some minimal implementations may - only accept a single CHILD_SA setup in the context of an initial - IKE exchange and reject any subsequent attempts to add more. - - INTERNAL_ADDRESS_FAILURE 36 - - - -Hoffman Expires July 5, 2006 [Page 80] - -Internet-Draft IKEv2 January 2006 - - - Indicates an error assigning an internal address (i.e., - INTERNAL_IP4_ADDRESS or INTERNAL_IP6_ADDRESS) during the - processing of a Configuration Payload by a responder. If this - error is generated within an IKE_AUTH exchange, no CHILD_SA will - be created. - - FAILED_CP_REQUIRED 37 - Sent by responder in the case where CP(CFG_REQUEST) was expected - but not received, and so is a conflict with locally configured - policy. There is no associated data. - - TS_UNACCEPTABLE 38 - Indicates that none of the addresses/protocols/ports in the - supplied traffic selectors is acceptable. - - INVALID_SELECTORS 39 - MAY be sent in an IKE INFORMATIONAL exchange when a node receives - an ESP or AH packet whose selectors do not match those of the SA - on which it was delivered (and that caused the packet to be - dropped). The Notification Data contains the start of the - offending packet (as in ICMP messages) and the SPI field of the - notification is set to match the SPI of the IPsec SA. - - RESERVED TO IANA 40-8191 - - PRIVATE USE 8192-16383 - - - NOTIFY messages: status types Value - ------------------------------------------------------------------- - - INITIAL_CONTACT 16384 - This notification asserts that this IKE_SA is the only IKE_SA - currently active between the authenticated identities. It MAY be - sent when an IKE_SA is established after a crash, and the - recipient MAY use this information to delete any other IKE_SAs it - has to the same authenticated identity without waiting for a - timeout. This notification MUST NOT be sent by an entity that may - be replicated (e.g., a roaming user's credentials where the user - is allowed to connect to the corporate firewall from two remote - systems at the same time). {{ Clarif-7.9 }} The INITIAL_CONTACT - notification, if sent, MUST be in the first IKE_AUTH request, - not as a separate exchange afterwards. - - SET_WINDOW_SIZE 16385 - This notification asserts that the sending endpoint is capable of - keeping state for multiple outstanding exchanges, permitting the - recipient to send multiple requests before getting a response to - - - -Hoffman Expires July 5, 2006 [Page 81] - -Internet-Draft IKEv2 January 2006 - - - the first. The data associated with a SET_WINDOW_SIZE - notification MUST be 4 octets long and contain the big endian - representation of the number of messages the sender promises to - keep. Window size is always one until the initial exchanges - complete. - - ADDITIONAL_TS_POSSIBLE 16386 - This notification asserts that the sending endpoint narrowed the - proposed traffic selectors but that other traffic selectors would - also have been acceptable, though only in a separate SA (see - section 2.9). There is no data associated with this Notify type. - It may be sent only as an additional payload in a message - including accepted TSs. - - IPCOMP_SUPPORTED 16387 - This notification may be included only in a message containing an - SA payload negotiating a CHILD_SA and indicates a willingness by - its sender to use IPComp on this SA. The data associated with - this notification includes a two-octet IPComp CPI followed by a - one-octet transform ID optionally followed by attributes whose - length and format are defined by that transform ID. A message - proposing an SA may contain multiple IPCOMP_SUPPORTED - notifications to indicate multiple supported algorithms. A - message accepting an SA may contain at most one. - - The transform IDs currently defined are: - - Name Number Defined In - ------------------------------------- - RESERVED 0 - IPCOMP_OUI 1 - IPCOMP_DEFLATE 2 RFC 2394 - IPCOMP_LZS 3 RFC 2395 - IPCOMP_LZJH 4 RFC 3051 - RESERVED TO IANA 5-240 - PRIVATE USE 241-255 - - NAT_DETECTION_SOURCE_IP 16388 - This notification is used by its recipient to determine whether - the source is behind a NAT box. The data associated with this - notification is a SHA-1 digest of the SPIs (in the order they - appear in the header), IP address, and port on which this packet - was sent. There MAY be multiple Notify payloads of this type in a - message if the sender does not know which of several network - attachments will be used to send the packet. The recipient of - this notification MAY compare the supplied value to a SHA-1 hash - of the SPIs, source IP address, and port, and if they don't match - it SHOULD enable NAT traversal (see section 2.23). Alternately, - - - -Hoffman Expires July 5, 2006 [Page 82] - -Internet-Draft IKEv2 January 2006 - - - it MAY reject the connection attempt if NAT traversal is not - supported. - - NAT_DETECTION_DESTINATION_IP 16389 - This notification is used by its recipient to determine whether - it is behind a NAT box. The data associated with this - notification is a SHA-1 digest of the SPIs (in the order they - appear in the header), IP address, and port to which this packet - was sent. The recipient of this notification MAY compare the - supplied value to a hash of the SPIs, destination IP address, and - port, and if they don't match it SHOULD invoke NAT traversal (see - section 2.23). If they don't match, it means that this end is - behind a NAT and this end SHOULD start sending keepalive packets - as defined in [UDPENCAPS]. Alternately, it MAY reject the - connection attempt if NAT traversal is not supported. - - COOKIE 16390 - This notification MAY be included in an IKE_SA_INIT response. It - indicates that the request should be retried with a copy of this - notification as the first payload. This notification MUST be - included in an IKE_SA_INIT request retry if a COOKIE notification - was included in the initial response. The data associated with - this notification MUST be between 1 and 64 octets in length - (inclusive). - - USE_TRANSPORT_MODE 16391 - This notification MAY be included in a request message that also - includes an SA payload requesting a CHILD_SA. It requests that - the CHILD_SA use transport mode rather than tunnel mode for the - SA created. If the request is accepted, the response MUST also - include a notification of type USE_TRANSPORT_MODE. If the - responder declines the request, the CHILD_SA will be established - in tunnel mode. If this is unacceptable to the initiator, the - initiator MUST delete the SA. Note: Except when using this option - to negotiate transport mode, all CHILD_SAs will use tunnel mode. - - Note: The ECN decapsulation modifications specified in - [IPSECARCH] MUST be performed for every tunnel mode SA created - by IKEv2. - - HTTP_CERT_LOOKUP_SUPPORTED 16392 - This notification MAY be included in any message that can include - a CERTREQ payload and indicates that the sender is capable of - looking up certificates based on an HTTP-based URL (and hence - presumably would prefer to receive certificate specifications in - that format). - - REKEY_SA 16393 - - - -Hoffman Expires July 5, 2006 [Page 83] - -Internet-Draft IKEv2 January 2006 - - - This notification MUST be included in a CREATE_CHILD_SA exchange - if the purpose of the exchange is to replace an existing ESP or - AH SA. The SPI field identifies the SA being rekeyed. - {{ Clarif-5.4 }} The SPI placed in the REKEY_SA - notification is the SPI the exchange initiator would expect in - inbound ESP or AH packets. There is no data. - - ESP_TFC_PADDING_NOT_SUPPORTED 16394 - This notification asserts that the sending endpoint will NOT - accept packets that contain Flow Confidentiality (TFC) padding. - {{ Clarif-4.5 }} The scope of this message is a single - CHILD_SA, and thus this notification is included in messages - containing an SA payload negotiating a CHILD_SA. If neither - endpoint accepts TFC padding, this notification SHOULD be - included in both the request proposing an SA and the response - accepting it. If this notification is included in only one of - the messages, TFC padding can still be sent in the other - direction. - - NON_FIRST_FRAGMENTS_ALSO 16395 - Used for fragmentation control. See [IPSECARCH] for explanation. - {{ Clarif-4.6 }} Sending non-first fragments is - enabled only if NON_FIRST_FRAGMENTS_ALSO notification is - included in both the request proposing an SA and the response - accepting it. If the peer rejects this proposal, the peer only - omits NON_FIRST_FRAGMENTS_ALSO notification from the response, - but does not reject the whole CHILD_SA creation. - - RESERVED TO IANA 16396-40959 - - PRIVATE USE 40960-65535 - -3.11. Delete Payload - - The Delete Payload, denoted D in this memo, contains a protocol - specific security association identifier that the sender has removed - from its security association database and is, therefore, no longer - valid. Figure 17 shows the format of the Delete Payload. It is - possible to send multiple SPIs in a Delete payload; however, each SPI - MUST be for the same protocol. Mixing of protocol identifiers MUST - NOT be performed in the Delete payload. It is permitted, however, to - include multiple Delete payloads in a single INFORMATIONAL exchange - where each Delete payload lists SPIs for a different protocol. - - Deletion of the IKE_SA is indicated by a protocol ID of 1 (IKE) but - no SPIs. Deletion of a CHILD_SA, such as ESP or AH, will contain the - IPsec protocol ID of that protocol (2 for AH, 3 for ESP), and the SPI - is the SPI the sending endpoint would expect in inbound ESP or AH - - - -Hoffman Expires July 5, 2006 [Page 84] - -Internet-Draft IKEv2 January 2006 - - - packets. - - The Delete Payload is defined as follows: - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload !C! RESERVED ! Payload Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Protocol ID ! SPI Size ! # of SPIs ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ Security Parameter Index(es) (SPI) ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 17: Delete Payload Format - - o Protocol ID (1 octet) - Must be 1 for an IKE_SA, 2 for AH, or 3 - for ESP. - - o SPI Size (1 octet) - Length in octets of the SPI as defined by the - protocol ID. It MUST be zero for IKE (SPI is in message header) - or four for AH and ESP. - - o # of SPIs (2 octets) - The number of SPIs contained in the Delete - payload. The size of each SPI is defined by the SPI Size field. - - o Security Parameter Index(es) (variable length) - Identifies the - specific security association(s) to delete. The length of this - field is determined by the SPI Size and # of SPIs fields. - - The payload type for the Delete Payload is forty two (42). - -3.12. Vendor ID Payload - - The Vendor ID Payload, denoted V in this memo, contains a vendor - defined constant. The constant is used by vendors to identify and - recognize remote instances of their implementations. This mechanism - allows a vendor to experiment with new features while maintaining - backward compatibility. - - A Vendor ID payload MAY announce that the sender is capable to - accepting certain extensions to the protocol, or it MAY simply - identify the implementation as an aid in debugging. A Vendor ID - payload MUST NOT change the interpretation of any information defined - in this specification (i.e., the critical bit MUST be set to 0). - Multiple Vendor ID payloads MAY be sent. An implementation is NOT - - - -Hoffman Expires July 5, 2006 [Page 85] - -Internet-Draft IKEv2 January 2006 - - - REQUIRED to send any Vendor ID payload at all. - - A Vendor ID payload may be sent as part of any message. Reception of - a familiar Vendor ID payload allows an implementation to make use of - Private USE numbers described throughout this memo-- private - payloads, private exchanges, private notifications, etc. Unfamiliar - Vendor IDs MUST be ignored. - - Writers of Internet-Drafts who wish to extend this protocol MUST - define a Vendor ID payload to announce the ability to implement the - extension in the Internet-Draft. It is expected that Internet-Drafts - that gain acceptance and are standardized will be given "magic - numbers" out of the Future Use range by IANA, and the requirement to - use a Vendor ID will go away. - - The Vendor ID Payload fields are defined as follows: - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload !C! RESERVED ! Payload Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ Vendor ID (VID) ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 18: Vendor ID Payload Format - - o Vendor ID (variable length) - It is the responsibility of the - person choosing the Vendor ID to assure its uniqueness in spite of - the absence of any central registry for IDs. Good practice is to - include a company name, a person name, or some such. If you want - to show off, you might include the latitude and longitude and time - where you were when you chose the ID and some random input. A - message digest of a long unique string is preferable to the long - unique string itself. - - The payload type for the Vendor ID Payload is forty three (43). - -3.13. Traffic Selector Payload - - The Traffic Selector Payload, denoted TS in this memo, allows peers - to identify packet flows for processing by IPsec security services. - The Traffic Selector Payload consists of the IKE generic payload - header followed by individual traffic selectors as follows: - - - - - -Hoffman Expires July 5, 2006 [Page 86] - -Internet-Draft IKEv2 January 2006 - - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload !C! RESERVED ! Payload Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Number of TSs ! RESERVED ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ <Traffic Selectors> ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 19: Traffic Selectors Payload Format - - o Number of TSs (1 octet) - Number of traffic selectors being - provided. - - o RESERVED - This field MUST be sent as zero and MUST be ignored on - receipt. - - o Traffic Selectors (variable length) - One or more individual - traffic selectors. - - The length of the Traffic Selector payload includes the TS header and - all the traffic selectors. - - The payload type for the Traffic Selector payload is forty four (44) - for addresses at the initiator's end of the SA and forty five (45) - for addresses at the responder's end. - - {{ Clarif-4.7 }} There is no requirement that TSi and TSr contain the - same number of individual traffic selectors. Thus, they are - interpreted as follows: a packet matches a given TSi/TSr if it - matches at least one of the individual selectors in TSi, and at least - one of the individual selectors in TSr. - - For instance, the following traffic selectors: - - TSi = ((17, 100, 192.0.1.66-192.0.1.66), - (17, 200, 192.0.1.66-192.0.1.66)) - TSr = ((17, 300, 0.0.0.0-255.255.255.255), - (17, 400, 0.0.0.0-255.255.255.255)) - - would match UDP packets from 192.0.1.66 to anywhere, with any of the - four combinations of source/destination ports (100,300), (100,400), - (200,300), and (200, 400). - - Thus, some types of policies may require several CHILD_SA pairs. For - - - -Hoffman Expires July 5, 2006 [Page 87] - -Internet-Draft IKEv2 January 2006 - - - instance, a policy matching only source/destination ports (100,300) - and (200,400), but not the other two combinations, cannot be - negotiated as a single CHILD_SA pair. - -3.13.1. Traffic Selector - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! TS Type !IP Protocol ID*| Selector Length | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Start Port* | End Port* | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ Starting Address* ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ Ending Address* ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 20: Traffic Selector - - *Note: All fields other than TS Type and Selector Length depend on - the TS Type. The fields shown are for TS Types 7 and 8, the only two - values currently defined. - - o TS Type (one octet) - Specifies the type of traffic selector. - - o IP protocol ID (1 octet) - Value specifying an associated IP - protocol ID (e.g., UDP/TCP/ICMP). A value of zero means that the - protocol ID is not relevant to this traffic selector-- the SA can - carry all protocols. - - o Selector Length - Specifies the length of this Traffic Selector - Substructure including the header. - - o Start Port (2 octets) - Value specifying the smallest port number - allowed by this Traffic Selector. For protocols for which port is - undefined, or if all ports are allowed, this field MUST be zero. - For the ICMP protocol, the two one-octet fields Type and Code are - treated as a single 16-bit integer (with Type in the most - significant eight bits and Code in the least significant eight - bits) port number for the purposes of filtering based on this - field. - - - - - -Hoffman Expires July 5, 2006 [Page 88] - -Internet-Draft IKEv2 January 2006 - - - o End Port (2 octets) - Value specifying the largest port number - allowed by this Traffic Selector. For protocols for which port is - undefined, or if all ports are allowed, this field MUST be 65535. - For the ICMP protocol, the two one-octet fields Type and Code are - treated as a single 16-bit integer (with Type in the most - significant eight bits and Code in the least significant eight - bits) port number for the purposed of filtering based on this - field. - - o Starting Address - The smallest address included in this Traffic - Selector (length determined by TS type). - - o Ending Address - The largest address included in this Traffic - Selector (length determined by TS type). - - Systems that are complying with [IPSECARCH] that wish to indicate - "ANY" ports MUST set the start port to 0 and the end port to 65535; - note that according to [IPSECARCH], "ANY" includes "OPAQUE". Systems - working with [IPSECARCH] that wish to indicate "OPAQUE" ports, but - not "ANY" ports, MUST set the start port to 65535 and the end port to - 0. - - {{ Added from Clarif-4.8 }} The traffic selector types 7 and 8 can - also refer to ICMP type and code fields. Note, however, that ICMP - packets do not have separate source and destination port fields. The - method for specifying the traffic selectors for ICMP is shown by - example in Section 4.4.1.3 of [IPSECARCH]. - - {{ Added from Clarif-4.9 }} Traffic selectors can use IP Protocol ID - 135 to match the IPv6 mobility header [MIPV6]. This document does - not specify how to represent the "MH Type" field in traffic - selectors, although it is likely that a different document will - specify this in the future. Note that [IPSECARCH] says that the IPv6 - mobility header (MH) message type is placed in the most significant - eight bits of the 16-bit local port selector. The direction - semantics of TSi/TSr port fields are the same as for ICMP. - - The following table lists the assigned values for the Traffic - Selector Type field and the corresponding Address Selector Data. - - - - - - - - - - - - -Hoffman Expires July 5, 2006 [Page 89] - -Internet-Draft IKEv2 January 2006 - - - TS Type Value - ------------------------------------------------------------------- - RESERVED 0-6 - - TS_IPV4_ADDR_RANGE 7 - - A range of IPv4 addresses, represented by two four-octet - values. The first value is the beginning IPv4 address - (inclusive) and the second value is the ending IPv4 address - (inclusive). All addresses falling between the two specified - addresses are considered to be within the list. - - TS_IPV6_ADDR_RANGE 8 - - A range of IPv6 addresses, represented by two sixteen-octet - values. The first value is the beginning IPv6 address - (inclusive) and the second value is the ending IPv6 address - (inclusive). All addresses falling between the two specified - addresses are considered to be within the list. - - RESERVED TO IANA 9-240 - PRIVATE USE 241-255 - -3.14. Encrypted Payload - - The Encrypted Payload, denoted SK{...} or E in this memo, contains - other payloads in encrypted form. The Encrypted Payload, if present - in a message, MUST be the last payload in the message. Often, it is - the only payload in the message. - - The algorithms for encryption and integrity protection are negotiated - during IKE_SA setup, and the keys are computed as specified in - Section 2.14 and Section 2.18. - - The encryption and integrity protection algorithms are modeled after - the ESP algorithms described in RFCs 2104 [HMAC], 4303 [ESP], and - 2451 [ESPCBC]. This document completely specifies the cryptographic - processing of IKE data, but those documents should be consulted for - design rationale. We require a block cipher with a fixed block size - and an integrity check algorithm that computes a fixed-length - checksum over a variable size message. - - The payload type for an Encrypted payload is forty six (46). The - Encrypted Payload consists of the IKE generic payload header followed - by individual fields as follows: - - - - - - -Hoffman Expires July 5, 2006 [Page 90] - -Internet-Draft IKEv2 January 2006 - - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload !C! RESERVED ! Payload Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Initialization Vector ! - ! (length is block size for encryption algorithm) ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ~ Encrypted IKE Payloads ~ - + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! Padding (0-255 octets) ! - +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+ - ! ! Pad Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ~ Integrity Checksum Data ~ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 21: Encrypted Payload Format - - o Next Payload - The payload type of the first embedded payload. - Note that this is an exception in the standard header format, - since the Encrypted payload is the last payload in the message and - therefore the Next Payload field would normally be zero. But - because the content of this payload is embedded payloads and there - was no natural place to put the type of the first one, that type - is placed here. - - o Payload Length - Includes the lengths of the header, IV, Encrypted - IKE Payloads, Padding, Pad Length, and Integrity Checksum Data. - - o Initialization Vector - A randomly chosen value whose length is - equal to the block length of the underlying encryption algorithm. - Recipients MUST accept any value. Senders SHOULD either pick this - value pseudo-randomly and independently for each message or use - the final ciphertext block of the previous message sent. Senders - MUST NOT use the same value for each message, use a sequence of - values with low hamming distance (e.g., a sequence number), or use - ciphertext from a received message. - - o IKE Payloads are as specified earlier in this section. This field - is encrypted with the negotiated cipher. - - o Padding MAY contain any value chosen by the sender, and MUST have - a length that makes the combination of the Payloads, the Padding, - and the Pad Length to be a multiple of the encryption block size. - This field is encrypted with the negotiated cipher. - - - - - -Hoffman Expires July 5, 2006 [Page 91] - -Internet-Draft IKEv2 January 2006 - - - o Pad Length is the length of the Padding field. The sender SHOULD - set the Pad Length to the minimum value that makes the combination - of the Payloads, the Padding, and the Pad Length a multiple of the - block size, but the recipient MUST accept any length that results - in proper alignment. This field is encrypted with the negotiated - cipher. - - o Integrity Checksum Data is the cryptographic checksum of the - entire message starting with the Fixed IKE Header through the Pad - Length. The checksum MUST be computed over the encrypted message. - Its length is determined by the integrity algorithm negotiated. - -3.15. Configuration Payload - - The Configuration payload, denoted CP in this document, is used to - exchange configuration information between IKE peers. The exchange - is for an IRAC to request an internal IP address from an IRAS and to - exchange other information of the sort that one would acquire with - Dynamic Host Configuration Protocol (DHCP) if the IRAC were directly - connected to a LAN. - - Configuration payloads are of type CFG_REQUEST/CFG_REPLY or CFG_SET/ - CFG_ACK (see CFG Type in the payload description below). CFG_REQUEST - and CFG_SET payloads may optionally be added to any IKE request. The - IKE response MUST include either a corresponding CFG_REPLY or CFG_ACK - or a Notify payload with an error type indicating why the request - could not be honored. An exception is that a minimal implementation - MAY ignore all CFG_REQUEST and CFG_SET payloads, so a response - message without a corresponding CFG_REPLY or CFG_ACK MUST be accepted - as an indication that the request was not supported. - - "CFG_REQUEST/CFG_REPLY" allows an IKE endpoint to request information - from its peer. If an attribute in the CFG_REQUEST Configuration - Payload is not zero-length, it is taken as a suggestion for that - attribute. The CFG_REPLY Configuration Payload MAY return that - value, or a new one. It MAY also add new attributes and not include - some requested ones. Requestors MUST ignore returned attributes that - they do not recognize. - - Some attributes MAY be multi-valued, in which case multiple attribute - values of the same type are sent and/or returned. Generally, all - values of an attribute are returned when the attribute is requested. - For some attributes (in this version of the specification only - internal addresses), multiple requests indicates a request that - multiple values be assigned. For these attributes, the number of - values returned SHOULD NOT exceed the number requested. - - If the data type requested in a CFG_REQUEST is not recognized or not - - - -Hoffman Expires July 5, 2006 [Page 92] - -Internet-Draft IKEv2 January 2006 - - - supported, the responder MUST NOT return an error type but rather - MUST either send a CFG_REPLY that MAY be empty or a reply not - containing a CFG_REPLY payload at all. Error returns are reserved - for cases where the request is recognized but cannot be performed as - requested or the request is badly formatted. - - "CFG_SET/CFG_ACK" allows an IKE endpoint to push configuration data - to its peer. In this case, the CFG_SET Configuration Payload - contains attributes the initiator wants its peer to alter. The - responder MUST return a Configuration Payload if it accepted any of - the configuration data and it MUST contain the attributes that the - responder accepted with zero-length data. Those attributes that it - did not accept MUST NOT be in the CFG_ACK Configuration Payload. If - no attributes were accepted, the responder MUST return either an - empty CFG_ACK payload or a response message without a CFG_ACK - payload. There are currently no defined uses for the CFG_SET/CFG_ACK - exchange, though they may be used in connection with extensions based - on Vendor IDs. An minimal implementation of this specification MAY - ignore CFG_SET payloads. - - {{ Demoted the SHOULD }} Extensions via the CP payload should not be - used for general purpose management. Its main intent is to provide a - bootstrap mechanism to exchange information within IPsec from IRAS to - IRAC. While it MAY be useful to use such a method to exchange - information between some Security Gateways (SGW) or small networks, - existing management protocols such as DHCP [DHCP], RADIUS [RADIUS], - SNMP, or LDAP [LDAP] should be preferred for enterprise management as - well as subsequent information exchanges. - - The Configuration Payload is defined as follows: - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload !C! RESERVED ! Payload Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! CFG Type ! RESERVED ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ Configuration Attributes ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 22: Configuration Payload Format - - The payload type for the Configuration Payload is forty seven (47). - - - - - -Hoffman Expires July 5, 2006 [Page 93] - -Internet-Draft IKEv2 January 2006 - - - o CFG Type (1 octet) - The type of exchange represented by the - Configuration Attributes. - - CFG Type Value - -------------------------- - RESERVED 0 - CFG_REQUEST 1 - CFG_REPLY 2 - CFG_SET 3 - CFG_ACK 4 - RESERVED TO IANA 5-127 - PRIVATE USE 128-255 - - o RESERVED (3 octets) - MUST be sent as zero; MUST be ignored on - receipt. - - o Configuration Attributes (variable length) - These are type length - values specific to the Configuration Payload and are defined - below. There may be zero or more Configuration Attributes in this - payload. - -3.15.1. Configuration Attributes - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - !R| Attribute Type ! Length | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | | - ~ Value ~ - | | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 23: Configuration Attribute Format - - o Reserved (1 bit) - This bit MUST be set to zero and MUST be - ignored on receipt. - - o Attribute Type (15 bits) - A unique identifier for each of the - Configuration Attribute Types. - - o Length (2 octets) - Length in octets of Value. - - o Value (0 or more octets) - The variable-length value of this - Configuration Attribute. The following attribute types have been - defined: - - - - - -Hoffman Expires July 5, 2006 [Page 94] - -Internet-Draft IKEv2 January 2006 - - - Multi- - Attribute Type Value Valued Length - ------------------------------------------------------- - RESERVED 0 - INTERNAL_IP4_ADDRESS 1 YES* 0 or 4 octets - INTERNAL_IP4_NETMASK 2 NO 0 or 4 octets - INTERNAL_IP4_DNS 3 YES 0 or 4 octets - INTERNAL_IP4_NBNS 4 YES 0 or 4 octets - INTERNAL_ADDRESS_EXPIRY 5 NO 0 or 4 octets - INTERNAL_IP4_DHCP 6 YES 0 or 4 octets - APPLICATION_VERSION 7 NO 0 or more - INTERNAL_IP6_ADDRESS 8 YES* 0 or 17 octets - RESERVED 9 - INTERNAL_IP6_DNS 10 YES 0 or 16 octets - INTERNAL_IP6_NBNS 11 YES 0 or 16 octets - INTERNAL_IP6_DHCP 12 YES 0 or 16 octets - INTERNAL_IP4_SUBNET 13 YES 0 or 8 octets - SUPPORTED_ATTRIBUTES 14 NO Multiple of 2 - INTERNAL_IP6_SUBNET 15 YES 17 octets - RESERVED TO IANA 16-16383 - PRIVATE USE 16384-32767 - - * These attributes may be multi-valued on return only if - multiple values were requested. - - o INTERNAL_IP4_ADDRESS, INTERNAL_IP6_ADDRESS - An address on the - internal network, sometimes called a red node address or private - address and MAY be a private address on the Internet. {{ - Clarif-6.3}} In a request message, the address specified is a - requested address (or a zero-length address if no specific address - is requested). If a specific address is requested, it likely - indicates that a previous connection existed with this address and - the requestor would like to reuse that address. With IPv6, a - requestor MAY supply the low-order address bytes it wants to use. - Multiple internal addresses MAY be requested by requesting - multiple internal address attributes. The responder MAY only send - up to the number of addresses requested. The INTERNAL_IP6_ADDRESS - is made up of two fields: the first is a 16-octet IPv6 address, - and the second is a one-octet prefix-length as defined in - [ADDRIPV6]. - - The requested address is valid until the expiry time defined with - the INTERNAL_ADDRESS_EXPIRY attribute or there are no IKE_SAs - between the peers. - - o INTERNAL_IP4_NETMASK - The internal network's netmask. Only one - netmask is allowed in the request and reply messages (e.g., - 255.255.255.0), and it MUST be used only with an - - - -Hoffman Expires July 5, 2006 [Page 95] - -Internet-Draft IKEv2 January 2006 - - - INTERNAL_IP4_ADDRESS attribute. {{ Clarif-6.5 }} - INTERNAL_IP4_NETMASK in a CFG_REPLY means roughly the same thing - as INTERNAL_IP4_SUBNET containing the same information ("send - traffic to these addresses through me"), but also implies a link - boundary. For instance, the client could use its own address and - the netmask to calculate the broadcast address of the link. An - empty INTERNAL_IP4_NETMASK attribute can be included in a - CFG_REQUEST to request this information (although the gateway can - send the information even when not requested). Non-empty values - for this attribute in a CFG_REQUEST do not make sense and thus - MUST NOT be included. - - o INTERNAL_IP4_DNS, INTERNAL_IP6_DNS - Specifies an address of a DNS - server within the network. Multiple DNS servers MAY be requested. - The responder MAY respond with zero or more DNS server attributes. - - o INTERNAL_IP4_NBNS, INTERNAL_IP6_NBNS - Specifies an address of a - NetBios Name Server (WINS) within the network. Multiple NBNS - servers MAY be requested. The responder MAY respond with zero or - more NBNS server attributes. {{ Clarif-6.7 }} NetBIOS is not - defined for IPv6; therefore, INTERNAL_IP6_NBNS SHOULD NOT be used. - - o INTERNAL_ADDRESS_EXPIRY - Specifies the number of seconds that the - host can use the internal IP address. The host MUST renew the IP - address before this expiry time. Only one of these attributes MAY - be present in the reply. {{ Clarif-6.8 }} Expiry times and - explicit renewals are primarily useful in environments like DHCP, - where the server cannot reliably know when the client has gone - away. However, in IKEv2, this is known, and the gateway can - simply free the address when the IKE_SA is deleted. Further, - supporting renewals is not mandatory. Thus - INTERNAL_ADDRESS_EXPIRY attribute MUST NOT be used. - - o INTERNAL_IP4_DHCP, INTERNAL_IP6_DHCP - Instructs the host to send - any internal DHCP requests to the address contained within the - attribute. Multiple DHCP servers MAY be requested. The responder - MAY respond with zero or more DHCP server attributes. - - o APPLICATION_VERSION - The version or application information of - the IPsec host. This is a string of printable ASCII characters - that is NOT null terminated. - - o INTERNAL_IP4_SUBNET - The protected sub-networks that this edge- - device protects. This attribute is made up of two fields: the - first being an IP address and the second being a netmask. - Multiple sub-networks MAY be requested. The responder MAY respond - with zero or more sub-network attributes. - - - - -Hoffman Expires July 5, 2006 [Page 96] - -Internet-Draft IKEv2 January 2006 - - - o SUPPORTED_ATTRIBUTES - When used within a Request, this attribute - MUST be zero-length and specifies a query to the responder to - reply back with all of the attributes that it supports. The - response contains an attribute that contains a set of attribute - identifiers each in 2 octets. The length divided by 2 (octets) - would state the number of supported attributes contained in the - response. - - o INTERNAL_IP6_SUBNET - The protected sub-networks that this edge- - device protects. This attribute is made up of two fields: the - first is a 16-octet IPv6 address, and the second is a one-octet - prefix-length as defined in [ADDRIPV6]. Multiple sub-networks MAY - be requested. The responder MAY respond with zero or more sub- - network attributes. - - Note that no recommendations are made in this document as to how an - implementation actually figures out what information to send in a - reply. That is, we do not recommend any specific method of an IRAS - determining which DNS server should be returned to a requesting IRAC. - -3.15.2. Meaning of INTERNAL_IP4_SUBNET/INTERNAL_IP6_SUBNET - - {{ Section added based on Clarif-6.4 }} - - INTERNAL_IP4/6_SUBNET attributes can indicate additional subnets, - ones that need one or more separate SAs, that can be reached through - the gateway that announces the attributes. INTERNAL_IP4/6_SUBNET - attributes may also express the gateway's policy about what traffic - should be sent through the gateway; the client can choose whether - other traffic (covered by TSr, but not in INTERNAL_IP4/6_SUBNET) is - sent through the gateway or directly to the destination. Thus, - traffic to the addresses listed in the INTERNAL_IP4/6_SUBNET - attributes should be sent through the gateway that announces the - attributes. If there are no existing IPsec SAs whose traffic - selectors cover the address in question, new SAs need to be created. - - For instance, if there are two subnets, 192.0.1.0/26 and - 192.0.2.0/24, and the client's request contains the following: - - CP(CFG_REQUEST) = - INTERNAL_IP4_ADDRESS() - TSi = (0, 0-65535, 0.0.0.0-255.255.255.255) - TSr = (0, 0-65535, 0.0.0.0-255.255.255.255) - - then a valid response could be the following (in which TSr and - INTERNAL_IP4_SUBNET contain the same information): - - - - - -Hoffman Expires July 5, 2006 [Page 97] - -Internet-Draft IKEv2 January 2006 - - - CP(CFG_REPLY) = - INTERNAL_IP4_ADDRESS(192.0.1.234) - INTERNAL_IP4_SUBNET(192.0.1.0/255.255.255.192) - INTERNAL_IP4_SUBNET(192.0.2.0/255.255.255.0) - TSi = (0, 0-65535, 192.0.1.234-192.0.1.234) - TSr = ((0, 0-65535, 192.0.1.0-192.0.1.63), - (0, 0-65535, 192.0.2.0-192.0.2.255)) - - In these cases, the INTERNAL_IP4_SUBNET does not really carry any - useful information. - - A different possible reply would have been this: - - CP(CFG_REPLY) = - INTERNAL_IP4_ADDRESS(192.0.1.234) - INTERNAL_IP4_SUBNET(192.0.1.0/255.255.255.192) - INTERNAL_IP4_SUBNET(192.0.2.0/255.255.255.0) - TSi = (0, 0-65535, 192.0.1.234-192.0.1.234) - TSr = (0, 0-65535, 0.0.0.0-255.255.255.255) - - That reply would mean that the client can send all its traffic - through the gateway, but the gateway does not mind if the client - sends traffic not included by INTERNAL_IP4_SUBNET directly to the - destination (without going through the gateway). - - A different situation arises if the gateway has a policy that - requires the traffic for the two subnets to be carried in separate - SAs. Then a response like this would indicate to the client that if - it wants access to the second subnet, it needs to create a separate - SA: - - CP(CFG_REPLY) = - INTERNAL_IP4_ADDRESS(192.0.1.234) - INTERNAL_IP4_SUBNET(192.0.1.0/255.255.255.192) - INTERNAL_IP4_SUBNET(192.0.2.0/255.255.255.0) - TSi = (0, 0-65535, 192.0.1.234-192.0.1.234) - TSr = (0, 0-65535, 192.0.1.0-192.0.1.63) - - INTERNAL_IP4_SUBNET can also be useful if the client's TSr included - only part of the address space. For instance, if the client requests - the following: - - CP(CFG_REQUEST) = - INTERNAL_IP4_ADDRESS() - TSi = (0, 0-65535, 0.0.0.0-255.255.255.255) - TSr = (0, 0-65535, 192.0.2.155-192.0.2.155) - - then the gateway's reply might be: - - - -Hoffman Expires July 5, 2006 [Page 98] - -Internet-Draft IKEv2 January 2006 - - - CP(CFG_REPLY) = - INTERNAL_IP4_ADDRESS(192.0.1.234) - INTERNAL_IP4_SUBNET(192.0.1.0/255.255.255.192) - INTERNAL_IP4_SUBNET(192.0.2.0/255.255.255.0) - TSi = (0, 0-65535, 192.0.1.234-192.0.1.234) - TSr = (0, 0-65535, 192.0.2.155-192.0.2.155) - - Because the meaning of INTERNAL_IP4_SUBNET/INTERNAL_IP6_SUBNET is in - CFG_REQUESTs is unclear, they MUST NOT be used in CFG_REQUESTs. - -3.15.3. Configuration payloads for IPv6 - - {{ Added this section from Clarif-6.6 }} - - The configuration payloads for IPv6 are based on the corresponding - IPv4 payloads, and do not fully follow the "normal IPv6 way of doing - things". In particular, IPv6 stateless autoconfiguration or router - advertisement messages are not used; neither is neighbor discovery. - - A client can be assigned an IPv6 address using the - INTERNAL_IP6_ADDRESS configuration payload. A minimal exchange might - look like this: - - CP(CFG_REQUEST) = - INTERNAL_IP6_ADDRESS() - INTERNAL_IP6_DNS() - TSi = (0, 0-65535, :: - FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF) - TSr = (0, 0-65535, :: - FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF) - - CP(CFG_REPLY) = - INTERNAL_IP6_ADDRESS(2001:DB8:0:1:2:3:4:5/64) - INTERNAL_IP6_DNS(2001:DB8:99:88:77:66:55:44) - TSi = (0, 0-65535, 2001:DB8:0:1:2:3:4:5 - 2001:DB8:0:1:2:3:4:5) - TSr = (0, 0-65535, :: - FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF) - - The client MAY send a non-empty INTERNAL_IP6_ADDRESS attribute in the - CFG_REQUEST to request a specific address or interface identifier. - The gateway first checks if the specified address is acceptable, and - if it is, returns that one. If the address was not acceptable, the - gateway attempts to use the interface identifier with some other - prefix; if even that fails, the gateway selects another interface - identifier. - - The INTERNAL_IP6_ADDRESS attribute also contains a prefix length - field. When used in a CFG_REPLY, this corresponds to the - INTERNAL_IP4_NETMASK attribute in the IPv4 case. - - Although this approach to configuring IPv6 addresses is reasonably - - - -Hoffman Expires July 5, 2006 [Page 99] - -Internet-Draft IKEv2 January 2006 - - - simple, it has some limitations. IPsec tunnels configured using - IKEv2 are not fully-featured "interfaces" in the IPv6 addressing - architecture sense [IPV6ADDR]. In particular, they do not - necessarily have link-local addresses, and this may complicate the - use of protocols that assume them, such as [MLDV2]. - -3.15.4. Address Assignment Failures - - {{ Added this section from Clarif-6.9 }} - - If the responder encounters an error while attempting to assign an IP - address to the initiator, it responds with an - INTERNAL_ADDRESS_FAILURE notification. However, there are some more - complex error cases. - - If the responder does not support configuration payloads at all, it - can simply ignore all configuration payloads. This type of - implementation never sends INTERNAL_ADDRESS_FAILURE notifications. - If the initiator requires the assignment of an IP address, it will - treat a response without CFG_REPLY as an error. - - The initiator may request a particular type of address (IPv4 or IPv6) - that the responder does not support, even though the responder - supports configuration payloads. In this case, the responder simply - ignores the type of address it does not support and processes the - rest of the request as usual. - - If the initiator requests multiple addresses of a type that the - responder supports, and some (but not all) of the requests fail, the - responder replies with the successful addresses only. The responder - sends INTERNAL_ADDRESS_FAILURE only if no addresses can be assigned. - -3.16. Extensible Authentication Protocol (EAP) Payload - - The Extensible Authentication Protocol Payload, denoted EAP in this - memo, allows IKE_SAs to be authenticated using the protocol defined - in RFC 3748 [EAP] and subsequent extensions to that protocol. The - full set of acceptable values for the payload is defined elsewhere, - but a short summary of RFC 3748 is included here to make this - document stand alone in the common cases. - - - - - - - - - - - -Hoffman Expires July 5, 2006 [Page 100] - -Internet-Draft IKEv2 January 2006 - - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload !C! RESERVED ! Payload Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ EAP Message ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 24: EAP Payload Format - - The payload type for an EAP Payload is forty eight (48). - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Code ! Identifier ! Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Type ! Type_Data... - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+- - - Figure 25: EAP Message Format - - o Code (1 octet) indicates whether this message is a Request (1), - Response (2), Success (3), or Failure (4). - - o Identifier (1 octet) is used in PPP to distinguish replayed - messages from repeated ones. Since in IKE, EAP runs over a - reliable protocol, it serves no function here. In a response - message, this octet MUST be set to match the identifier in the - corresponding request. In other messages, this field MAY be set - to any value. - - o Length (2 octets) is the length of the EAP message and MUST be - four less than the Payload Length of the encapsulating payload. - - o Type (1 octet) is present only if the Code field is Request (1) or - Response (2). For other codes, the EAP message length MUST be - four octets and the Type and Type_Data fields MUST NOT be present. - In a Request (1) message, Type indicates the data being requested. - In a Response (2) message, Type MUST either be Nak or match the - type of the data requested. The following types are defined in - RFC 3748: - - - - - - - -Hoffman Expires July 5, 2006 [Page 101] - -Internet-Draft IKEv2 January 2006 - - - 1 Identity - 2 Notification - 3 Nak (Response Only) - 4 MD5-Challenge - 5 One-Time Password (OTP) - 6 Generic Token Card - - o Type_Data (Variable Length) varies with the Type of Request and - the associated Response. For the documentation of the EAP - methods, see [EAP]. - - {{ Demoted the SHOULD NOT and SHOULD }} Note that since IKE passes an - indication of initiator identity in message 3 of the protocol, the - responder should not send EAP Identity requests. The initiator may, - however, respond to such requests if it receives them. - - -4. Conformance Requirements - - In order to assure that all implementations of IKEv2 can - interoperate, there are "MUST support" requirements in addition to - those listed elsewhere. Of course, IKEv2 is a security protocol, and - one of its major functions is to allow only authorized parties to - successfully complete establishment of SAs. So a particular - implementation may be configured with any of a number of restrictions - concerning algorithms and trusted authorities that will prevent - universal interoperability. - - IKEv2 is designed to permit minimal implementations that can - interoperate with all compliant implementations. There are a series - of optional features that can easily be ignored by a particular - implementation if it does not support that feature. Those features - include: - - o Ability to negotiate SAs through a NAT and tunnel the resulting - ESP SA over UDP. - - o Ability to request (and respond to a request for) a temporary IP - address on the remote end of a tunnel. - - o Ability to support various types of legacy authentication. - - o Ability to support window sizes greater than one. - - o Ability to establish multiple ESP and/or AH SAs within a single - IKE_SA. - - - - - -Hoffman Expires July 5, 2006 [Page 102] - -Internet-Draft IKEv2 January 2006 - - - o Ability to rekey SAs. - - To assure interoperability, all implementations MUST be capable of - parsing all payload types (if only to skip over them) and to ignore - payload types that it does not support unless the critical bit is set - in the payload header. If the critical bit is set in an unsupported - payload header, all implementations MUST reject the messages - containing those payloads. - - Every implementation MUST be capable of doing four-message - IKE_SA_INIT and IKE_AUTH exchanges establishing two SAs (one for IKE, - one for ESP and/or AH). Implementations MAY be initiate-only or - respond-only if appropriate for their platform. Every implementation - MUST be capable of responding to an INFORMATIONAL exchange, but a - minimal implementation MAY respond to any INFORMATIONAL message with - an empty INFORMATIONAL reply (note that within the context of an - IKE_SA, an "empty" message consists of an IKE header followed by an - Encrypted payload with no payloads contained in it). A minimal - implementation MAY support the CREATE_CHILD_SA exchange only in so - far as to recognize requests and reject them with a Notify payload of - type NO_ADDITIONAL_SAS. A minimal implementation need not be able to - initiate CREATE_CHILD_SA or INFORMATIONAL exchanges. When an SA - expires (based on locally configured values of either lifetime or - octets passed), and implementation MAY either try to renew it with a - CREATE_CHILD_SA exchange or it MAY delete (close) the old SA and - create a new one. If the responder rejects the CREATE_CHILD_SA - request with a NO_ADDITIONAL_SAS notification, the implementation - MUST be capable of instead deleting the old SA and creating a new - one. - - Implementations are not required to support requesting temporary IP - addresses or responding to such requests. If an implementation does - support issuing such requests, it MUST include a CP payload in - message 3 containing at least a field of type INTERNAL_IP4_ADDRESS or - INTERNAL_IP6_ADDRESS. All other fields are optional. If an - implementation supports responding to such requests, it MUST parse - the CP payload of type CFG_REQUEST in message 3 and recognize a field - of type INTERNAL_IP4_ADDRESS or INTERNAL_IP6_ADDRESS. If it supports - leasing an address of the appropriate type, it MUST return a CP - payload of type CFG_REPLY containing an address of the requested - type. {{ Demoted the SHOULD }} The responder may include any other - related attributes. - - A minimal IPv4 responder implementation will ignore the contents of - the CP payload except to determine that it includes an - INTERNAL_IP4_ADDRESS attribute and will respond with the address and - other related attributes regardless of whether the initiator - requested them. - - - -Hoffman Expires July 5, 2006 [Page 103] - -Internet-Draft IKEv2 January 2006 - - - A minimal IPv4 initiator will generate a CP payload containing only - an INTERNAL_IP4_ADDRESS attribute and will parse the response - ignoring attributes it does not know how to use. {{ Clarif-6.8 - removes the sentence about processing INTERNAL_ADDRESS_EXPIRY. }} - Minimal initiators need not be able to request lease renewals and - minimal responders need not respond to them. - - For an implementation to be called conforming to this specification, - it MUST be possible to configure it to accept the following: - - o PKIX Certificates containing and signed by RSA keys of size 1024 - or 2048 bits, where the ID passed is any of ID_KEY_ID, ID_FQDN, - ID_RFC822_ADDR, or ID_DER_ASN1_DN. - - o Shared key authentication where the ID passes is any of ID_KEY_ID, - ID_FQDN, or ID_RFC822_ADDR. - - o Authentication where the responder is authenticated using PKIX - Certificates and the initiator is authenticated using shared key - authentication. - - -5. Security Considerations - - While this protocol is designed to minimize disclosure of - configuration information to unauthenticated peers, some such - disclosure is unavoidable. One peer or the other must identify - itself first and prove its identity first. To avoid probing, the - initiator of an exchange is required to identify itself first, and - usually is required to authenticate itself first. The initiator can, - however, learn that the responder supports IKE and what cryptographic - protocols it supports. The responder (or someone impersonating the - responder) can probe the initiator not only for its identity, but - using CERTREQ payloads may be able to determine what certificates the - initiator is willing to use. - - Use of EAP authentication changes the probing possibilities somewhat. - When EAP authentication is used, the responder proves its identity - before the initiator does, so an initiator that knew the name of a - valid initiator could probe the responder for both its name and - certificates. - - Repeated rekeying using CREATE_CHILD_SA without additional Diffie- - Hellman exchanges leaves all SAs vulnerable to cryptanalysis of a - single key or overrun of either endpoint. Implementers should take - note of this fact and set a limit on CREATE_CHILD_SA exchanges - between exponentiations. This memo does not prescribe such a limit. - - - - -Hoffman Expires July 5, 2006 [Page 104] - -Internet-Draft IKEv2 January 2006 - - - The strength of a key derived from a Diffie-Hellman exchange using - any of the groups defined here depends on the inherent strength of - the group, the size of the exponent used, and the entropy provided by - the random number generator used. Due to these inputs, it is - difficult to determine the strength of a key for any of the defined - groups. Diffie-Hellman group number two, when used with a strong - random number generator and an exponent no less than 200 bits, is - common for use with 3DES. Group five provides greater security than - group two. Group one is for historic purposes only and does not - provide sufficient strength except for use with DES, which is also - for historic use only. Implementations should make note of these - estimates when establishing policy and negotiating security - parameters. - - Note that these limitations are on the Diffie-Hellman groups - themselves. There is nothing in IKE that prohibits using stronger - groups nor is there anything that will dilute the strength obtained - from stronger groups (limited by the strength of the other algorithms - negotiated including the prf function). In fact, the extensible - framework of IKE encourages the definition of more groups; use of - elliptical curve groups may greatly increase strength using much - smaller numbers. - - It is assumed that all Diffie-Hellman exponents are erased from - memory after use. In particular, these exponents MUST NOT be derived - from long-lived secrets like the seed to a pseudo-random generator - that is not erased after use. - - The strength of all keys is limited by the size of the output of the - negotiated prf function. For this reason, a prf function whose - output is less than 128 bits (e.g., 3DES-CBC) MUST NOT be used with - this protocol. - - The security of this protocol is critically dependent on the - randomness of the randomly chosen parameters. These should be - generated by a strong random or properly seeded pseudo-random source - (see [RANDOMNESS]). Implementers should take care to ensure that use - of random numbers for both keys and nonces is engineered in a fashion - that does not undermine the security of the keys. - - For information on the rationale of many of the cryptographic design - choices in this protocol, see [SIGMA] and [SKEME]. Though the - security of negotiated CHILD_SAs does not depend on the strength of - the encryption and integrity protection negotiated in the IKE_SA, - implementations MUST NOT negotiate NONE as the IKE integrity - protection algorithm or ENCR_NULL as the IKE encryption algorithm. - - When using pre-shared keys, a critical consideration is how to assure - - - -Hoffman Expires July 5, 2006 [Page 105] - -Internet-Draft IKEv2 January 2006 - - - the randomness of these secrets. The strongest practice is to ensure - that any pre-shared key contain as much randomness as the strongest - key being negotiated. Deriving a shared secret from a password, - name, or other low-entropy source is not secure. These sources are - subject to dictionary and social engineering attacks, among others. - - The NAT_DETECTION_*_IP notifications contain a hash of the addresses - and ports in an attempt to hide internal IP addresses behind a NAT. - Since the IPv4 address space is only 32 bits, and it is usually very - sparse, it would be possible for an attacker to find out the internal - address used behind the NAT box by trying all possible IP addresses - and trying to find the matching hash. The port numbers are normally - fixed to 500, and the SPIs can be extracted from the packet. This - reduces the number of hash calculations to 2^32. With an educated - guess of the use of private address space, the number of hash - calculations is much smaller. Designers should therefore not assume - that use of IKE will not leak internal address information. - - When using an EAP authentication method that does not generate a - shared key for protecting a subsequent AUTH payload, certain man-in- - the-middle and server impersonation attacks are possible [EAPMITM]. - These vulnerabilities occur when EAP is also used in protocols that - are not protected with a secure tunnel. Since EAP is a general- - purpose authentication protocol, which is often used to provide - single-signon facilities, a deployed IPsec solution that relies on an - EAP authentication method that does not generate a shared key (also - known as a non-key-generating EAP method) can become compromised due - to the deployment of an entirely unrelated application that also - happens to use the same non-key-generating EAP method, but in an - unprotected fashion. Note that this vulnerability is not limited to - just EAP, but can occur in other scenarios where an authentication - infrastructure is reused. For example, if the EAP mechanism used by - IKEv2 utilizes a token authenticator, a man-in-the-middle attacker - could impersonate the web server, intercept the token authentication - exchange, and use it to initiate an IKEv2 connection. For this - reason, use of non-key-generating EAP methods SHOULD be avoided where - possible. Where they are used, it is extremely important that all - usages of these EAP methods SHOULD utilize a protected tunnel, where - the initiator validates the responder's certificate before initiating - the EAP exchange. {{ Demoted the SHOULD }} Implementers should - describe the vulnerabilities of using non-key-generating EAP methods - in the documentation of their implementations so that the - administrators deploying IPsec solutions are aware of these dangers. - - An implementation using EAP MUST also use a public-key-based - authentication of the server to the client before the EAP exchange - begins, even if the EAP method offers mutual authentication. This - avoids having additional IKEv2 protocol variations and protects the - - - -Hoffman Expires July 5, 2006 [Page 106] - -Internet-Draft IKEv2 January 2006 - - - EAP data from active attackers. - - If the messages of IKEv2 are long enough that IP-level fragmentation - is necessary, it is possible that attackers could prevent the - exchange from completing by exhausting the reassembly buffers. The - chances of this can be minimized by using the Hash and URL encodings - instead of sending certificates (see Section 3.6). Additional - mitigations are discussed in [DOSUDPPROT]. - - -6. IANA Considerations - - {{ This section was changed to not re-define any new IANA registries. - }} - - [IKEV2] defined many field types and values. IANA has already - registered those types and values, so the are not listed here again. - No new types or values are registered in IKEv2.1. - - -7. Acknowledgements - - {{ Added new acknowledgements. }} - - Charlie Kaufman did a huge amount of work on the original IKEv2 - document, on which this document is primarily based. Pasi Eronen - worked hard on the clarifications document, which is the basis for - the differences between IKEv2 and IKEv2.1. The individuals on the - IPsec mailing list was very helpful in both pointing out where - clarifications and changes were needed, as well as in reviewing the - clarifications suggested by others. - - The acknowledgements from the IKEv2 document were: - - This document is a collaborative effort of the entire IPsec WG. If - there were no limit to the number of authors that could appear on an - RFC, the following, in alphabetical order, would have been listed: - Bill Aiello, Stephane Beaulieu, Steve Bellovin, Sara Bitan, Matt - Blaze, Ran Canetti, Darren Dukes, Dan Harkins, Paul Hoffman, John - Ioannidis, Charlie Kaufman, Steve Kent, Angelos Keromytis, Tero - Kivinen, Hugo Krawczyk, Andrew Krywaniuk, Radia Perlman, Omer - Reingold, and Michael Richardson. Many other people contributed to - the design. It is an evolution of IKEv1, ISAKMP, and the IPsec DOI, - each of which has its own list of authors. Hugh Daniel suggested the - feature of having the initiator, in message 3, specify a name for the - responder, and gave the feature the cute name "You Tarzan, Me Jane". - David Faucher and Valery Smyzlov helped refine the design of the - traffic selector negotiation. - - - -Hoffman Expires July 5, 2006 [Page 107] - -Internet-Draft IKEv2 January 2006 - - - This paragraph lists references that appear only in figures. The - section is only here to keep the 'xml2rfc' program happy, and will be - removed when the document is published. Feel free to ignore it. - [DES] [IDEA] [MD5] [X.501] [X.509] - - -8. References - -8.1. Normative References - - [ADDGROUP] - Kivinen, T. and M. Kojo, "More Modular Exponential (MODP) - Diffie-Hellman groups for Internet Key Exchange (IKE)", - RFC 3526, May 2003. - - [ADDRIPV6] - Hinden, R. and S. Deering, "Internet Protocol Version 6 - (IPv6) Addressing Architecture", RFC 3513, April 2003. - - [Clarif] "IKEv2 Clarifications and Implementation Guidelines", - draft-eronen-ipsec-ikev2-clarifications (work in - progress). - - [EAP] Aboba, B., Blunk, L., Vollbrecht, J., Carlson, J., and H. - Levkowetz, "Extensible Authentication Protocol (EAP)", - RFC 3748, June 2004. - - [ECN] Ramakrishnan, K., Floyd, S., and D. Black, "The Addition - of Explicit Congestion Notification (ECN) to IP", - RFC 3168, September 2001. - - [ESPCBC] Pereira, R. and R. Adams, "The ESP CBC-Mode Cipher - Algorithms", RFC 2451, November 1998. - - [IANACONS] - Narten, T. and H. Alvestrand, "Guidelines for Writing an - IANA Considerations Section in RFCs", BCP 26, RFC 2434. - - [IKEV2] Kaufman, C., "Internet Key Exchange (IKEv2) Protocol", - RFC 4306, December 2005. - - [IPSECARCH] - Kent, S. and K. Seo, "Security Architecture for the - Internet Protocol", RFC 4301, December 2005. - - [MUSTSHOULD] - Bradner, S., "Key Words for use in RFCs to indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. - - - -Hoffman Expires July 5, 2006 [Page 108] - -Internet-Draft IKEv2 January 2006 - - - [PKIX] Housley, R., Polk, W., Ford, W., and D. Solo, "Internet - X.509 Public Key Infrastructure Certificate and - Certificate Revocation List (CRL) Profile", RFC 3280, - April 2002. - - [UDPENCAPS] - Huttunen, A., Swander, B., Volpe, V., DiBurro, L., and M. - Stenberg, "UDP Encapsulation of IPsec ESP Packets", - RFC 3948, January 2005. - -8.2. Informative References - - [AH] Kent, S., "IP Authentication Header", RFC 4302, - December 2005. - - [ARCHGUIDEPHIL] - Bush, R. and D. Meyer, "Some Internet Architectural - Guidelines and Philosophy", RFC 3439, December 2002. - - [ARCHPRINC] - Carpenter, B., "Architectural Principles of the Internet", - RFC 1958, June 1996. - - [DES] American National Standards Institute, "American National - Standard for Information Systems-Data Link Encryption", - ANSI X3.106, 1983. - - [DH] Diffie, W. and M. Hellman, "New Directions in - Cryptography", IEEE Transactions on Information Theory, - V.IT-22 n. 6, June 1977. - - [DHCP] Droms, R., "Dynamic Host Configuration Protocol", - RFC 2131, March 1997. - - [DIFFSERVARCH] - Blake, S., Black, D., Carlson, M., Davies, E., Wang, Z., - and W. Weiss, "An Architecture for Differentiated - Services", RFC 2475. - - [DIFFSERVFIELD] - Nichols, K., Blake, S., Baker, F., and D. Black, - "Definition of the Differentiated Services Field (DS - Field) in the IPv4 and IPv6 Headers", RFC 2474, - December 1998. - - [DIFFTUNNEL] - Black, D., "Differentiated Services and Tunnels", - RFC 2983, October 2000. - - - -Hoffman Expires July 5, 2006 [Page 109] - -Internet-Draft IKEv2 January 2006 - - - [DOI] Piper, D., "The Internet IP Security Domain of - Interpretation for ISAKMP", RFC 2407, November 1998. - - [DOSUDPPROT] - C. Kaufman, R. Perlman, and B. Sommerfeld, "DoS protection - for UDP-based protocols", ACM Conference on Computer and - Communications Security , October 2003. - - [DSS] National Institute of Standards and Technology, U.S. - Department of Commerce, "Digital Signature Standard", - FIPS 186, May 1994. - - [EAPMITM] N. Asokan, V. Nierni, and K. Nyberg, "Man-in-the-Middle in - Tunneled Authentication Protocols", November 2002, - <http://eprint.iacr.org/2002/163>. - - [ESP] Kent, S., "IP Encapsulating Security Payload (ESP)", - RFC 4303, December 2005. - - [EXCHANGEANALYSIS] - R. Perlman and C. Kaufman, "Analysis of the IPsec key - exchange Standard", WET-ICE Security Conference, MIT , - 2001, - <http://sec.femto.org/wetice-2001/papers/radia-paper.pdf>. - - [HMAC] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- - Hashing for Message Authentication", RFC 2104, - February 1997. - - [IDEA] X. Lai, "On the Design and Security of Block Ciphers", ETH - Series in Information Processing, v. 1, Konstanz: Hartung- - Gorre Verlag, 1992. - - [IKEV1] Harkins, D. and D. Carrel, "The Internet Key Exchange - (IKE)", RFC 2409, November 1998. - - [IPCOMP] Shacham, A., Monsour, B., Pereira, R., and M. Thomas, "IP - Payload Compression Protocol (IPComp)", RFC 3173, - September 2001. - - [IPSECARCH-OLD] - Kent, S. and R. Atkinson, "Security Architecture for the - Internet Protocol", RFC 2401, November 1998. - - [IPV6ADDR] - Hinden, R. and S. Deering, "Internet Protocol Version 6 - (IPv6) Addressing Architecture", RFC 3513, April 2003. - - - - -Hoffman Expires July 5, 2006 [Page 110] - -Internet-Draft IKEv2 January 2006 - - - [ISAKMP] Maughan, D., Schneider, M., and M. Schertler, "Internet - Security Association and Key Management Protocol - (ISAKMP)", RFC 2408, November 1998. - - [LDAP] Wahl, M., Howes, T., and S. Kille, "Lightweight Directory - Access Protocol (v3)", RFC 2251, December 1997. - - [MAILFORMAT] - Resnick, P., "Internet Message Format", RFC 2822, - April 2001. - - [MD5] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, - April 1992. - - [MIPV6] Johnson, D., Perkins, C., and J. Arkko, "Mobility Support - in IPv6", RFC 3775, June 2004. - - [MLDV2] Vida, R. and L. Costa, "Multicast Listener Discovery - Version 2 (MLDv2) for IPv6", RFC 3810, June 2004. - - [NAI] Aboba, B. and M. Beadles, "The Network Access Identifier", - RFC 2486, January 1999. - - [NATREQ] Aboba, B. and W. Dixon, "IPsec-Network Address Translation - (NAT) Compatibility Requirements", RFC 3715, March 2004. - - [OAKLEY] Orman, H., "The OAKLEY Key Determination Protocol", - RFC 2412, November 1998. - - [PFKEY] McDonald, D., Metz, C., and B. Phan, "PF_KEY Key - Management API, Version 2", RFC 2367, July 1998. - - [PHOTURIS] - Karn, P. and W. Simpson, "Photuris: Session-Key Management - Protocol", RFC 2522, March 1999. - - [PKCS1] B. Kaliski and J. Staddon, "PKCS #1: RSA Cryptography - Specifications Version 2", September 1998. - - [PRFAES128CBC] - Hoffman, P., "The AES-XCBC-PRF-128 Algorithm for the - Internet Key Exchange Protocol (IKE)", RFC 3664, - January 2004. - - [PRFAES128CBC-bis] - Hoffman, P., "The AES-XCBC-PRF-128 Algorithm for the - Internet Key Exchange Protocol (IKE)", - draft-hoffman-rfc3664bis (work in progress), October 2005. - - - -Hoffman Expires July 5, 2006 [Page 111] - -Internet-Draft IKEv2 January 2006 - - - [RADIUS] Rigney, C., Rubens, A., Simpson, W., and S. Willens, - "Remote Authentication Dial In User Service (RADIUS)", - RFC 2138, April 1997. - - [RANDOMNESS] - Eastlake, D., Schiller, J., and S. Crocker, "Randomness - Requirements for Security", BCP 106, RFC 4086, June 2005. - - [REAUTH] Nir, Y., ""Repeated Authentication in IKEv2", - draft-nir-ikev2-auth-lt (work in progress), May 2005. - - [RSA] R. Rivest, A. Shamir, and L. Adleman, "A Method for - Obtaining Digital Signatures and Public-Key - Cryptosystems", February 1978. - - [SHA] National Institute of Standards and Technology, U.S. - Department of Commerce, "Secure Hash Standard", - FIPS 180-1, May 1994. - - [SIGMA] H. Krawczyk, "SIGMA: the `SIGn-and-MAc' Approach to - Authenticated Diffie-Hellman and its Use in the IKE - Protocols", Advances in Cryptography - CRYPTO 2003 - Proceedings LNCS 2729, 2003, <http:// - www.informatik.uni-trier.de/~ley/db/conf/crypto/ - crypto2003.html>. - - [SKEME] H. Krawczyk, "SKEME: A Versatile Secure Key Exchange - Mechanism for Internet", IEEE Proceedings of the 1996 - Symposium on Network and Distributed Systems Security , - 1996. - - [TRANSPARENCY] - Carpenter, B., "Internet Transparency", RFC 2775, - February 2000. - - [X.501] ITU-T, "Recommendation X.501: Information Technology - - Open Systems Interconnection - The Directory: Models", - 1993. - - [X.509] ITU-T, "Recommendation X.509 (1997 E): Information - Technology - Open Systems Interconnection - The Directory: - Authentication Framework", 1997. - - -Appendix A. Summary of changes from IKEv1 - - The goals of this revision to IKE are: - - - - -Hoffman Expires July 5, 2006 [Page 112] - -Internet-Draft IKEv2 January 2006 - - - 1. To define the entire IKE protocol in a single document, - replacing RFCs 2407, 2408, and 2409 and incorporating subsequent - changes to support NAT Traversal, Extensible Authentication, and - Remote Address acquisition; - - 2. To simplify IKE by replacing the eight different initial - exchanges with a single four-message exchange (with changes in - authentication mechanisms affecting only a single AUTH payload - rather than restructuring the entire exchange) see - [EXCHANGEANALYSIS]; - - 3. To remove the Domain of Interpretation (DOI), Situation (SIT), - and Labeled Domain Identifier fields, and the Commit and - Authentication only bits; - - 4. To decrease IKE's latency in the common case by making the - initial exchange be 2 round trips (4 messages), and allowing the - ability to piggyback setup of a CHILD_SA on that exchange; - - 5. To replace the cryptographic syntax for protecting the IKE - messages themselves with one based closely on ESP to simplify - implementation and security analysis; - - 6. To reduce the number of possible error states by making the - protocol reliable (all messages are acknowledged) and sequenced. - This allows shortening CREATE_CHILD_SA exchanges from 3 messages - to 2; - - 7. To increase robustness by allowing the responder to not do - significant processing until it receives a message proving that - the initiator can receive messages at its claimed IP address, - and not commit any state to an exchange until the initiator can - be cryptographically authenticated; - - 8. To fix cryptographic weaknesses such as the problem with - symmetries in hashes used for authentication documented by Tero - Kivinen; - - 9. To specify Traffic Selectors in their own payloads type rather - than overloading ID payloads, and making more flexible the - Traffic Selectors that may be specified; - - 10. To specify required behavior under certain error conditions or - when data that is not understood is received in order to make it - easier to make future revisions in a way that does not break - backwards compatibility; - - - - - -Hoffman Expires July 5, 2006 [Page 113] - -Internet-Draft IKEv2 January 2006 - - - 11. To simplify and clarify how shared state is maintained in the - presence of network failures and Denial of Service attacks; and - - 12. To maintain existing syntax and magic numbers to the extent - possible to make it likely that implementations of IKEv1 can be - enhanced to support IKEv2 with minimum effort. - - -Appendix B. Diffie-Hellman Groups - - There are two Diffie-Hellman groups defined here for use in IKE. - These groups were generated by Richard Schroeppel at the University - of Arizona. Properties of these primes are described in [OAKLEY]. - - The strength supplied by group one may not be sufficient for the - mandatory-to-implement encryption algorithm and is here for historic - reasons. - - Additional Diffie-Hellman groups have been defined in [ADDGROUP]. - -B.1. Group 1 - 768 Bit MODP - - This group is assigned id 1 (one). - - The prime is: 2^768 - 2 ^704 - 1 + 2^64 * { [2^638 pi] + 149686 } - Its hexadecimal value is: - - FFFFFFFF FFFFFFFF C90FDAA2 2168C234 C4C6628B 80DC1CD1 - 29024E08 8A67CC74 020BBEA6 3B139B22 514A0879 8E3404DD - EF9519B3 CD3A431B 302B0A6D F25F1437 4FE1356D 6D51C245 - E485B576 625E7EC6 F44C42E9 A63A3620 FFFFFFFF FFFFFFFF - - The generator is 2. - -B.2. Group 2 - 1024 Bit MODP - - This group is assigned id 2 (two). - - The prime is 2^1024 - 2^960 - 1 + 2^64 * { [2^894 pi] + 129093 }. - Its hexadecimal value is: - - FFFFFFFF FFFFFFFF C90FDAA2 2168C234 C4C6628B 80DC1CD1 - 29024E08 8A67CC74 020BBEA6 3B139B22 514A0879 8E3404DD - EF9519B3 CD3A431B 302B0A6D F25F1437 4FE1356D 6D51C245 - E485B576 625E7EC6 F44C42E9 A637ED6B 0BFF5CB6 F406B7ED - EE386BFB 5A899FA5 AE9F2411 7C4B1FE6 49286651 ECE65381 - FFFFFFFF FFFFFFFF - - - - -Hoffman Expires July 5, 2006 [Page 114] - -Internet-Draft IKEv2 January 2006 - - - The generator is 2. - - -Appendix C. Exchanges and Payloads - - {{ Clarif-AppA }} - - This appendix contains a short summary of the IKEv2 exchanges, and - what payloads can appear in which message. This appendix is purely - informative; if it disagrees with the body of this document, the - other text is considered correct. - - Vendor-ID (V) payloads may be included in any place in any message. - This sequence here shows what are the most logical places for them. - -C.1. IKE_SA_INIT Exchange - - request --> [N(COOKIE)], - SA, KE, Ni, - [N(NAT_DETECTION_SOURCE_IP)+, - N(NAT_DETECTION_DESTINATION_IP)], - [V+] - - normal response <-- SA, KE, Nr, - (no cookie) [N(NAT_DETECTION_SOURCE_IP), - N(NAT_DETECTION_DESTINATION_IP)], - [[N(HTTP_CERT_LOOKUP_SUPPORTED)], CERTREQ+], - [V+] - - - - - - - - - - - - - - - - - - - - - - - -Hoffman Expires July 5, 2006 [Page 115] - -Internet-Draft IKEv2 January 2006 - - -C.2. IKE_AUTH Exchange without EAP - - request --> IDi, [CERT+], - [N(INITIAL_CONTACT)], - [[N(HTTP_CERT_LOOKUP_SUPPORTED)], CERTREQ+], - [IDr], - AUTH, - [CP(CFG_REQUEST)], - [N(IPCOMP_SUPPORTED)+], - [N(USE_TRANSPORT_MODE)], - [N(ESP_TFC_PADDING_NOT_SUPPORTED)], - [N(NON_FIRST_FRAGMENTS_ALSO)], - SA, TSi, TSr, - [V+] - - response <-- IDr, [CERT+], - AUTH, - [CP(CFG_REPLY)], - [N(IPCOMP_SUPPORTED)], - [N(USE_TRANSPORT_MODE)], - [N(ESP_TFC_PADDING_NOT_SUPPORTED)], - [N(NON_FIRST_FRAGMENTS_ALSO)], - SA, TSi, TSr, - [N(ADDITIONAL_TS_POSSIBLE)], - [V+] - - - - - - - - - - - - - - - - - - - - - - - - - - -Hoffman Expires July 5, 2006 [Page 116] - -Internet-Draft IKEv2 January 2006 - - -C.3. IKE_AUTH Exchange with EAP - - first request --> IDi, - [N(INITIAL_CONTACT)], - [[N(HTTP_CERT_LOOKUP_SUPPORTED)], CERTREQ+], - [IDr], - [CP(CFG_REQUEST)], - [N(IPCOMP_SUPPORTED)+], - [N(USE_TRANSPORT_MODE)], - [N(ESP_TFC_PADDING_NOT_SUPPORTED)], - [N(NON_FIRST_FRAGMENTS_ALSO)], - SA, TSi, TSr, - [V+] - - first response <-- IDr, [CERT+], AUTH, - EAP, - [V+] - - / --> EAP - repeat 1..N times | - \ <-- EAP - - last request --> AUTH - - last response <-- AUTH, - [CP(CFG_REPLY)], - [N(IPCOMP_SUPPORTED)], - [N(USE_TRANSPORT_MODE)], - [N(ESP_TFC_PADDING_NOT_SUPPORTED)], - [N(NON_FIRST_FRAGMENTS_ALSO)], - SA, TSi, TSr, - [N(ADDITIONAL_TS_POSSIBLE)], - [V+] - - - - - - - - - - - - - - - - - - -Hoffman Expires July 5, 2006 [Page 117] - -Internet-Draft IKEv2 January 2006 - - -C.4. CREATE_CHILD_SA Exchange for Creating or Rekeying CHILD_SAs - - request --> [N(REKEY_SA)], - [N(IPCOMP_SUPPORTED)+], - [N(USE_TRANSPORT_MODE)], - [N(ESP_TFC_PADDING_NOT_SUPPORTED)], - [N(NON_FIRST_FRAGMENTS_ALSO)], - SA, Ni, [KEi], TSi, TSr - - response <-- [N(IPCOMP_SUPPORTED)], - [N(USE_TRANSPORT_MODE)], - [N(ESP_TFC_PADDING_NOT_SUPPORTED)], - [N(NON_FIRST_FRAGMENTS_ALSO)], - SA, Nr, [KEr], TSi, TSr, - [N(ADDITIONAL_TS_POSSIBLE)] - -C.5. CREATE_CHILD_SA Exchange for Rekeying the IKE_SA - - request --> SA, Ni, [KEi] - - response <-- SA, Nr, [KEr] - -C.6. INFORMATIONAL Exchange - - request --> [N+], - [D+], - [CP(CFG_REQUEST)] - - response <-- [N+], - [D+], - [CP(CFG_REPLY)] - - -Appendix D. Changes Between Internet Draft Versions - - This section will be removed before publication as an RFC. - -D.1. Changes from IKEv2 to draft -00 - - There were a zillion additions from the Clarifications document. - These are noted with "{{ Clarif-nn }}". - - Cleaned up many of the figures. Made the table headings consistent. - Made some tables easier to read by removing blank spaces. Removed - the "reserved to IANA" and "private use" text wording and moved it - into the tables. - - Changed many SHOULD and MUST requirements to better match RFC 2119. - - - -Hoffman Expires July 5, 2006 [Page 118] - -Internet-Draft IKEv2 January 2006 - - -Author's Address - - Paul Hoffman - VPN Consortium - 127 Segre Place - Santa Cruz, CA 95060 - US - - Phone: 1-831-426-9827 - Email: paul.hoffman@vpnc.org - - -Full Copyright Statement - - Copyright (C) The Internet Society (2006). - - This document is subject to the rights, licenses and restrictions - contained in BCP 78, and except as set forth therein, the authors - retain all their rights. - - This document and the information contained herein are provided on an - "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS - OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET - ENGINEERING TASK FORCE DISCLAIM 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. - - -Intellectual Property - - The IETF takes no position regarding the validity or scope of any - Intellectual Property Rights or other rights that might be claimed to - pertain to the implementation or use of the technology described in - this document or the extent to which any license under such rights - might or might not be available; nor does it represent that it has - made any independent effort to identify any such rights. Information - on the procedures with respect to rights in RFC documents can be - found in BCP 78 and BCP 79. - - Copies of IPR disclosures made to the IETF Secretariat and any - assurances of licenses to be made available, or the result of an - attempt made to obtain a general license or permission for the use of - such proprietary rights by implementers or users of this - specification can be obtained from the IETF on-line IPR repository at - http://www.ietf.org/ipr. - - The IETF invites any interested party to bring to its attention any - - - -Hoffman Expires July 5, 2006 [Page 119] - -Internet-Draft IKEv2 January 2006 - - - copyrights, patents or patent applications, or other proprietary - rights that may cover technology that may be required to implement - this standard. Please address the information to the IETF at - ietf-ipr@ietf.org. - - -Acknowledgment - - Funding for the RFC Editor function is currently provided by the - Internet Society. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Hoffman Expires July 5, 2006 [Page 120] - diff --git a/src/charon/doc/standards/draft-hoffman-ikev2bis-00.txt b/src/charon/doc/standards/draft-hoffman-ikev2bis-00.txt deleted file mode 100644 index 9d1b9d74d..000000000 --- a/src/charon/doc/standards/draft-hoffman-ikev2bis-00.txt +++ /dev/null @@ -1,6776 +0,0 @@ - - - -Network Working Group C. Kaufman -Internet-Draft Microsoft -Expires: August 27, 2006 P. Hoffman - VPN Consortium - P. Eronen - Nokia - February 23, 2006 - - - Internet Key Exchange Protocol: IKEv2 - draft-hoffman-ikev2bis-00.txt - -Status of this Memo - - By submitting this Internet-Draft, each author represents that any - applicable patent or other IPR claims of which he or she is aware - have been or will be disclosed, and any of which he or she becomes - aware will be disclosed, in accordance with Section 6 of BCP 79. - - 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 August 27, 2006. - -Copyright Notice - - Copyright (C) The Internet Society (2006). - -Abstract - - This document describes version 2 of the Internet Key Exchange (IKE) - protocol. It is a restatement of RFC 4306, and includes all of the - clarifications from the "IKEv2 Clarifications" document. - - - - - -Kaufman, et al. Expires August 27, 2006 [Page 1] - -Internet-Draft IKEv2bis February 2006 - - -Table of Contents - - 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5 - 1.1. Usage Scenarios . . . . . . . . . . . . . . . . . . . . . 6 - 1.1.1. Security Gateway to Security Gateway Tunnel . . . . . 7 - 1.1.2. Endpoint-to-Endpoint Transport . . . . . . . . . . . 7 - 1.1.3. Endpoint to Security Gateway Tunnel . . . . . . . . . 8 - 1.1.4. Other Scenarios . . . . . . . . . . . . . . . . . . . 9 - 1.2. The Initial Exchanges . . . . . . . . . . . . . . . . . . 9 - 1.3. The CREATE_CHILD_SA Exchange . . . . . . . . . . . . . . 12 - 1.3.1. Creating New CHILD_SAs with the CREATE_CHILD_SA - Exchange . . . . . . . . . . . . . . . . . . . . . . 13 - 1.3.2. Rekeying IKE_SAs with the CREATE_CHILD_SA Exchange . 14 - 1.3.3. Rekeying CHILD_SAs with the CREATE_CHILD_SA - Exchange . . . . . . . . . . . . . . . . . . . . . . 14 - 1.4. The INFORMATIONAL Exchange . . . . . . . . . . . . . . . 15 - 1.5. Informational Messages outside of an IKE_SA . . . . . . . 16 - 1.6. Requirements Terminology . . . . . . . . . . . . . . . . 17 - 1.7. Differences Between RFC 4306 and This Document . . . . . 17 - 2. IKE Protocol Details and Variations . . . . . . . . . . . . . 18 - 2.1. Use of Retransmission Timers . . . . . . . . . . . . . . 19 - 2.2. Use of Sequence Numbers for Message ID . . . . . . . . . 19 - 2.3. Window Size for Overlapping Requests . . . . . . . . . . 20 - 2.4. State Synchronization and Connection Timeouts . . . . . . 21 - 2.5. Version Numbers and Forward Compatibility . . . . . . . . 23 - 2.6. Cookies . . . . . . . . . . . . . . . . . . . . . . . . . 25 - 2.6.1. Interaction of COOKIE and INVALID_KE_PAYLOAD . . . . 27 - 2.7. Cryptographic Algorithm Negotiation . . . . . . . . . . . 28 - 2.8. Rekeying . . . . . . . . . . . . . . . . . . . . . . . . 29 - 2.8.1. Simultaneous CHILD_SA rekeying . . . . . . . . . . . 31 - 2.8.2. Rekeying the IKE_SA Versus Reauthentication . . . . . 33 - 2.9. Traffic Selector Negotiation . . . . . . . . . . . . . . 34 - 2.9.1. Traffic Selectors Violating Own Policy . . . . . . . 37 - 2.10. Nonces . . . . . . . . . . . . . . . . . . . . . . . . . 38 - 2.11. Address and Port Agility . . . . . . . . . . . . . . . . 38 - 2.12. Reuse of Diffie-Hellman Exponentials . . . . . . . . . . 38 - 2.13. Generating Keying Material . . . . . . . . . . . . . . . 39 - 2.14. Generating Keying Material for the IKE_SA . . . . . . . . 40 - 2.15. Authentication of the IKE_SA . . . . . . . . . . . . . . 41 - 2.16. Extensible Authentication Protocol Methods . . . . . . . 43 - 2.17. Generating Keying Material for CHILD_SAs . . . . . . . . 45 - 2.18. Rekeying IKE_SAs Using a CREATE_CHILD_SA Exchange . . . . 46 - 2.19. Requesting an Internal Address on a Remote Network . . . 47 - 2.20. Requesting the Peer's Version . . . . . . . . . . . . . . 48 - 2.21. Error Handling . . . . . . . . . . . . . . . . . . . . . 49 - 2.22. IPComp . . . . . . . . . . . . . . . . . . . . . . . . . 50 - 2.23. NAT Traversal . . . . . . . . . . . . . . . . . . . . . . 50 - 2.24. Explicit Congestion Notification (ECN) . . . . . . . . . 53 - - - -Kaufman, et al. Expires August 27, 2006 [Page 2] - -Internet-Draft IKEv2bis February 2006 - - - 3. Header and Payload Formats . . . . . . . . . . . . . . . . . 53 - 3.1. The IKE Header . . . . . . . . . . . . . . . . . . . . . 53 - 3.2. Generic Payload Header . . . . . . . . . . . . . . . . . 56 - 3.3. Security Association Payload . . . . . . . . . . . . . . 58 - 3.3.1. Proposal Substructure . . . . . . . . . . . . . . . . 60 - 3.3.2. Transform Substructure . . . . . . . . . . . . . . . 62 - 3.3.3. Valid Transform Types by Protocol . . . . . . . . . . 64 - 3.3.4. Mandatory Transform IDs . . . . . . . . . . . . . . . 65 - 3.3.5. Transform Attributes . . . . . . . . . . . . . . . . 66 - 3.3.6. Attribute Negotiation . . . . . . . . . . . . . . . . 67 - 3.4. Key Exchange Payload . . . . . . . . . . . . . . . . . . 68 - 3.5. Identification Payloads . . . . . . . . . . . . . . . . . 69 - 3.6. Certificate Payload . . . . . . . . . . . . . . . . . . . 71 - 3.7. Certificate Request Payload . . . . . . . . . . . . . . . 74 - 3.8. Authentication Payload . . . . . . . . . . . . . . . . . 76 - 3.9. Nonce Payload . . . . . . . . . . . . . . . . . . . . . . 77 - 3.10. Notify Payload . . . . . . . . . . . . . . . . . . . . . 77 - 3.10.1. Notify Message Types . . . . . . . . . . . . . . . . 78 - 3.11. Delete Payload . . . . . . . . . . . . . . . . . . . . . 84 - 3.12. Vendor ID Payload . . . . . . . . . . . . . . . . . . . . 85 - 3.13. Traffic Selector Payload . . . . . . . . . . . . . . . . 86 - 3.13.1. Traffic Selector . . . . . . . . . . . . . . . . . . 88 - 3.14. Encrypted Payload . . . . . . . . . . . . . . . . . . . . 90 - 3.15. Configuration Payload . . . . . . . . . . . . . . . . . . 92 - 3.15.1. Configuration Attributes . . . . . . . . . . . . . . 94 - 3.15.2. Meaning of INTERNAL_IP4_SUBNET/INTERNAL_IP6_SUBNET . 97 - 3.15.3. Configuration payloads for IPv6 . . . . . . . . . . . 99 - 3.15.4. Address Assignment Failures . . . . . . . . . . . . . 100 - 3.16. Extensible Authentication Protocol (EAP) Payload . . . . 100 - 4. Conformance Requirements . . . . . . . . . . . . . . . . . . 102 - 5. Security Considerations . . . . . . . . . . . . . . . . . . . 104 - 5.1. Traffic selector authorization . . . . . . . . . . . . . 107 - 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 108 - 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 108 - 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 109 - 8.1. Normative References . . . . . . . . . . . . . . . . . . 109 - 8.2. Informative References . . . . . . . . . . . . . . . . . 110 - Appendix A. Summary of changes from IKEv1 . . . . . . . . . . . 114 - Appendix B. Diffie-Hellman Groups . . . . . . . . . . . . . . . 115 - B.1. Group 1 - 768 Bit MODP . . . . . . . . . . . . . . . . . 115 - B.2. Group 2 - 1024 Bit MODP . . . . . . . . . . . . . . . . . 115 - Appendix C. Exchanges and Payloads . . . . . . . . . . . . . . . 116 - C.1. IKE_SA_INIT Exchange . . . . . . . . . . . . . . . . . . 116 - C.2. IKE_AUTH Exchange without EAP . . . . . . . . . . . . . . 117 - C.3. IKE_AUTH Exchange with EAP . . . . . . . . . . . . . . . 118 - C.4. CREATE_CHILD_SA Exchange for Creating or Rekeying - CHILD_SAs . . . . . . . . . . . . . . . . . . . . . . . . 119 - C.5. CREATE_CHILD_SA Exchange for Rekeying the IKE_SA . . . . 119 - - - -Kaufman, et al. Expires August 27, 2006 [Page 3] - -Internet-Draft IKEv2bis February 2006 - - - C.6. INFORMATIONAL Exchange . . . . . . . . . . . . . . . . . 119 - Appendix D. Changes Between Internet Draft Versions . . . . . . 119 - D.1. Changes from IKEv2 to draft -00 . . . . . . . . . . . . . 119 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 120 - Intellectual Property and Copyright Statements . . . . . . . . . 120 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Kaufman, et al. Expires August 27, 2006 [Page 4] - -Internet-Draft IKEv2bis February 2006 - - -1. Introduction - - {{ An introduction to the differences between RFC 4306 [IKEV2] and - this document is given at the end of Section 1. It is put there - (instead of here) to preserve the section numbering of the original - IKEv2 document. }} - - IP Security (IPsec) provides confidentiality, data integrity, access - control, and data source authentication to IP datagrams. These - services are provided by maintaining shared state between the source - and the sink of an IP datagram. This state defines, among other - things, the specific services provided to the datagram, which - cryptographic algorithms will be used to provide the services, and - the keys used as input to the cryptographic algorithms. - - Establishing this shared state in a manual fashion does not scale - well. Therefore, a protocol to establish this state dynamically is - needed. This memo describes such a protocol -- the Internet Key - Exchange (IKE). Version 1 of IKE was defined in RFCs 2407 [DOI], - 2408 [ISAKMP], and 2409 [IKEV1]. IKEv2 was defined in [IKEV2]. This - single document is intended to replace all three of those RFCs. - - Definitions of the primitive terms in this document (such as Security - Association or SA) can be found in [IPSECARCH]. {{ Clarif-7.2 }} It - should be noted that parts of IKEv2 rely on some of the processing - rules in [IPSECARCH], as described in various sections of this - document. - - IKE performs mutual authentication between two parties and - establishes an IKE security association (SA) that includes shared - secret information that can be used to efficiently establish SAs for - Encapsulating Security Payload (ESP) [ESP] and/or Authentication - Header (AH) [AH] and a set of cryptographic algorithms to be used by - the SAs to protect the traffic that they carry. In this document, - the term "suite" or "cryptographic suite" refers to a complete set of - algorithms used to protect an SA. An initiator proposes one or more - suites by listing supported algorithms that can be combined into - suites in a mix-and-match fashion. IKE can also negotiate use of IP - Compression (IPComp) [IPCOMP] in connection with an ESP and/or AH SA. - We call the IKE SA an "IKE_SA". The SAs for ESP and/or AH that get - set up through that IKE_SA we call "CHILD_SAs". - - All IKE communications consist of pairs of messages: a request and a - response. The pair is called an "exchange". We call the first - messages establishing an IKE_SA IKE_SA_INIT and IKE_AUTH exchanges - and subsequent IKE exchanges CREATE_CHILD_SA or INFORMATIONAL - exchanges. In the common case, there is a single IKE_SA_INIT - exchange and a single IKE_AUTH exchange (a total of four messages) to - - - -Kaufman, et al. Expires August 27, 2006 [Page 5] - -Internet-Draft IKEv2bis February 2006 - - - establish the IKE_SA and the first CHILD_SA. In exceptional cases, - there may be more than one of each of these exchanges. In all cases, - all IKE_SA_INIT exchanges MUST complete before any other exchange - type, then all IKE_AUTH exchanges MUST complete, and following that - any number of CREATE_CHILD_SA and INFORMATIONAL exchanges may occur - in any order. In some scenarios, only a single CHILD_SA is needed - between the IPsec endpoints, and therefore there would be no - additional exchanges. Subsequent exchanges MAY be used to establish - additional CHILD_SAs between the same authenticated pair of endpoints - and to perform housekeeping functions. - - IKE message flow always consists of a request followed by a response. - It is the responsibility of the requester to ensure reliability. If - the response is not received within a timeout interval, the requester - needs to retransmit the request (or abandon the connection). - - The first request/response of an IKE session (IKE_SA_INIT) negotiates - security parameters for the IKE_SA, sends nonces, and sends Diffie- - Hellman values. - - The second request/response (IKE_AUTH) transmits identities, proves - knowledge of the secrets corresponding to the two identities, and - sets up an SA for the first (and often only) AH and/or ESP CHILD_SA. - - The types of subsequent exchanges are CREATE_CHILD_SA (which creates - a CHILD_SA) and INFORMATIONAL (which deletes an SA, reports error - conditions, or does other housekeeping). Every request requires a - response. An INFORMATIONAL request with no payloads (other than the - empty Encrypted payload required by the syntax) is commonly used as a - check for liveness. These subsequent exchanges cannot be used until - the initial exchanges have completed. - - In the description that follows, we assume that no errors occur. - Modifications to the flow should errors occur are described in - Section 2.21. - -1.1. Usage Scenarios - - IKE is expected to be used to negotiate ESP and/or AH SAs in a number - of different scenarios, each with its own special requirements. - - - - - - - - - - - -Kaufman, et al. Expires August 27, 2006 [Page 6] - -Internet-Draft IKEv2bis February 2006 - - -1.1.1. Security Gateway to Security Gateway Tunnel - - +-+-+-+-+-+ +-+-+-+-+-+ - ! ! IPsec ! ! - Protected !Tunnel ! tunnel !Tunnel ! Protected - Subnet <-->!Endpoint !<---------->!Endpoint !<--> Subnet - ! ! ! ! - +-+-+-+-+-+ +-+-+-+-+-+ - - Figure 1: Security Gateway to Security Gateway Tunnel - - In this scenario, neither endpoint of the IP connection implements - IPsec, but network nodes between them protect traffic for part of the - way. Protection is transparent to the endpoints, and depends on - ordinary routing to send packets through the tunnel endpoints for - processing. Each endpoint would announce the set of addresses - "behind" it, and packets would be sent in tunnel mode where the inner - IP header would contain the IP addresses of the actual endpoints. - -1.1.2. Endpoint-to-Endpoint Transport - - +-+-+-+-+-+ +-+-+-+-+-+ - ! ! IPsec transport ! ! - !Protected! or tunnel mode SA !Protected! - !Endpoint !<---------------------------------------->!Endpoint ! - ! ! ! ! - +-+-+-+-+-+ +-+-+-+-+-+ - - Figure 2: Endpoint to Endpoint - - In this scenario, both endpoints of the IP connection implement - IPsec, as required of hosts in [IPSECARCH]. Transport mode will - commonly be used with no inner IP header. If there is an inner IP - header, the inner addresses will be the same as the outer addresses. - A single pair of addresses will be negotiated for packets to be - protected by this SA. These endpoints MAY implement application - layer access controls based on the IPsec authenticated identities of - the participants. This scenario enables the end-to-end security that - has been a guiding principle for the Internet since [ARCHPRINC], - [TRANSPARENCY], and a method of limiting the inherent problems with - complexity in networks noted by [ARCHGUIDEPHIL]. Although this - scenario may not be fully applicable to the IPv4 Internet, it has - been deployed successfully in specific scenarios within intranets - using IKEv1. It should be more broadly enabled during the transition - to IPv6 and with the adoption of IKEv2. - - It is possible in this scenario that one or both of the protected - endpoints will be behind a network address translation (NAT) node, in - - - -Kaufman, et al. Expires August 27, 2006 [Page 7] - -Internet-Draft IKEv2bis February 2006 - - - which case the tunneled packets will have to be UDP encapsulated so - that port numbers in the UDP headers can be used to identify - individual endpoints "behind" the NAT (see Section 2.23). - -1.1.3. Endpoint to Security Gateway Tunnel - - +-+-+-+-+-+ +-+-+-+-+-+ - ! ! IPsec ! ! Protected - !Protected! tunnel !Tunnel ! Subnet - !Endpoint !<------------------------>!Endpoint !<--- and/or - ! ! ! ! Internet - +-+-+-+-+-+ +-+-+-+-+-+ - - Figure 3: Endpoint to Security Gateway Tunnel - - In this scenario, a protected endpoint (typically a portable roaming - computer) connects back to its corporate network through an IPsec- - protected tunnel. It might use this tunnel only to access - information on the corporate network, or it might tunnel all of its - traffic back through the corporate network in order to take advantage - of protection provided by a corporate firewall against Internet-based - attacks. In either case, the protected endpoint will want an IP - address associated with the security gateway so that packets returned - to it will go to the security gateway and be tunneled back. This IP - address may be static or may be dynamically allocated by the security - gateway. {{ Clarif-6.1 }} In support of the latter case, IKEv2 - includes a mechanism (namely, configuration payloads) for the - initiator to request an IP address owned by the security gateway for - use for the duration of its SA. - - In this scenario, packets will use tunnel mode. On each packet from - the protected endpoint, the outer IP header will contain the source - IP address associated with its current location (i.e., the address - that will get traffic routed to the endpoint directly), while the - inner IP header will contain the source IP address assigned by the - security gateway (i.e., the address that will get traffic routed to - the security gateway for forwarding to the endpoint). The outer - destination address will always be that of the security gateway, - while the inner destination address will be the ultimate destination - for the packet. - - In this scenario, it is possible that the protected endpoint will be - behind a NAT. In that case, the IP address as seen by the security - gateway will not be the same as the IP address sent by the protected - endpoint, and packets will have to be UDP encapsulated in order to be - routed properly. - - - - - -Kaufman, et al. Expires August 27, 2006 [Page 8] - -Internet-Draft IKEv2bis February 2006 - - -1.1.4. Other Scenarios - - Other scenarios are possible, as are nested combinations of the - above. One notable example combines aspects of 1.1.1 and 1.1.3. A - subnet may make all external accesses through a remote security - gateway using an IPsec tunnel, where the addresses on the subnet are - routed to the security gateway by the rest of the Internet. An - example would be someone's home network being virtually on the - Internet with static IP addresses even though connectivity is - provided by an ISP that assigns a single dynamically assigned IP - address to the user's security gateway (where the static IP addresses - and an IPsec relay are provided by a third party located elsewhere). - -1.2. The Initial Exchanges - - Communication using IKE always begins with IKE_SA_INIT and IKE_AUTH - exchanges (known in IKEv1 as Phase 1). These initial exchanges - normally consist of four messages, though in some scenarios that - number can grow. All communications using IKE consist of request/ - response pairs. We'll describe the base exchange first, followed by - variations. The first pair of messages (IKE_SA_INIT) negotiate - cryptographic algorithms, exchange nonces, and do a Diffie-Hellman - exchange [DH]. - - The second pair of messages (IKE_AUTH) authenticate the previous - messages, exchange identities and certificates, and establish the - first CHILD_SA. Parts of these messages are encrypted and integrity - protected with keys established through the IKE_SA_INIT exchange, so - the identities are hidden from eavesdroppers and all fields in all - the messages are authenticated. - - In the following descriptions, the payloads contained in the message - are indicated by names as listed below. - - - - - - - - - - - - - - - - - - -Kaufman, et al. Expires August 27, 2006 [Page 9] - -Internet-Draft IKEv2bis February 2006 - - - Notation Payload - ----------------------------------------- - AUTH Authentication - CERT Certificate - CERTREQ Certificate Request - CP Configuration - D Delete - E Encrypted - EAP Extensible Authentication - HDR IKE Header - IDi Identification - Initiator - IDr Identification - Responder - KE Key Exchange - Ni, Nr Nonce - N Notify - SA Security Association - TSi Traffic Selector - Initiator - TSr Traffic Selector - Responder - V Vendor ID - - The details of the contents of each payload are described in section - 3. Payloads that may optionally appear will be shown in brackets, - such as [CERTREQ], indicate that optionally a certificate request - payload can be included. - - {{ Clarif-7.10 }} Many payloads contain fields marked as "RESERVED". - Some payloads in IKEv2 (and historically in IKEv1) are not aligned to - 4-byte boundaries. - - The initial exchanges are as follows: - - Initiator Responder - ------------------------------------------------------------------- - HDR, SAi1, KEi, Ni --> - - HDR contains the Security Parameter Indexes (SPIs), version numbers, - and flags of various sorts. The SAi1 payload states the - cryptographic algorithms the initiator supports for the IKE_SA. The - KE payload sends the initiator's Diffie-Hellman value. Ni is the - initiator's nonce. - - <-- HDR, SAr1, KEr, Nr, [CERTREQ] - - The responder chooses a cryptographic suite from the initiator's - offered choices and expresses that choice in the SAr1 payload, - completes the Diffie-Hellman exchange with the KEr payload, and sends - its nonce in the Nr payload. - - - - -Kaufman, et al. Expires August 27, 2006 [Page 10] - -Internet-Draft IKEv2bis February 2006 - - - At this point in the negotiation, each party can generate SKEYSEED, - from which all keys are derived for that IKE_SA. All but the headers - of all the messages that follow are encrypted and integrity - protected. The keys used for the encryption and integrity protection - are derived from SKEYSEED and are known as SK_e (encryption) and SK_a - (authentication, a.k.a. integrity protection). A separate SK_e and - SK_a is computed for each direction. In addition to the keys SK_e - and SK_a derived from the DH value for protection of the IKE_SA, - another quantity SK_d is derived and used for derivation of further - keying material for CHILD_SAs. The notation SK { ... } indicates - that these payloads are encrypted and integrity protected using that - direction's SK_e and SK_a. - - HDR, SK {IDi, [CERT,] [CERTREQ,] - [IDr,] AUTH, SAi2, - TSi, TSr} --> - - The initiator asserts its identity with the IDi payload, proves - knowledge of the secret corresponding to IDi and integrity protects - the contents of the first message using the AUTH payload (see - Section 2.15). It might also send its certificate(s) in CERT - payload(s) and a list of its trust anchors in CERTREQ payload(s). If - any CERT payloads are included, the first certificate provided MUST - contain the public key used to verify the AUTH field. The optional - payload IDr enables the initiator to specify which of the responder's - identities it wants to talk to. This is useful when the machine on - which the responder is running is hosting multiple identities at the - same IP address. The initiator begins negotiation of a CHILD_SA - using the SAi2 payload. The final fields (starting with SAi2) are - described in the description of the CREATE_CHILD_SA exchange. - - <-- HDR, SK {IDr, [CERT,] AUTH, - SAr2, TSi, TSr} - - The responder asserts its identity with the IDr payload, optionally - sends one or more certificates (again with the certificate containing - the public key used to verify AUTH listed first), authenticates its - identity and protects the integrity of the second message with the - AUTH payload, and completes negotiation of a CHILD_SA with the - additional fields described below in the CREATE_CHILD_SA exchange. - - The recipients of messages 3 and 4 MUST verify that all signatures - and MACs are computed correctly and that the names in the ID payloads - correspond to the keys used to generate the AUTH payload. - - {{ Clarif-4.2}} If creating the CHILD_SA during the IKE_AUTH exchange - fails for some reason, the IKE_SA is still created as usual. The - list of responses in the IKE_AUTH exchange that do not prevent an - - - -Kaufman, et al. Expires August 27, 2006 [Page 11] - -Internet-Draft IKEv2bis February 2006 - - - IKE_SA from being set up include at least the following: - NO_PROPOSAL_CHOSEN, TS_UNACCEPTABLE, SINGLE_PAIR_REQUIRED, - INTERNAL_ADDRESS_FAILURE, and FAILED_CP_REQUIRED. - - {{ Clarif-4.3 }} Note that IKE_AUTH messages do not contain KEi/KEr - or Ni/Nr payloads. Thus, the SA payload in IKE_AUTH exchange cannot - contain Transform Type 4 (Diffie-Hellman Group) with any value other - than NONE. Implementations SHOULD NOT send such a transform because - it cannot be interpreted consistently, and implementations SHOULD - ignore any such tranforms they receive. - -1.3. The CREATE_CHILD_SA Exchange - - {{ This is a heavy rewrite of most of this section. The major - organization changes are described in Clarif-4.1 and Clarif-5.1. }} - - The CREATE_CHILD_SA exchange is used to create new CHILD_SAs and to - rekey both IKE_SAs and CHILD_SAs. This exchange consists of a single - request/response pair, and some of its function was referred to as a - phase 2 exchange in IKEv1. It MAY be initiated by either end of the - IKE_SA after the initial exchanges are completed. - - All messages following the initial exchange are cryptographically - protected using the cryptographic algorithms and keys negotiated in - the first two messages of the IKE exchange. These subsequent - messages use the syntax of the Encrypted Payload described in - Section 3.14. All subsequent messages include an Encrypted Payload, - even if they are referred to in the text as "empty". For both - messages in the CREATE_CHILD_SA, the message following the header is - encrypted and the message including the header is integrity protected - using the cryptographic algorithms negotiated for the IKE_SA. - - The CREATE_CHILD_SA is also used for rekeying IKE_SAs and CHILD_SAs. - An SA is rekeyed by creating a new SA and then deleting the old one. - This section describes the first part of rekeying, the creation of - new SAs; Section 2.8 covers the mechanics of rekeying, including - moving traffic from old to new SAs and the deletion of the old SAs. - The two sections must be read together to understand the entire - process of rekeying. - - Either endpoint may initiate a CREATE_CHILD_SA exchange, so in this - section the term initiator refers to the endpoint initiating this - exchange. An implementation MAY refuse all CREATE_CHILD_SA requests - within an IKE_SA. - - The CREATE_CHILD_SA request MAY optionally contain a KE payload for - an additional Diffie-Hellman exchange to enable stronger guarantees - of forward secrecy for the CHILD_SA. The keying material for the - - - -Kaufman, et al. Expires August 27, 2006 [Page 12] - -Internet-Draft IKEv2bis February 2006 - - - CHILD_SA is a function of SK_d established during the establishment - of the IKE_SA, the nonces exchanged during the CREATE_CHILD_SA - exchange, and the Diffie-Hellman value (if KE payloads are included - in the CREATE_CHILD_SA exchange). - - If a CREATE_CHILD_SA exchange includes a KEi payload, at least one of - the SA offers MUST include the Diffie-Hellman group of the KEi. The - Diffie-Hellman group of the KEi MUST be an element of the group the - initiator expects the responder to accept (additional Diffie-Hellman - groups can be proposed). If the responder rejects the Diffie-Hellman - group of the KEi payload, the responder MUST reject the request and - indicate its preferred Diffie-Hellman group in the INVALID_KE_PAYLOAD - Notification payload. In the case of such a rejection, the - CREATE_CHILD_SA exchange fails, and the initiator will probably retry - the exchange with a Diffie-Hellman proposal and KEi in the group that - the responder gave in the INVALID_KE_PAYLOAD. - -1.3.1. Creating New CHILD_SAs with the CREATE_CHILD_SA Exchange - - A CHILD_SA may be created by sending a CREATE_CHILD_SA request. The - CREATE_CHILD_SA request for creating a new CHILD_SA is: - - Initiator Responder - ------------------------------------------------------------------- - HDR, SK {SA, Ni, [KEi], - TSi, TSr} --> - - The initiator sends SA offer(s) in the SA payload, a nonce in the Ni - payload, optionally a Diffie-Hellman value in the KEi payload, and - the proposed traffic selectors for the proposed CHILD_SA in the TSi - and TSr payloads. - - The CREATE_CHILD_SA response for creating a new CHILD_SA is: - - <-- HDR, SK {SA, Nr, [KEr], - TSi, TSr} - - The responder replies (using the same Message ID to respond) with the - accepted offer in an SA payload, and a Diffie-Hellman value in the - KEr payload if KEi was included in the request and the selected - cryptographic suite includes that group. - - The traffic selectors for traffic to be sent on that SA are specified - in the TS payloads in the response, which may be a subset of what the - initiator of the CHILD_SA proposed. - - - - - - -Kaufman, et al. Expires August 27, 2006 [Page 13] - -Internet-Draft IKEv2bis February 2006 - - -1.3.2. Rekeying IKE_SAs with the CREATE_CHILD_SA Exchange - - The CREATE_CHILD_SA request for rekeying an IKE_SA is: - - Initiator Responder - ------------------------------------------------------------------- - HDR, SK {SA, Ni, KEi} --> - - The initiator sends SA offer(s) in the SA payload, a nonce in the Ni - payload, and a Diffie-Hellman value in the KEi payload. New - initiator and responder SPIs are supplied in the SPI fields. - - The CREATE_CHILD_SA response for rekeying an IKE_SA is: - - <-- HDR, SK {SA, Nr, KEr} - - The responder replies (using the same Message ID to respond) with the - accepted offer in an SA payload, and a Diffie-Hellman value in the - KEr payload if the selected cryptographic suite includes that group. - - The new IKE_SA has its message counters set to 0, regardless of what - they were in the earlier IKE_SA. The window size starts at 1 for any - new IKE_SA. - - KEi and KEr are required for rekeying an IKE_SA. - -1.3.3. Rekeying CHILD_SAs with the CREATE_CHILD_SA Exchange - - The CREATE_CHILD_SA request for rekeying a CHILD_SA is: - - Initiator Responder - ------------------------------------------------------------------- - HDR, SK {N, SA, Ni, [KEi], - TSi, TSr} --> - - The initiator sends SA offer(s) in the SA payload, a nonce in the Ni - payload, optionally a Diffie-Hellman value in the KEi payload, and - the proposed traffic selectors for the proposed CHILD_SA in the TSi - and TSr payloads. When rekeying an existing CHILD_SA, the leading N - payload of type REKEY_SA MUST be included and MUST give the SPI (as - they would be expected in the headers of inbound packets) of the SAs - being rekeyed. - - The CREATE_CHILD_SA response for rekeying a CHILD_SA is: - - <-- HDR, SK {SA, Nr, [KEr], - Si, TSr} - - - - -Kaufman, et al. Expires August 27, 2006 [Page 14] - -Internet-Draft IKEv2bis February 2006 - - - The responder replies (using the same Message ID to respond) with the - accepted offer in an SA payload, and a Diffie-Hellman value in the - KEr payload if KEi was included in the request and the selected - cryptographic suite includes that group. - - The traffic selectors for traffic to be sent on that SA are specified - in the TS payloads in the response, which may be a subset of what the - initiator of the CHILD_SA proposed. - -1.4. The INFORMATIONAL Exchange - - At various points during the operation of an IKE_SA, peers may desire - to convey control messages to each other regarding errors or - notifications of certain events. To accomplish this, IKE defines an - INFORMATIONAL exchange. INFORMATIONAL exchanges MUST ONLY occur - after the initial exchanges and are cryptographically protected with - the negotiated keys. - - Control messages that pertain to an IKE_SA MUST be sent under that - IKE_SA. Control messages that pertain to CHILD_SAs MUST be sent - under the protection of the IKE_SA which generated them (or its - successor if the IKE_SA was replaced for the purpose of rekeying). - - Messages in an INFORMATIONAL exchange contain zero or more - Notification, Delete, and Configuration payloads. The Recipient of - an INFORMATIONAL exchange request MUST send some response (else the - Sender will assume the message was lost in the network and will - retransmit it). That response MAY be a message with no payloads. - The request message in an INFORMATIONAL exchange MAY also contain no - payloads. This is the expected way an endpoint can ask the other - endpoint to verify that it is alive. - - {{ Clarif-5.6 }} ESP and AH SAs always exist in pairs, with one SA in - each direction. When an SA is closed, both members of the pair MUST - be closed (that is, deleted). When SAs are nested, as when data (and - IP headers if in tunnel mode) are encapsulated first with IPComp, - then with ESP, and finally with AH between the same pair of - endpoints, all of the SAs MUST be deleted together. Each endpoint - MUST close its incoming SAs and allow the other endpoint to close the - other SA in each pair. To delete an SA, an INFORMATIONAL exchange - with one or more delete payloads is sent listing the SPIs (as they - would be expected in the headers of inbound packets) of the SAs to be - deleted. The recipient MUST close the designated SAs. {{ Clarif-5.7 - }} Note that one never sends delete payloads for the two sides of an - SA in a single message. If there are many SAs to delete at the same - time (such as for nested SAs), one includes delete payloads for in - inbound half of each SA pair in your Informational exchange. - - - - -Kaufman, et al. Expires August 27, 2006 [Page 15] - -Internet-Draft IKEv2bis February 2006 - - - Normally, the reply in the INFORMATIONAL exchange will contain delete - payloads for the paired SAs going in the other direction. There is - one exception. If by chance both ends of a set of SAs independently - decide to close them, each may send a delete payload and the two - requests may cross in the network. If a node receives a delete - request for SAs for which it has already issued a delete request, it - MUST delete the outgoing SAs while processing the request and the - incoming SAs while processing the response. In that case, the - responses MUST NOT include delete payloads for the deleted SAs, since - that would result in duplicate deletion and could in theory delete - the wrong SA. - - {{ Demoted the SHOULD }} Half-closed connections are anomalous, and a - node with auditing capability should probably audit their existence - if they persist. Note that this specification nowhere specifies time - periods, so it is up to individual endpoints to decide how long to - wait. A node MAY refuse to accept incoming data on half-closed - connections but MUST NOT unilaterally close them and reuse the SPIs. - If connection state becomes sufficiently messed up, a node MAY close - the IKE_SA; doing so will implicitly close all SAs negotiated under - it. It can then rebuild the SAs it needs on a clean base under a new - IKE_SA. {{ Clarif-5.8 }} The response to a request that deletes the - IKE_SA is an empty Informational response. - - The INFORMATIONAL exchange is defined as: - - Initiator Responder - ------------------------------------------------------------------- - HDR, SK {[N,] [D,] - [CP,] ...} --> - <-- HDR, SK {[N,] [D,] - [CP], ...} - - The processing of an INFORMATIONAL exchange is determined by its - component payloads. - -1.5. Informational Messages outside of an IKE_SA - - If an encrypted IKE packet arrives on port 500 or 4500 with an - unrecognized SPI, it could be because the receiving node has recently - crashed and lost state or because of some other system malfunction or - attack. If the receiving node has an active IKE_SA to the IP address - from whence the packet came, it MAY send a notification of the - wayward packet over that IKE_SA in an INFORMATIONAL exchange. If it - does not have such an IKE_SA, it MAY send an Informational message - without cryptographic protection to the source IP address. Such a - message is not part of an informational exchange, and the receiving - node MUST NOT respond to it. Doing so could cause a message loop. - - - -Kaufman, et al. Expires August 27, 2006 [Page 16] - -Internet-Draft IKEv2bis February 2006 - - - {{ Clarif-7.7 }} There are two cases when such a one-way notification - is sent: INVALID_IKE_SPI and INVALID_SPI. These notifications are - sent outside of an IKE_SA. Note that such notifications are - explicitly not Informational exchanges; these are one-way messages - that must not be responded to. In case of INVALID_IKE_SPI, the - message sent is a response message, and thus it is sent to the IP - address and port from whence it came with the same IKE SPIs and the - Message ID copied. In case of INVALID_SPI, however, there are no IKE - SPI values that would be meaningful to the recipient of such a - notification. Using zero values or random values are both - acceptable. - -1.6. Requirements Terminology - - Keywords "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT" and - "MAY" that appear in this document are to be interpreted as described - in [MUSTSHOULD]. - - The term "Expert Review" is to be interpreted as defined in - [IANACONS]. - -1.7. Differences Between RFC 4306 and This Document - - {{ Added this entire section, including this recursive remark. }} - - This document contains clarifications and amplifications to IKEv2 - [IKEV2]. The clarifications are mostly based on [Clarif]. The - changes listed in that document were discussed in the IPsec Working - Group and, after the Working Group was disbanded, on the IPsec - mailing list. That document contains detailed explanations of areas - that were unclear in IKEv2, and is thus useful to implementers of - IKEv2. - - The protocol described in this document retains the same major - version number (2) and minor version number (0) as was used in RFC - 4306. - - In the body of this document, notes that are enclosed in double curly - braces {{ such as this }} point out changes from IKEv2. Changes that - come from [Clarif] are marked with the section from that document, - such as "{{ Clarif-2.10 }}". - - This document also make the figures and references a bit more regular - than in [IKEV2]. - - IKEv2 developers have noted that the SHOULD-level requirements are - often unclear in that they don't say when it is OK to not obey the - requirements. They also have noted that there are MUST-level - - - -Kaufman, et al. Expires August 27, 2006 [Page 17] - -Internet-Draft IKEv2bis February 2006 - - - requirements that are not related to interoperability. This document - has more explanation of some of these requirements. All non- - capitalized uses of the words SHOULD and MUST now mean their normal - English sense, not the interoperability sense of [MUSTSHOULD]. - - IKEv2 (and IKEv1) developers have noted that there is a great deal of - material in the tables of codes in Section 3.10. This leads to - implementers not having all the needed information in the main body - of the docment. A later version of this document may move much of - the material from those tables into the associated parts of the main - body of the document. - - A later version of this document will probably have all the {{ }} - comments removed from the body of the document and instead appear in - an appendix. - - -2. IKE Protocol Details and Variations - - IKE normally listens and sends on UDP port 500, though IKE messages - may also be received on UDP port 4500 with a slightly different - format (see Section 2.23). Since UDP is a datagram (unreliable) - protocol, IKE includes in its definition recovery from transmission - errors, including packet loss, packet replay, and packet forgery. - IKE is designed to function so long as (1) at least one of a series - of retransmitted packets reaches its destination before timing out; - and (2) the channel is not so full of forged and replayed packets so - as to exhaust the network or CPU capacities of either endpoint. Even - in the absence of those minimum performance requirements, IKE is - designed to fail cleanly (as though the network were broken). - - Although IKEv2 messages are intended to be short, they contain - structures with no hard upper bound on size (in particular, X.509 - certificates), and IKEv2 itself does not have a mechanism for - fragmenting large messages. IP defines a mechanism for fragmentation - of oversize UDP messages, but implementations vary in the maximum - message size supported. Furthermore, use of IP fragmentation opens - an implementation to denial of service attacks [DOSUDPPROT]. - Finally, some NAT and/or firewall implementations may block IP - fragments. - - All IKEv2 implementations MUST be able to send, receive, and process - IKE messages that are up to 1280 bytes long, and they SHOULD be able - to send, receive, and process messages that are up to 3000 bytes - long. {{ Demoted the SHOULD }} IKEv2 implementations need to be aware - of the maximum UDP message size supported and MAY shorten messages by - leaving out some certificates or cryptographic suite proposals if - that will keep messages below the maximum. Use of the "Hash and URL" - - - -Kaufman, et al. Expires August 27, 2006 [Page 18] - -Internet-Draft IKEv2bis February 2006 - - - formats rather than including certificates in exchanges where - possible can avoid most problems. {{ Demoted the SHOULD }} - Implementations and configuration need to keep in mind, however, that - if the URL lookups are possible only after the IPsec SA is - established, recursion issues could prevent this technique from - working. - - {{ Clarif-7.5 }} All packets sent on port 4500 MUST begin with the - prefix of four zeros; otherwise, the receiver won't know how to - handle them. - -2.1. Use of Retransmission Timers - - All messages in IKE exist in pairs: a request and a response. The - setup of an IKE_SA normally consists of two request/response pairs. - Once the IKE_SA is set up, either end of the security association may - initiate requests at any time, and there can be many requests and - responses "in flight" at any given moment. But each message is - labeled as either a request or a response, and for each request/ - response pair one end of the security association is the initiator - and the other is the responder. - - For every pair of IKE messages, the initiator is responsible for - retransmission in the event of a timeout. The responder MUST never - retransmit a response unless it receives a retransmission of the - request. In that event, the responder MUST ignore the retransmitted - request except insofar as it triggers a retransmission of the - response. The initiator MUST remember each request until it receives - the corresponding response. The responder MUST remember each - response until it receives a request whose sequence number is larger - than the sequence number in the response plus its window size (see - Section 2.3). - - IKE is a reliable protocol, in the sense that the initiator MUST - retransmit a request until either it receives a corresponding reply - OR it deems the IKE security association to have failed and it - discards all state associated with the IKE_SA and any CHILD_SAs - negotiated using that IKE_SA. - -2.2. Use of Sequence Numbers for Message ID - - Every IKE message contains a Message ID as part of its fixed header. - This Message ID is used to match up requests and responses, and to - identify retransmissions of messages. - - The Message ID is a 32-bit quantity, which is zero for the first IKE - request in each direction. {{ Clarif-3.10 }} When the IKE_AUTH - exchange does not use EAP, the IKE_SA initial setup messages will - - - -Kaufman, et al. Expires August 27, 2006 [Page 19] - -Internet-Draft IKEv2bis February 2006 - - - always be numbered 0 and 1. When EAP is used, each pair of messages - have their message numbers incremented; the first pair of AUTH - messages will have an ID of 1, the second will be 2, and so on. - - Each endpoint in the IKE Security Association maintains two "current" - Message IDs: the next one to be used for a request it initiates and - the next one it expects to see in a request from the other end. - These counters increment as requests are generated and received. - Responses always contain the same message ID as the corresponding - request. That means that after the initial exchange, each integer n - may appear as the message ID in four distinct messages: the nth - request from the original IKE initiator, the corresponding response, - the nth request from the original IKE responder, and the - corresponding response. If the two ends make very different numbers - of requests, the Message IDs in the two directions can be very - different. There is no ambiguity in the messages, however, because - the (I)nitiator and (R)esponse bits in the message header specify - which of the four messages a particular one is. - - {{ Clarif-2.2 }} The Message ID for IKE_SA_INIT messages is always - zero, including for retries of the message due to responses such as - COOKIE and INVALID_KE_PAYLOAD. - - Note that Message IDs are cryptographically protected and provide - protection against message replays. In the unlikely event that - Message IDs grow too large to fit in 32 bits, the IKE_SA MUST be - closed. Rekeying an IKE_SA resets the sequence numbers. - - {{ Clarif-2.3 }} When a responder receives an IKE_SA_INIT request, it - has to determine whether the packet is a retransmission belonging to - an existing "half-open" IKE_SA (in which case the responder - retransmits the same response), or a new request (in which case the - responder creates a new IKE_SA and sends a fresh response), or it is - a retransmission of a now-opened IKE_SA (in whcih case the responder - ignores it). It is not sufficient to use the initiator's SPI and/or - IP address to differentiate between the two cases because two - different peers behind a single NAT could choose the same initiator - SPI. Instead, a robust responder will do the IKE_SA lookup using the - whole packet, its hash, or the Ni payload. - -2.3. Window Size for Overlapping Requests - - In order to maximize IKE throughput, an IKE endpoint MAY issue - multiple requests before getting a response to any of them if the - other endpoint has indicated its ability to handle such requests. - For simplicity, an IKE implementation MAY choose to process requests - strictly in order and/or wait for a response to one request before - issuing another. Certain rules must be followed to ensure - - - -Kaufman, et al. Expires August 27, 2006 [Page 20] - -Internet-Draft IKEv2bis February 2006 - - - interoperability between implementations using different strategies. - - After an IKE_SA is set up, either end can initiate one or more - requests. These requests may pass one another over the network. An - IKE endpoint MUST be prepared to accept and process a request while - it has a request outstanding in order to avoid a deadlock in this - situation. {{ Downgraded the SHOULD }} An IKE endpoint may also - accept and process multiple requests while it has a request - outstanding. - - An IKE endpoint MUST wait for a response to each of its messages - before sending a subsequent message unless it has received a - SET_WINDOW_SIZE Notify message from its peer informing it that the - peer is prepared to maintain state for multiple outstanding messages - in order to allow greater throughput. - - An IKE endpoint MUST NOT exceed the peer's stated window size for - transmitted IKE requests. In other words, if the responder stated - its window size is N, then when the initiator needs to make a request - X, it MUST wait until it has received responses to all requests up - through request X-N. An IKE endpoint MUST keep a copy of (or be able - to regenerate exactly) each request it has sent until it receives the - corresponding response. An IKE endpoint MUST keep a copy of (or be - able to regenerate exactly) the number of previous responses equal to - its declared window size in case its response was lost and the - initiator requests its retransmission by retransmitting the request. - - An IKE endpoint supporting a window size greater than one ought to be - capable of processing incoming requests out of order to maximize - performance in the event of network failures or packet reordering. - - {{ Clarif-7.3 }} The window size is normally a (possibly - configurable) property of a particular implementation, and is not - related to congestion control (unlike the window size in TCP, for - example). In particular, it is not defined what the responder should - do when it receives a SET_WINDOW_SIZE notification containing a - smaller value than is currently in effect. Thus, there is currently - no way to reduce the window size of an existing IKE_SA; you can only - increase it. When rekeying an IKE_SA, the new IKE_SA starts with - window size 1 until it is explicitly increased by sending a new - SET_WINDOW_SIZE notification. - -2.4. State Synchronization and Connection Timeouts - - An IKE endpoint is allowed to forget all of its state associated with - an IKE_SA and the collection of corresponding CHILD_SAs at any time. - This is the anticipated behavior in the event of an endpoint crash - and restart. It is important when an endpoint either fails or - - - -Kaufman, et al. Expires August 27, 2006 [Page 21] - -Internet-Draft IKEv2bis February 2006 - - - reinitializes its state that the other endpoint detect those - conditions and not continue to waste network bandwidth by sending - packets over discarded SAs and having them fall into a black hole. - - Since IKE is designed to operate in spite of Denial of Service (DoS) - attacks from the network, an endpoint MUST NOT conclude that the - other endpoint has failed based on any routing information (e.g., - ICMP messages) or IKE messages that arrive without cryptographic - protection (e.g., Notify messages complaining about unknown SPIs). - An endpoint MUST conclude that the other endpoint has failed only - when repeated attempts to contact it have gone unanswered for a - timeout period or when a cryptographically protected INITIAL_CONTACT - notification is received on a different IKE_SA to the same - authenticated identity. {{ Demoted the SHOULD }} An endpoint should - suspect that the other endpoint has failed based on routing - information and initiate a request to see whether the other endpoint - is alive. To check whether the other side is alive, IKE specifies an - empty INFORMATIONAL message that (like all IKE requests) requires an - acknowledgement (note that within the context of an IKE_SA, an - "empty" message consists of an IKE header followed by an Encrypted - payload that contains no payloads). If a cryptographically protected - message has been received from the other side recently, unprotected - notifications MAY be ignored. Implementations MUST limit the rate at - which they take actions based on unprotected messages. - - Numbers of retries and lengths of timeouts are not covered in this - specification because they do not affect interoperability. It is - suggested that messages be retransmitted at least a dozen times over - a period of at least several minutes before giving up on an SA, but - different environments may require different rules. To be a good - network citizen, retranmission times MUST increase exponentially to - avoid flooding the network and making an existing congestion - situation worse. If there has only been outgoing traffic on all of - the SAs associated with an IKE_SA, it is essential to confirm - liveness of the other endpoint to avoid black holes. If no - cryptographically protected messages have been received on an IKE_SA - or any of its CHILD_SAs recently, the system needs to perform a - liveness check in order to prevent sending messages to a dead peer. - Receipt of a fresh cryptographically protected message on an IKE_SA - or any of its CHILD_SAs ensures liveness of the IKE_SA and all of its - CHILD_SAs. Note that this places requirements on the failure modes - of an IKE endpoint. An implementation MUST NOT continue sending on - any SA if some failure prevents it from receiving on all of the - associated SAs. If CHILD_SAs can fail independently from one another - without the associated IKE_SA being able to send a delete message, - then they MUST be negotiated by separate IKE_SAs. - - There is a Denial of Service attack on the initiator of an IKE_SA - - - -Kaufman, et al. Expires August 27, 2006 [Page 22] - -Internet-Draft IKEv2bis February 2006 - - - that can be avoided if the initiator takes the proper care. Since - the first two messages of an SA setup are not cryptographically - protected, an attacker could respond to the initiator's message - before the genuine responder and poison the connection setup attempt. - To prevent this, the initiator MAY be willing to accept multiple - responses to its first message, treat each as potentially legitimate, - respond to it, and then discard all the invalid half-open connections - when it receives a valid cryptographically protected response to any - one of its requests. Once a cryptographically valid response is - received, all subsequent responses should be ignored whether or not - they are cryptographically valid. - - Note that with these rules, there is no reason to negotiate and agree - upon an SA lifetime. If IKE presumes the partner is dead, based on - repeated lack of acknowledgement to an IKE message, then the IKE SA - and all CHILD_SAs set up through that IKE_SA are deleted. - - An IKE endpoint may at any time delete inactive CHILD_SAs to recover - resources used to hold their state. If an IKE endpoint chooses to - delete CHILD_SAs, it MUST send Delete payloads to the other end - notifying it of the deletion. It MAY similarly time out the IKE_SA. - {{ Clarified the SHOULD }} Closing the IKE_SA implicitly closes all - associated CHILD_SAs. In this case, an IKE endpoint SHOULD send a - Delete payload indicating that it has closed the IKE_SA unless the - other endpoint is no longer responding. - -2.5. Version Numbers and Forward Compatibility - - This document describes version 2.0 of IKE, meaning the major version - number is 2 and the minor version number is 0. {{ Restated the - relationship to RFC 4306 }} This document is a clarification of - [IKEV2]. It is likely that some implementations will want to support - version 1.0 and version 2.0, and in the future, other versions. - - The major version number should be incremented only if the packet - formats or required actions have changed so dramatically that an - older version node would not be able to interoperate with a newer - version node if it simply ignored the fields it did not understand - and took the actions specified in the older specification. The minor - version number indicates new capabilities, and MUST be ignored by a - node with a smaller minor version number, but used for informational - purposes by the node with the larger minor version number. For - example, it might indicate the ability to process a newly defined - notification message. The node with the larger minor version number - would simply note that its correspondent would not be able to - understand that message and therefore would not send it. - - If an endpoint receives a message with a higher major version number, - - - -Kaufman, et al. Expires August 27, 2006 [Page 23] - -Internet-Draft IKEv2bis February 2006 - - - it MUST drop the message and SHOULD send an unauthenticated - notification message containing the highest version number it - supports. If an endpoint supports major version n, and major version - m, it MUST support all versions between n and m. If it receives a - message with a major version that it supports, it MUST respond with - that version number. In order to prevent two nodes from being - tricked into corresponding with a lower major version number than the - maximum that they both support, IKE has a flag that indicates that - the node is capable of speaking a higher major version number. - - Thus, the major version number in the IKE header indicates the - version number of the message, not the highest version number that - the transmitter supports. If the initiator is capable of speaking - versions n, n+1, and n+2, and the responder is capable of speaking - versions n and n+1, then they will negotiate speaking n+1, where the - initiator will set the flag indicating its ability to speak a higher - version. If they mistakenly (perhaps through an active attacker - sending error messages) negotiate to version n, then both will notice - that the other side can support a higher version number, and they - MUST break the connection and reconnect using version n+1. - - Note that IKEv1 does not follow these rules, because there is no way - in v1 of noting that you are capable of speaking a higher version - number. So an active attacker can trick two v2-capable nodes into - speaking v1. {{ Demoted the SHOULD }} When a v2-capable node - negotiates down to v1, it should note that fact in its logs. - - Also for forward compatibility, all fields marked RESERVED MUST be - set to zero by an implementation running version 2.0 or later, and - their content MUST be ignored by an implementation running version - 2.0 or later ("Be conservative in what you send and liberal in what - you receive"). In this way, future versions of the protocol can use - those fields in a way that is guaranteed to be ignored by - implementations that do not understand them. Similarly, payload - types that are not defined are reserved for future use; - implementations of a version where they are undefined MUST skip over - those payloads and ignore their contents. - - IKEv2 adds a "critical" flag to each payload header for further - flexibility for forward compatibility. If the critical flag is set - and the payload type is unrecognized, the message MUST be rejected - and the response to the IKE request containing that payload MUST - include a Notify payload UNSUPPORTED_CRITICAL_PAYLOAD, indicating an - unsupported critical payload was included. If the critical flag is - not set and the payload type is unsupported, that payload MUST be - ignored. - - {{ Demoted the SHOULD in the second clause }}Although new payload - - - -Kaufman, et al. Expires August 27, 2006 [Page 24] - -Internet-Draft IKEv2bis February 2006 - - - types may be added in the future and may appear interleaved with the - fields defined in this specification, implementations MUST send the - payloads defined in this specification in the order shown in the - figures in Section 2; implementations are explicitly allowed to - reject as invalid a message with those payloads in any other order. - -2.6. Cookies - - The term "cookies" originates with Karn and Simpson [PHOTURIS] in - Photuris, an early proposal for key management with IPsec, and it has - persisted. The Internet Security Association and Key Management - Protocol (ISAKMP) [ISAKMP] fixed message header includes two eight- - octet fields titled "cookies", and that syntax is used by both IKEv1 - and IKEv2 though in IKEv2 they are referred to as the IKE SPI and - there is a new separate field in a Notify payload holding the cookie. - The initial two eight-octet fields in the header are used as a - connection identifier at the beginning of IKE packets. {{ Demoted the - SHOULD }} Each endpoint chooses one of the two SPIs and needs to - choose them so as to be unique identifiers of an IKE_SA. An SPI - value of zero is special and indicates that the remote SPI value is - not yet known by the sender. - - Unlike ESP and AH where only the recipient's SPI appears in the - header of a message, in IKE the sender's SPI is also sent in every - message. Since the SPI chosen by the original initiator of the - IKE_SA is always sent first, an endpoint with multiple IKE_SAs open - that wants to find the appropriate IKE_SA using the SPI it assigned - must look at the I(nitiator) Flag bit in the header to determine - whether it assigned the first or the second eight octets. - - In the first message of an initial IKE exchange, the initiator will - not know the responder's SPI value and will therefore set that field - to zero. - - An expected attack against IKE is state and CPU exhaustion, where the - target is flooded with session initiation requests from forged IP - addresses. This attack can be made less effective if an - implementation of a responder uses minimal CPU and commits no state - to an SA until it knows the initiator can receive packets at the - address from which it claims to be sending them. To accomplish this, - a responder SHOULD -- when it detects a large number of half-open - IKE_SAs -- reject initial IKE messages unless they contain a Notify - payload of type COOKIE. {{ Clarified the SHOULD }} If the responder - wants to set up an SA, it SHOULD instead send an unprotected IKE - message as a response and include COOKIE Notify payload with the - cookie data to be returned. Initiators who receive such responses - MUST retry the IKE_SA_INIT with a Notify payload of type COOKIE - containing the responder supplied cookie data as the first payload - - - -Kaufman, et al. Expires August 27, 2006 [Page 25] - -Internet-Draft IKEv2bis February 2006 - - - and all other payloads unchanged. The initial exchange will then be - as follows: - - Initiator Responder - ------------------------------------------------------------------- - HDR(A,0), SAi1, KEi, Ni --> - <-- HDR(A,0), N(COOKIE) - HDR(A,0), N(COOKIE), SAi1, - KEi, Ni --> - <-- HDR(A,B), SAr1, KEr, - Nr, [CERTREQ] - HDR(A,B), SK {IDi, [CERT,] - [CERTREQ,] [IDr,] AUTH, - SAi2, TSi, TSr} --> - <-- HDR(A,B), SK {IDr, [CERT,] - AUTH, SAr2, TSi, TSr} - - The first two messages do not affect any initiator or responder state - except for communicating the cookie. In particular, the message - sequence numbers in the first four messages will all be zero and the - message sequence numbers in the last two messages will be one. 'A' - is the SPI assigned by the initiator, while 'B' is the SPI assigned - by the responder. - - {{ Clarif-2.1 }} Because the responder's SPI identifies security- - related state held by the responder, and in this case no state is - created, the responder sends a zero value for the responder's SPI. - - {{ Demoted the SHOULD }} An IKE implementation should implement its - responder cookie generation in such a way as to not require any saved - state to recognize its valid cookie when the second IKE_SA_INIT - message arrives. The exact algorithms and syntax they use to - generate cookies do not affect interoperability and hence are not - specified here. The following is an example of how an endpoint could - use cookies to implement limited DOS protection. - - A good way to do this is to set the responder cookie to be: - - Cookie = <VersionIDofSecret> | Hash(Ni | IPi | SPIi | <secret>) - - where <secret> is a randomly generated secret known only to the - responder and periodically changed and | indicates concatenation. - <VersionIDofSecret> should be changed whenever <secret> is - regenerated. The cookie can be recomputed when the IKE_SA_INIT - arrives the second time and compared to the cookie in the received - message. If it matches, the responder knows that the cookie was - generated since the last change to <secret> and that IPi must be the - same as the source address it saw the first time. Incorporating SPIi - - - -Kaufman, et al. Expires August 27, 2006 [Page 26] - -Internet-Draft IKEv2bis February 2006 - - - into the calculation ensures that if multiple IKE_SAs are being set - up in parallel they will all get different cookies (assuming the - initiator chooses unique SPIi's). Incorporating Ni into the hash - ensures that an attacker who sees only message 2 can't successfully - forge a message 3. - - If a new value for <secret> is chosen while there are connections in - the process of being initialized, an IKE_SA_INIT might be returned - with other than the current <VersionIDofSecret>. The responder in - that case MAY reject the message by sending another response with a - new cookie or it MAY keep the old value of <secret> around for a - short time and accept cookies computed from either one. {{ Demoted - the SHOULD NOT }} The responder should not accept cookies - indefinitely after <secret> is changed, since that would defeat part - of the denial of service protection. {{ Demoted the SHOULD }} The - responder should change the value of <secret> frequently, especially - if under attack. - - {{ Clarif-2.1 }} In addition to cookies, there are several cases - where the IKE_SA_INIT exchange does not result in the creation of an - IKE_SA (such as INVALID_KE_PAYLOAD or NO_PROPOSAL_CHOSEN). In such a - case, sending a zero value for the Responder's SPI is correct. If - the responder sends a non-zero responder SPI, the initiator should - not reject the response for only that reason. - - {{ Clarif-2.5 }} When one party receives an IKE_SA_INIT request - containing a cookie whose contents do not match the value expected, - that party MUST ignore the cookie and process the message as if no - cookie had been included; usually this means sending a response - containing a new cookie. - -2.6.1. Interaction of COOKIE and INVALID_KE_PAYLOAD - - {{ This section added by Clarif-2.4 }} - - There are two common reasons why the initiator may have to retry the - IKE_SA_INIT exchange: the responder requests a cookie or wants a - different Diffie-Hellman group than was included in the KEi payload. - If the initiator receives a cookie from the responder, the initiator - needs to decide whether or not to include the cookie in only the next - retry of the IKE_SA_INIT request, or in all subsequent retries as - well. - - If the initiator includes the cookie only in the next retry, one - additional roundtrip may be needed in some cases. An additional - roundtrip is needed also if the initiator includes the cookie in all - retries, but the responder does not support this. For instance, if - the responder includes the SAi1 and KEi payloads in cookie - - - -Kaufman, et al. Expires August 27, 2006 [Page 27] - -Internet-Draft IKEv2bis February 2006 - - - calculation, it will reject the request by sending a new cookie. - - If both peers support including the cookie in all retries, a slightly - shorter exchange can happen. Implementations SHOULD support this - shorter exchange, but MUST NOT fail if other implementations do not - support this shorter exchange. - -2.7. Cryptographic Algorithm Negotiation - - The payload type known as "SA" indicates a proposal for a set of - choices of IPsec protocols (IKE, ESP, and/or AH) for the SA as well - as cryptographic algorithms associated with each protocol. - - An SA payload consists of one or more proposals. Each proposal - includes one or more protocols (usually one). Each protocol contains - one or more transforms -- each specifying a cryptographic algorithm. - Each transform contains zero or more attributes (attributes are - needed only if the transform identifier does not completely specify - the cryptographic algorithm). - - This hierarchical structure was designed to efficiently encode - proposals for cryptographic suites when the number of supported - suites is large because multiple values are acceptable for multiple - transforms. The responder MUST choose a single suite, which MAY be - any subset of the SA proposal following the rules below: - - Each proposal contains one or more protocols. If a proposal is - accepted, the SA response MUST contain the same protocols in the same - order as the proposal. The responder MUST accept a single proposal - or reject them all and return an error. (Example: if a single - proposal contains ESP and AH and that proposal is accepted, both ESP - and AH MUST be accepted. If ESP and AH are included in separate - proposals, the responder MUST accept only one of them). - - Each IPsec protocol proposal contains one or more transforms. Each - transform contains a transform type. The accepted cryptographic - suite MUST contain exactly one transform of each type included in the - proposal. For example: if an ESP proposal includes transforms - ENCR_3DES, ENCR_AES w/keysize 128, ENCR_AES w/keysize 256, - AUTH_HMAC_MD5, and AUTH_HMAC_SHA, the accepted suite MUST contain one - of the ENCR_ transforms and one of the AUTH_ transforms. Thus, six - combinations are acceptable. - - Since the initiator sends its Diffie-Hellman value in the - IKE_SA_INIT, it must guess the Diffie-Hellman group that the - responder will select from its list of supported groups. If the - initiator guesses wrong, the responder will respond with a Notify - payload of type INVALID_KE_PAYLOAD indicating the selected group. In - - - -Kaufman, et al. Expires August 27, 2006 [Page 28] - -Internet-Draft IKEv2bis February 2006 - - - this case, the initiator MUST retry the IKE_SA_INIT with the - corrected Diffie-Hellman group. The initiator MUST again propose its - full set of acceptable cryptographic suites because the rejection - message was unauthenticated and otherwise an active attacker could - trick the endpoints into negotiating a weaker suite than a stronger - one that they both prefer. - -2.8. Rekeying - - {{ Demoted the SHOULD }} IKE, ESP, and AH security associations use - secret keys that should be used only for a limited amount of time and - to protect a limited amount of data. This limits the lifetime of the - entire security association. When the lifetime of a security - association expires, the security association MUST NOT be used. If - there is demand, new security associations MAY be established. - Reestablishment of security associations to take the place of ones - that expire is referred to as "rekeying". - - To allow for minimal IPsec implementations, the ability to rekey SAs - without restarting the entire IKE_SA is optional. An implementation - MAY refuse all CREATE_CHILD_SA requests within an IKE_SA. If an SA - has expired or is about to expire and rekeying attempts using the - mechanisms described here fail, an implementation MUST close the - IKE_SA and any associated CHILD_SAs and then MAY start new ones. {{ - Demoted the SHOULD }} Implementations may wish to support in-place - rekeying of SAs, since doing so offers better performance and is - likely to reduce the number of packets lost during the transition. - - To rekey a CHILD_SA within an existing IKE_SA, create a new, - equivalent SA (see Section 2.17 below), and when the new one is - established, delete the old one. To rekey an IKE_SA, establish a new - equivalent IKE_SA (see Section 2.18 below) with the peer to whom the - old IKE_SA is shared using a CREATE_CHILD_SA within the existing - IKE_SA. An IKE_SA so created inherits all of the original IKE_SA's - CHILD_SAs. Use the new IKE_SA for all control messages needed to - maintain the CHILD_SAs created by the old IKE_SA, and delete the old - IKE_SA. The Delete payload to delete itself MUST be the last request - sent over an IKE_SA. - - {{ Demoted the SHOULD }} SAs should be rekeyed proactively, i.e., the - new SA should be established before the old one expires and becomes - unusable. Enough time should elapse between the time the new SA is - established and the old one becomes unusable so that traffic can be - switched over to the new SA. - - A difference between IKEv1 and IKEv2 is that in IKEv1 SA lifetimes - were negotiated. In IKEv2, each end of the SA is responsible for - enforcing its own lifetime policy on the SA and rekeying the SA when - - - -Kaufman, et al. Expires August 27, 2006 [Page 29] - -Internet-Draft IKEv2bis February 2006 - - - necessary. If the two ends have different lifetime policies, the end - with the shorter lifetime will end up always being the one to request - the rekeying. If an SA bundle has been inactive for a long time and - if an endpoint would not initiate the SA in the absence of traffic, - the endpoint MAY choose to close the SA instead of rekeying it when - its lifetime expires. {{ Demoted the SHOULD }} It should do so if - there has been no traffic since the last time the SA was rekeyed. - - Note that IKEv2 deliberately allows parallel SAs with the same - traffic selectors between common endpoints. One of the purposes of - this is to support traffic quality of service (QoS) differences among - the SAs (see [DIFFSERVFIELD], [DIFFSERVARCH], and section 4.1 of - [DIFFTUNNEL]). Hence unlike IKEv1, the combination of the endpoints - and the traffic selectors may not uniquely identify an SA between - those endpoints, so the IKEv1 rekeying heuristic of deleting SAs on - the basis of duplicate traffic selectors SHOULD NOT be used. - - {{ Demoted the SHOULD }} The node that initiated the surviving - rekeyed SA should delete the replaced SA after the new one is - established. - - There are timing windows -- particularly in the presence of lost - packets -- where endpoints may not agree on the state of an SA. The - responder to a CREATE_CHILD_SA MUST be prepared to accept messages on - an SA before sending its response to the creation request, so there - is no ambiguity for the initiator. The initiator MAY begin sending - on an SA as soon as it processes the response. The initiator, - however, cannot receive on a newly created SA until it receives and - processes the response to its CREATE_CHILD_SA request. How, then, is - the responder to know when it is OK to send on the newly created SA? - - From a technical correctness and interoperability perspective, the - responder MAY begin sending on an SA as soon as it sends its response - to the CREATE_CHILD_SA request. In some situations, however, this - could result in packets unnecessarily being dropped, so an - implementation MAY want to defer such sending. - - The responder can be assured that the initiator is prepared to - receive messages on an SA if either (1) it has received a - cryptographically valid message on the new SA, or (2) the new SA - rekeys an existing SA and it receives an IKE request to close the - replaced SA. When rekeying an SA, the responder continues to send - traffic on the old SA until one of those events occurs. When - establishing a new SA, the responder MAY defer sending messages on a - new SA until either it receives one or a timeout has occurred. {{ - Demoted the SHOULD }} If an initiator receives a message on an SA for - which it has not received a response to its CREATE_CHILD_SA request, - it interprets that as a likely packet loss and retransmits the - - - -Kaufman, et al. Expires August 27, 2006 [Page 30] - -Internet-Draft IKEv2bis February 2006 - - - CREATE_CHILD_SA request. An initiator MAY send a dummy message on a - newly created SA if it has no messages queued in order to assure the - responder that the initiator is ready to receive messages. - - {{ Clarif-5.9 }} Throughout this document, "initiator" refers to the - party who initiated the exchange being described, and "original - initiator" refers to the party who initiated the whole IKE_SA. The - "original initiator" always refers to the party who initiated the - exchange which resulted in the current IKE_SA. In other words, if - the the "original responder" starts rekeying the IKE_SA, that party - becomes the "original initiator" of the new IKE_SA. - -2.8.1. Simultaneous CHILD_SA rekeying - - {{ The first two paragraphs were moved, and the rest was added, based - on Clarif-5.11 }} - - If the two ends have the same lifetime policies, it is possible that - both will initiate a rekeying at the same time (which will result in - redundant SAs). To reduce the probability of this happening, the - timing of rekeying requests SHOULD be jittered (delayed by a random - amount of time after the need for rekeying is noticed). - - This form of rekeying may temporarily result in multiple similar SAs - between the same pairs of nodes. When there are two SAs eligible to - receive packets, a node MUST accept incoming packets through either - SA. If redundant SAs are created though such a collision, the SA - created with the lowest of the four nonces used in the two exchanges - SHOULD be closed by the endpoint that created it. {{ Clarif-5.10 }} - "Lowest" means an octet-by-octet, lexicographical comparison (instead - of, for instance, comparing the nonces as large integers). In other - words, start by comparing the first octet; if they're equal, move to - the next octet, and so on. If you reach the end of one nonce, that - nonce is the lower one. - - The following is an explanation on the impact this has on - implementations. Assume that hosts A and B have an existing IPsec SA - pair with SPIs (SPIa1,SPIb1), and both start rekeying it at the same - time: - - Host A Host B - ------------------------------------------------------------------- - send req1: N(REKEY_SA,SPIa1), - SA(..,SPIa2,..),Ni1,.. --> - <-- send req2: N(REKEY_SA,SPIb1), - SA(..,SPIb2,..),Ni2 - recv req2 <-- - - - - -Kaufman, et al. Expires August 27, 2006 [Page 31] - -Internet-Draft IKEv2bis February 2006 - - - At this point, A knows there is a simultaneous rekeying going on. - However, it cannot yet know which of the exchanges will have the - lowest nonce, so it will just note the situation and respond as - usual. - - send resp2: SA(..,SPIa3,..), - Nr1,.. --> - --> recv req1 - - Now B also knows that simultaneous rekeying is going on. It responds - as usual. - - <-- send resp1: SA(..,SPIb3,..), - Nr2,.. - recv resp1 <-- - --> recv resp2 - - At this point, there are three CHILD_SA pairs between A and B (the - old one and two new ones). A and B can now compare the nonces. - Suppose that the lowest nonce was Nr1 in message resp2; in this case, - B (the sender of req2) deletes the redundant new SA, and A (the node - that initiated the surviving rekeyed SA), deletes the old one. - - send req3: D(SPIa1) --> - <-- send req4: D(SPIb2) - --> recv req3 - <-- send resp4: D(SPIb1) - recv req4 <-- - send resp4: D(SPIa3) --> - - The rekeying is now finished. - - However, there is a second possible sequence of events that can - happen if some packets are lost in the network, resulting in - retransmissions. The rekeying begins as usual, but A's first packet - (req1) is lost. - - - - - - - - - - - - - - - -Kaufman, et al. Expires August 27, 2006 [Page 32] - -Internet-Draft IKEv2bis February 2006 - - - Host A Host B - ------------------------------------------------------------------- - send req1: N(REKEY_SA,SPIa1), - SA(..,SPIa2,..), - Ni1,.. --> (lost) - <-- send req2: N(REKEY_SA,SPIb1), - SA(..,SPIb2,..),Ni2 - recv req2 <-- - send resp2: SA(..,SPIa3,..), - Nr1,.. --> - --> recv resp2 - <-- send req3: D(SPIb1) - recv req3 <-- - send resp3: D(SPIa1) --> - --> recv resp3 - - From B's point of view, the rekeying is now completed, and since it - has not yet received A's req1, it does not even know that there was - simultaneous rekeying. However, A will continue retransmitting the - message, and eventually it will reach B. - - resend req1 --> - --> recv req1 - - To B, it looks like A is trying to rekey an SA that no longer exists; - thus, B responds to the request with something non-fatal such as - NO_PROPOSAL_CHOSEN. - - <-- send resp1: N(NO_PROPOSAL_CHOSEN) - recv resp1 <-- - - When A receives this error, it already knows there was simultaneous - rekeying, so it can ignore the error message. - -2.8.2. Rekeying the IKE_SA Versus Reauthentication - - {{ Added this section from Clarif-5.2 }} - - Rekeying the IKE_SA and reauthentication are different concepts in - IKEv2. Rekeying the IKE_SA establishes new keys for the IKE_SA and - resets the Message ID counters, but it does not authenticate the - parties again (no AUTH or EAP payloads are involved). - - Although rekeying the IKE_SA may be important in some environments, - reauthentication (the verification that the parties still have access - to the long-term credentials) is often more important. - - IKEv2 does not have any special support for reauthentication. - - - -Kaufman, et al. Expires August 27, 2006 [Page 33] - -Internet-Draft IKEv2bis February 2006 - - - Reauthentication is done by creating a new IKE_SA from scratch (using - IKE_SA_INIT/IKE_AUTH exchanges, without any REKEY_SA notify - payloads), creating new CHILD_SAs within the new IKE_SA (without - REKEY_SA notify payloads), and finally deleting the old IKE_SA (which - deletes the old CHILD_SAs as well). - - This means that reauthentication also establishes new keys for the - IKE_SA and CHILD_SAs. Therefore, while rekeying can be performed - more often than reauthentication, the situation where "authentication - lifetime" is shorter than "key lifetime" does not make sense. - - While creation of a new IKE_SA can be initiated by either party - (initiator or responder in the original IKE_SA), the use of EAP - authentication and/or configuration payloads means in practice that - reauthentication has to be initiated by the same party as the - original IKE_SA. IKEv2 does not currently allow the responder to - request reauthentication in this case; however, there is ongoing work - to add this functionality [REAUTH]. - -2.9. Traffic Selector Negotiation - - {{ Clarif-7.2 }} When an RFC4301-compliant IPsec subsystem receives - an IP packet and matches a "protect" selector in its Security Policy - Database (SPD), the subsystem protects that packet with IPsec. When - no SA exists yet, it is the task of IKE to create it. Maintenance of - a system's SPD is outside the scope of IKE (see [PFKEY] for an - example protocol), though some implementations might update their SPD - in connection with the running of IKE (for an example scenario, see - Section 1.1.3). - - Traffic Selector (TS) payloads allow endpoints to communicate some of - the information from their SPD to their peers. TS payloads specify - the selection criteria for packets that will be forwarded over the - newly set up SA. This can serve as a consistency check in some - scenarios to assure that the SPDs are consistent. In others, it - guides the dynamic update of the SPD. - - Two TS payloads appear in each of the messages in the exchange that - creates a CHILD_SA pair. Each TS payload contains one or more - Traffic Selectors. Each Traffic Selector consists of an address - range (IPv4 or IPv6), a port range, and an IP protocol ID. In - support of the scenario described in Section 1.1.3, an initiator may - request that the responder assign an IP address and tell the - initiator what it is. {{ Clarif-6.1 }} That request is done using - configuration payloads, not traffic selectors. An address in a TSi - payload in a response does not mean that the responder has assigned - that address to the initiator: it only means that if packets matching - these traffic selectors are sent by the initiator, IPsec processing - - - -Kaufman, et al. Expires August 27, 2006 [Page 34] - -Internet-Draft IKEv2bis February 2006 - - - can be performed as agreed for this SA. - - IKEv2 allows the responder to choose a subset of the traffic proposed - by the initiator. This could happen when the configurations of the - two endpoints are being updated but only one end has received the new - information. Since the two endpoints may be configured by different - people, the incompatibility may persist for an extended period even - in the absence of errors. It also allows for intentionally different - configurations, as when one end is configured to tunnel all addresses - and depends on the other end to have the up-to-date list. - - The first of the two TS payloads is known as TSi (Traffic Selector- - initiator). The second is known as TSr (Traffic Selector-responder). - TSi specifies the source address of traffic forwarded from (or the - destination address of traffic forwarded to) the initiator of the - CHILD_SA pair. TSr specifies the destination address of the traffic - forwarded to (or the source address of the traffic forwarded from) - the responder of the CHILD_SA pair. For example, if the original - initiator request the creation of a CHILD_SA pair, and wishes to - tunnel all traffic from subnet 192.0.1.* on the initiator's side to - subnet 192.0.2.* on the responder's side, the initiator would include - a single traffic selector in each TS payload. TSi would specify the - address range (192.0.1.0 - 192.0.1.255) and TSr would specify the - address range (192.0.2.0 - 192.0.2.255). Assuming that proposal was - acceptable to the responder, it would send identical TS payloads - back. (Note: The IP address range 192.0.2.* has been reserved for - use in examples in RFCs and similar documents. This document needed - two such ranges, and so also used 192.0.1.*. This should not be - confused with any actual address.) - - The responder is allowed to narrow the choices by selecting a subset - of the traffic, for instance by eliminating or narrowing the range of - one or more members of the set of traffic selectors, provided the set - does not become the NULL set. - - It is possible for the responder's policy to contain multiple smaller - ranges, all encompassed by the initiator's traffic selector, and with - the responder's policy being that each of those ranges should be sent - over a different SA. Continuing the example above, the responder - might have a policy of being willing to tunnel those addresses to and - from the initiator, but might require that each address pair be on a - separately negotiated CHILD_SA. If the initiator generated its - request in response to an incoming packet from 192.0.1.43 to - 192.0.2.123, there would be no way for the responder to determine - which pair of addresses should be included in this tunnel, and it - would have to make a guess or reject the request with a status of - SINGLE_PAIR_REQUIRED. - - - - -Kaufman, et al. Expires August 27, 2006 [Page 35] - -Internet-Draft IKEv2bis February 2006 - - - {{ Clarif-4.11 }} Few implementations will have policies that require - separate SAs for each address pair. Because of this, if only some - part (or parts) of the TSi/TSr proposed by the initiator is (are) - acceptable to the responder, responders SHOULD narrow TSi/TSr to an - acceptable subset rather than use SINGLE_PAIR_REQUIRED. - - To enable the responder to choose the appropriate range in this case, - if the initiator has requested the SA due to a data packet, the - initiator SHOULD include as the first traffic selector in each of TSi - and TSr a very specific traffic selector including the addresses in - the packet triggering the request. In the example, the initiator - would include in TSi two traffic selectors: the first containing the - address range (192.0.1.43 - 192.0.1.43) and the source port and IP - protocol from the packet and the second containing (192.0.1.0 - - 192.0.1.255) with all ports and IP protocols. The initiator would - similarly include two traffic selectors in TSr. - - If the responder's policy does not allow it to accept the entire set - of traffic selectors in the initiator's request, but does allow him - to accept the first selector of TSi and TSr, then the responder MUST - narrow the traffic selectors to a subset that includes the - initiator's first choices. In this example, the responder might - respond with TSi being (192.0.1.43 - 192.0.1.43) with all ports and - IP protocols. - - If the initiator creates the CHILD_SA pair not in response to an - arriving packet, but rather, say, upon startup, then there may be no - specific addresses the initiator prefers for the initial tunnel over - any other. In that case, the first values in TSi and TSr MAY be - ranges rather than specific values, and the responder chooses a - subset of the initiator's TSi and TSr that are acceptable. If more - than one subset is acceptable but their union is not, the responder - MUST accept some subset and MAY include a Notify payload of type - ADDITIONAL_TS_POSSIBLE to indicate that the initiator might want to - try again. This case will occur only when the initiator and - responder are configured differently from one another. If the - initiator and responder agree on the granularity of tunnels, the - initiator will never request a tunnel wider than the responder will - accept. {{ Demoted the SHOULD }} Such misconfigurations should be - recorded in error logs. - - {{ Clarif-4.10 }} A concise summary of the narrowing process is: - - o If the responder's policy does not allow any part of the traffic - covered by TSi/TSr, it responds with TS_UNACCEPTABLE. - - o If the responder's policy allows the entire set of traffic covered - by TSi/TSr, no narrowing is necessary, and the responder can - - - -Kaufman, et al. Expires August 27, 2006 [Page 36] - -Internet-Draft IKEv2bis February 2006 - - - return the same TSi/TSr values. - - o Otherwise, narrowing is needed. If the responder's policy allows - all traffic covered by TSi[1]/TSr[1] (the first traffic selectors - in TSi/TSr) but not entire TSi/TSr, the responder narrows to an - acceptable subset of TSi/TSr that includes TSi[1]/TSr[1]. - - o If the responder's policy does not allow all traffic covered by - TSi[1]/TSr[1], but does allow some parts of TSi/TSr, it narrows to - an acceptable subset of TSi/TSr. - - In the last two cases, there may be several subsets that are - acceptable (but their union is not); in this case, the responder - arbitrarily chooses one of them, and includes ADDITIONAL_TS_POSSIBLE - notification in the response. - -2.9.1. Traffic Selectors Violating Own Policy - - {{ Clarif-4.12 }} - - When creating a new SA, the initiator needs to avoid proposing - traffic selectors that violate its own policy. If this rule is not - followed, valid traffic may be dropped. - - This is best illustrated by an example. Suppose that host A has a - policy whose effect is that traffic to 192.0.1.66 is sent via host B - encrypted using AES, and traffic to all other hosts in 192.0.1.0/24 - is also sent via B, but must use 3DES. Suppose also that host B - accepts any combination of AES and 3DES. - - If host A now proposes an SA that uses 3DES, and includes TSr - containing (192.0.1.0-192.0.1.0.255), this will be accepted by host - B. Now, host B can also use this SA to send traffic from 192.0.1.66, - but those packets will be dropped by A since it requires the use of - AES for those traffic. Even if host A creates a new SA only for - 192.0.1.66 that uses AES, host B may freely continue to use the first - SA for the traffic. In this situation, when proposing the SA, host A - should have followed its own policy, and included a TSr containing - ((192.0.1.0-192.0.1.65),(192.0.1.67-192.0.1.255)) instead. - - In general, if (1) the initiator makes a proposal "for traffic X - (TSi/TSr), do SA", and (2) for some subset X' of X, the initiator - does not actually accept traffic X' with SA, and (3) the initiator - would be willing to accept traffic X' with some SA' (!=SA), valid - traffic can be unnecessarily dropped since the responder can apply - either SA or SA' to traffic X'. - - - - - -Kaufman, et al. Expires August 27, 2006 [Page 37] - -Internet-Draft IKEv2bis February 2006 - - -2.10. Nonces - - The IKE_SA_INIT messages each contain a nonce. These nonces are used - as inputs to cryptographic functions. The CREATE_CHILD_SA request - and the CREATE_CHILD_SA response also contain nonces. These nonces - are used to add freshness to the key derivation technique used to - obtain keys for CHILD_SA, and to ensure creation of strong pseudo- - random bits from the Diffie-Hellman key. Nonces used in IKEv2 MUST - be randomly chosen, MUST be at least 128 bits in size, and MUST be at - least half the key size of the negotiated prf. ("prf" refers to - "pseudo-random function", one of the cryptographic algorithms - negotiated in the IKE exchange.) {{ Clarif-7.4 }} However, the - initiator chooses the nonce before the outcome of the negotiation is - known. Because of that, the nonce has to be long enough for all the - PRFs being proposed. If the same random number source is used for - both keys and nonces, care must be taken to ensure that the latter - use does not compromise the former. - -2.11. Address and Port Agility - - IKE runs over UDP ports 500 and 4500, and implicitly sets up ESP and - AH associations for the same IP addresses it runs over. The IP - addresses and ports in the outer header are, however, not themselves - cryptographically protected, and IKE is designed to work even through - Network Address Translation (NAT) boxes. An implementation MUST - accept incoming requests even if the source port is not 500 or 4500, - and MUST respond to the address and port from which the request was - received. It MUST specify the address and port at which the request - was received as the source address and port in the response. IKE - functions identically over IPv4 or IPv6. - -2.12. Reuse of Diffie-Hellman Exponentials - - IKE generates keying material using an ephemeral Diffie-Hellman - exchange in order to gain the property of "perfect forward secrecy". - This means that once a connection is closed and its corresponding - keys are forgotten, even someone who has recorded all of the data - from the connection and gets access to all of the long-term keys of - the two endpoints cannot reconstruct the keys used to protect the - conversation without doing a brute force search of the session key - space. - - Achieving perfect forward secrecy requires that when a connection is - closed, each endpoint MUST forget not only the keys used by the - connection but also any information that could be used to recompute - those keys. In particular, it MUST forget the secrets used in the - Diffie-Hellman calculation and any state that may persist in the - state of a pseudo-random number generator that could be used to - - - -Kaufman, et al. Expires August 27, 2006 [Page 38] - -Internet-Draft IKEv2bis February 2006 - - - recompute the Diffie-Hellman secrets. - - Since the computing of Diffie-Hellman exponentials is computationally - expensive, an endpoint may find it advantageous to reuse those - exponentials for multiple connection setups. There are several - reasonable strategies for doing this. An endpoint could choose a new - exponential only periodically though this could result in less-than- - perfect forward secrecy if some connection lasts for less than the - lifetime of the exponential. Or it could keep track of which - exponential was used for each connection and delete the information - associated with the exponential only when some corresponding - connection was closed. This would allow the exponential to be reused - without losing perfect forward secrecy at the cost of maintaining - more state. - - Decisions as to whether and when to reuse Diffie-Hellman exponentials - is a private decision in the sense that it will not affect - interoperability. An implementation that reuses exponentials MAY - choose to remember the exponential used by the other endpoint on past - exchanges and if one is reused to avoid the second half of the - calculation. - -2.13. Generating Keying Material - - In the context of the IKE_SA, four cryptographic algorithms are - negotiated: an encryption algorithm, an integrity protection - algorithm, a Diffie-Hellman group, and a pseudo-random function - (prf). The pseudo-random function is used for the construction of - keying material for all of the cryptographic algorithms used in both - the IKE_SA and the CHILD_SAs. - - We assume that each encryption algorithm and integrity protection - algorithm uses a fixed-size key and that any randomly chosen value of - that fixed size can serve as an appropriate key. For algorithms that - accept a variable length key, a fixed key size MUST be specified as - part of the cryptographic transform negotiated. For algorithms for - which not all values are valid keys (such as DES or 3DES with key - parity), the algorithm by which keys are derived from arbitrary - values MUST be specified by the cryptographic transform. For - integrity protection functions based on Hashed Message Authentication - Code (HMAC), the fixed key size is the size of the output of the - underlying hash function. When the prf function takes a variable - length key, variable length data, and produces a fixed-length output - (e.g., when using HMAC), the formulas in this document apply. When - the key for the prf function has fixed length, the data provided as a - key is truncated or padded with zeros as necessary unless exceptional - processing is explained following the formula. - - - - -Kaufman, et al. Expires August 27, 2006 [Page 39] - -Internet-Draft IKEv2bis February 2006 - - - Keying material will always be derived as the output of the - negotiated prf algorithm. Since the amount of keying material needed - may be greater than the size of the output of the prf algorithm, we - will use the prf iteratively. We will use the terminology prf+ to - describe the function that outputs a pseudo-random stream based on - the inputs to a prf as follows: (where | indicates concatenation) - - prf+ (K,S) = T1 | T2 | T3 | T4 | ... - - where: - T1 = prf (K, S | 0x01) - T2 = prf (K, T1 | S | 0x02) - T3 = prf (K, T2 | S | 0x03) - T4 = prf (K, T3 | S | 0x04) - - continuing as needed to compute all required keys. The keys are - taken from the output string without regard to boundaries (e.g., if - the required keys are a 256-bit Advanced Encryption Standard (AES) - key and a 160-bit HMAC key, and the prf function generates 160 bits, - the AES key will come from T1 and the beginning of T2, while the HMAC - key will come from the rest of T2 and the beginning of T3). - - The constant concatenated to the end of each string feeding the prf - is a single octet. prf+ in this document is not defined beyond 255 - times the size of the prf output. - -2.14. Generating Keying Material for the IKE_SA - - The shared keys are computed as follows. A quantity called SKEYSEED - is calculated from the nonces exchanged during the IKE_SA_INIT - exchange and the Diffie-Hellman shared secret established during that - exchange. SKEYSEED is used to calculate seven other secrets: SK_d - used for deriving new keys for the CHILD_SAs established with this - IKE_SA; SK_ai and SK_ar used as a key to the integrity protection - algorithm for authenticating the component messages of subsequent - exchanges; SK_ei and SK_er used for encrypting (and of course - decrypting) all subsequent exchanges; and SK_pi and SK_pr, which are - used when generating an AUTH payload. - - SKEYSEED and its derivatives are computed as follows: - - SKEYSEED = prf(Ni | Nr, g^ir) - - {SK_d | SK_ai | SK_ar | SK_ei | SK_er | SK_pi | SK_pr } - = prf+ (SKEYSEED, Ni | Nr | SPIi | SPIr ) - - (indicating that the quantities SK_d, SK_ai, SK_ar, SK_ei, SK_er, - SK_pi, and SK_pr are taken in order from the generated bits of the - - - -Kaufman, et al. Expires August 27, 2006 [Page 40] - -Internet-Draft IKEv2bis February 2006 - - - prf+). g^ir is the shared secret from the ephemeral Diffie-Hellman - exchange. g^ir is represented as a string of octets in big endian - order padded with zeros if necessary to make it the length of the - modulus. Ni and Nr are the nonces, stripped of any headers. If the - negotiated prf takes a fixed-length key and the lengths of Ni and Nr - do not add up to that length, half the bits must come from Ni and - half from Nr, taking the first bits of each. - - The two directions of traffic flow use different keys. The keys used - to protect messages from the original initiator are SK_ai and SK_ei. - The keys used to protect messages in the other direction are SK_ar - and SK_er. Each algorithm takes a fixed number of bits of keying - material, which is specified as part of the algorithm. For integrity - algorithms based on a keyed hash, the key size is always equal to the - length of the output of the underlying hash function. - -2.15. Authentication of the IKE_SA - - When not using extensible authentication (see Section 2.16), the - peers are authenticated by having each sign (or MAC using a shared - secret as the key) a block of data. For the responder, the octets to - be signed start with the first octet of the first SPI in the header - of the second message and end with the last octet of the last payload - in the second message. Appended to this (for purposes of computing - the signature) are the initiator's nonce Ni (just the value, not the - payload containing it), and the value prf(SK_pr,IDr') where IDr' is - the responder's ID payload excluding the fixed header. Note that - neither the nonce Ni nor the value prf(SK_pr,IDr') are transmitted. - Similarly, the initiator signs the first message, starting with the - first octet of the first SPI in the header and ending with the last - octet of the last payload. Appended to this (for purposes of - computing the signature) are the responder's nonce Nr, and the value - prf(SK_pi,IDi'). In the above calculation, IDi' and IDr' are the - entire ID payloads excluding the fixed header. It is critical to the - security of the exchange that each side sign the other side's nonce. - - {{ Clarif-3.1 }} - - The initiator's signed octets can be described as: - - InitiatorSignedOctets = RealMessage1 | NonceRData | MACedIDForI - GenIKEHDR = [ four octets 0 if using port 4500 ] | RealIKEHDR - RealIKEHDR = SPIi | SPIr | . . . | Length - RealMessage1 = RealIKEHDR | RestOfMessage1 - NonceRPayload = PayloadHeader | NonceRData - InitiatorIDPayload = PayloadHeader | RestOfIDPayload - RestOfInitIDPayload = IDType | RESERVED | InitIDData - MACedIDForI = prf(SK_pi, RestOfInitIDPayload) - - - -Kaufman, et al. Expires August 27, 2006 [Page 41] - -Internet-Draft IKEv2bis February 2006 - - - The responder's signed octets can be described as: - - ResponderSignedOctets = RealMessage2 | NonceIData | MACedIDForR - GenIKEHDR = [ four octets 0 if using port 4500 ] | RealIKEHDR - RealIKEHDR = SPIi | SPIr | . . . | Length - RealMessage2 = RealIKEHDR | RestOfMessage2 - NonceIPayload = PayloadHeader | NonceIData - ResponderIDPayload = PayloadHeader | RestOfIDPayload - RestOfRespIDPayload = IDType | RESERVED | InitIDData - MACedIDForR = prf(SK_pr, RestOfRespIDPayload) - - Note that all of the payloads are included under the signature, - including any payload types not defined in this document. If the - first message of the exchange is sent twice (the second time with a - responder cookie and/or a different Diffie-Hellman group), it is the - second version of the message that is signed. - - Optionally, messages 3 and 4 MAY include a certificate, or - certificate chain providing evidence that the key used to compute a - digital signature belongs to the name in the ID payload. The - signature or MAC will be computed using algorithms dictated by the - type of key used by the signer, and specified by the Auth Method - field in the Authentication payload. There is no requirement that - the initiator and responder sign with the same cryptographic - algorithms. The choice of cryptographic algorithms depends on the - type of key each has. In particular, the initiator may be using a - shared key while the responder may have a public signature key and - certificate. It will commonly be the case (but it is not required) - that if a shared secret is used for authentication that the same key - is used in both directions. Note that it is a common but typically - insecure practice to have a shared key derived solely from a user- - chosen password without incorporating another source of randomness. - - This is typically insecure because user-chosen passwords are unlikely - to have sufficient unpredictability to resist dictionary attacks and - these attacks are not prevented in this authentication method. - (Applications using password-based authentication for bootstrapping - and IKE_SA should use the authentication method in Section 2.16, - which is designed to prevent off-line dictionary attacks.) {{ Demoted - the SHOULD }} The pre-shared key needs to contain as much - unpredictability as the strongest key being negotiated. In the case - of a pre-shared key, the AUTH value is computed as: - - AUTH = prf(prf(Shared Secret,"Key Pad for IKEv2"), <msg octets>) - - where the string "Key Pad for IKEv2" is 17 ASCII characters without - null termination. The shared secret can be variable length. The pad - string is added so that if the shared secret is derived from a - - - -Kaufman, et al. Expires August 27, 2006 [Page 42] - -Internet-Draft IKEv2bis February 2006 - - - password, the IKE implementation need not store the password in - cleartext, but rather can store the value prf(Shared Secret,"Key Pad - for IKEv2"), which could not be used as a password equivalent for - protocols other than IKEv2. As noted above, deriving the shared - secret from a password is not secure. This construction is used - because it is anticipated that people will do it anyway. The - management interface by which the Shared Secret is provided MUST - accept ASCII strings of at least 64 octets and MUST NOT add a null - terminator before using them as shared secrets. It MUST also accept - a hex encoding of the Shared Secret. The management interface MAY - accept other encodings if the algorithm for translating the encoding - to a binary string is specified. - - {{ Clarif-3.7 }} If the negotiated prf takes a fixed-size key, the - shared secret MUST be of that fixed size. This requirement means - that it is difficult to use these PRFs with shared key authentication - because it limits the shared secrets that can be used. Thus, PRFs - that require a fixed-size key SHOULD NOT be used with shared key - authentication. For example, PRF_AES128_CBC [PRFAES128CBC] - originally used fixed key sizes; that RFC has been updated to handle - variable key sizes in [PRFAES128CBC-bis]. Note that Section 2.13 - also contains text that is related to PRFs with fixed key size. - However, the text in that section applies only to the prf+ - construction. - -2.16. Extensible Authentication Protocol Methods - - In addition to authentication using public key signatures and shared - secrets, IKE supports authentication using methods defined in RFC - 3748 [EAP]. Typically, these methods are asymmetric (designed for a - user authenticating to a server), and they may not be mutual. {{ In - the next sentence, changed "public key signature based" to "strong" - }} For this reason, these protocols are typically used to - authenticate the initiator to the responder and MUST be used in - conjunction with a strong authentication of the responder to the - initiator. These methods are often associated with mechanisms - referred to as "Legacy Authentication" mechanisms. - - While this memo references [EAP] with the intent that new methods can - be added in the future without updating this specification, some - simpler variations are documented here and in Section 3.16. [EAP] - defines an authentication protocol requiring a variable number of - messages. Extensible Authentication is implemented in IKE as - additional IKE_AUTH exchanges that MUST be completed in order to - initialize the IKE_SA. - - An initiator indicates a desire to use extensible authentication by - leaving out the AUTH payload from message 3. By including an IDi - - - -Kaufman, et al. Expires August 27, 2006 [Page 43] - -Internet-Draft IKEv2bis February 2006 - - - payload but not an AUTH payload, the initiator has declared an - identity but has not proven it. If the responder is willing to use - an extensible authentication method, it will place an Extensible - Authentication Protocol (EAP) payload in message 4 and defer sending - SAr2, TSi, and TSr until initiator authentication is complete in a - subsequent IKE_AUTH exchange. In the case of a minimal extensible - authentication, the initial SA establishment will appear as follows: - - Initiator Responder - ------------------------------------------------------------------- - HDR, SAi1, KEi, Ni --> - <-- HDR, SAr1, KEr, Nr, [CERTREQ] - HDR, SK {IDi, [CERTREQ,] - [IDr,] SAi2, - TSi, TSr} --> - <-- HDR, SK {IDr, [CERT,] AUTH, - EAP } - HDR, SK {EAP} --> - <-- HDR, SK {EAP (success)} - HDR, SK {AUTH} --> - <-- HDR, SK {AUTH, SAr2, TSi, TSr } - - {{ Clarif-3.10 }} As described in Section 2.2, when EAP is used, each - pair of IKE_SA initial setup messages will have their message numbers - incremented; the first pair of AUTH messages will have an ID of 1, - the second will be 2, and so on. - - For EAP methods that create a shared key as a side effect of - authentication, that shared key MUST be used by both the initiator - and responder to generate AUTH payloads in messages 7 and 8 using the - syntax for shared secrets specified in Section 2.15. The shared key - from EAP is the field from the EAP specification named MSK. The - shared key generated during an IKE exchange MUST NOT be used for any - other purpose. - - EAP methods that do not establish a shared key SHOULD NOT be used, as - they are subject to a number of man-in-the-middle attacks [EAPMITM] - if these EAP methods are used in other protocols that do not use a - server-authenticated tunnel. Please see the Security Considerations - section for more details. If EAP methods that do not generate a - shared key are used, the AUTH payloads in messages 7 and 8 MUST be - generated using SK_pi and SK_pr, respectively. - - {{ Demoted the SHOULD }} The initiator of an IKE_SA using EAP needs - to be capable of extending the initial protocol exchange to at least - ten IKE_AUTH exchanges in the event the responder sends notification - messages and/or retries the authentication prompt. Once the protocol - exchange defined by the chosen EAP authentication method has - - - -Kaufman, et al. Expires August 27, 2006 [Page 44] - -Internet-Draft IKEv2bis February 2006 - - - successfully terminated, the responder MUST send an EAP payload - containing the Success message. Similarly, if the authentication - method has failed, the responder MUST send an EAP payload containing - the Failure message. The responder MAY at any time terminate the IKE - exchange by sending an EAP payload containing the Failure message. - - Following such an extended exchange, the EAP AUTH payloads MUST be - included in the two messages following the one containing the EAP - Success message. - - {{ Clarif-3.5 }} When the initiator authentication uses EAP, it is - possible that the contents of the IDi payload is used only for AAA - routing purposes and selecting which EAP method to use. This value - may be different from the identity authenticated by the EAP method. - It is important that policy lookups and access control decisions use - the actual authenticated identity. Often the EAP server is - implemented in a separate AAA server that communicates with the IKEv2 - responder. In this case, the authenticated identity has to be sent - from the AAA server to the IKEv2 responder. - - {{ Clarif-3.8 }} The information in Section 2.17 about PRFs with - fixed-size keys also applies to EAP authentication. For instance, a - PRF that requires a 128-bit key cannot be used with EAP because - specifies that the MSK is at least 512 bits long. - -2.17. Generating Keying Material for CHILD_SAs - - A single CHILD_SA is created by the IKE_AUTH exchange, and additional - CHILD_SAs can optionally be created in CREATE_CHILD_SA exchanges. - Keying material for them is generated as follows: - - KEYMAT = prf+(SK_d, Ni | Nr) - - Where Ni and Nr are the nonces from the IKE_SA_INIT exchange if this - request is the first CHILD_SA created or the fresh Ni and Nr from the - CREATE_CHILD_SA exchange if this is a subsequent creation. - - For CREATE_CHILD_SA exchanges including an optional Diffie-Hellman - exchange, the keying material is defined as: - - KEYMAT = prf+(SK_d, g^ir (new) | Ni | Nr ) - - where g^ir (new) is the shared secret from the ephemeral Diffie- - Hellman exchange of this CREATE_CHILD_SA exchange (represented as an - octet string in big endian order padded with zeros in the high-order - bits if necessary to make it the length of the modulus). - - A single CHILD_SA negotiation may result in multiple security - - - -Kaufman, et al. Expires August 27, 2006 [Page 45] - -Internet-Draft IKEv2bis February 2006 - - - associations. ESP and AH SAs exist in pairs (one in each direction), - and four SAs could be created in a single CHILD_SA negotiation if a - combination of ESP and AH is being negotiated. - - Keying material MUST be taken from the expanded KEYMAT in the - following order: - - o All keys for SAs carrying data from the initiator to the responder - are taken before SAs going in the reverse direction. - - o If multiple IPsec protocols are negotiated, keying material is - taken in the order in which the protocol headers will appear in - the encapsulated packet. - - o If a single protocol has both encryption and authentication keys, - the encryption key is taken from the first octets of KEYMAT and - the authentication key is taken from the next octets. - - Each cryptographic algorithm takes a fixed number of bits of keying - material specified as part of the algorithm. - -2.18. Rekeying IKE_SAs Using a CREATE_CHILD_SA Exchange - - The CREATE_CHILD_SA exchange can be used to rekey an existing IKE_SA - (see Section 2.8). {{ Clarif-5.3 }} New initiator and responder SPIs - are supplied in the SPI fields in the Proposal structures inside the - Security Association (SA) payloads (not the SPI fields in the IKE - header). The TS payloads are omitted when rekeying an IKE_SA. - SKEYSEED for the new IKE_SA is computed using SK_d from the existing - IKE_SA as follows: - - SKEYSEED = prf(SK_d (old), [g^ir (new)] | Ni | Nr) - - where g^ir (new) is the shared secret from the ephemeral Diffie- - Hellman exchange of this CREATE_CHILD_SA exchange (represented as an - octet string in big endian order padded with zeros if necessary to - make it the length of the modulus) and Ni and Nr are the two nonces - stripped of any headers. - - {{ Clarif-5.5 }} The old and new IKE_SA may have selected a different - PRF. Because the rekeying exchange belongs to the old IKE_SA, it is - the old IKE_SA's PRF that is used. Note that this may not work if - the new IKE_SA's PRF has a fixed key size because the output of the - PRF may not be of the correct size. - - The new IKE_SA MUST reset its message counters to 0. - - SK_d, SK_ai, SK_ar, SK_ei, and SK_er are computed from SKEYSEED as - - - -Kaufman, et al. Expires August 27, 2006 [Page 46] - -Internet-Draft IKEv2bis February 2006 - - - specified in Section 2.14. - -2.19. Requesting an Internal Address on a Remote Network - - Most commonly occurring in the endpoint-to-security-gateway scenario, - an endpoint may need an IP address in the network protected by the - security gateway and may need to have that address dynamically - assigned. A request for such a temporary address can be included in - any request to create a CHILD_SA (including the implicit request in - message 3) by including a CP payload. - - This function provides address allocation to an IPsec Remote Access - Client (IRAC) trying to tunnel into a network protected by an IPsec - Remote Access Server (IRAS). Since the IKE_AUTH exchange creates an - IKE_SA and a CHILD_SA, the IRAC MUST request the IRAS-controlled - address (and optionally other information concerning the protected - network) in the IKE_AUTH exchange. The IRAS may procure an address - for the IRAC from any number of sources such as a DHCP/BOOTP server - or its own address pool. - - Initiator Responder - ------------------------------------------------------------------- - HDR, SK {IDi, [CERT,] - [CERTREQ,] [IDr,] AUTH, - CP(CFG_REQUEST), SAi2, - TSi, TSr} --> - <-- HDR, SK {IDr, [CERT,] AUTH, - CP(CFG_REPLY), SAr2, - TSi, TSr} - - In all cases, the CP payload MUST be inserted before the SA payload. - In variations of the protocol where there are multiple IKE_AUTH - exchanges, the CP payloads MUST be inserted in the messages - containing the SA payloads. - - CP(CFG_REQUEST) MUST contain at least an INTERNAL_ADDRESS attribute - (either IPv4 or IPv6) but MAY contain any number of additional - attributes the initiator wants returned in the response. - - For example, message from initiator to responder: - - CP(CFG_REQUEST)= - INTERNAL_ADDRESS() - TSi = (0, 0-65535,0.0.0.0-255.255.255.255) - TSr = (0, 0-65535,0.0.0.0-255.255.255.255) - - NOTE: Traffic Selectors contain (protocol, port range, address - range). - - - -Kaufman, et al. Expires August 27, 2006 [Page 47] - -Internet-Draft IKEv2bis February 2006 - - - Message from responder to initiator: - - CP(CFG_REPLY)= - INTERNAL_ADDRESS(192.0.2.202) - INTERNAL_NETMASK(255.255.255.0) - INTERNAL_SUBNET(192.0.2.0/255.255.255.0) - TSi = (0, 0-65535,192.0.2.202-192.0.2.202) - TSr = (0, 0-65535,192.0.2.0-192.0.2.255) - - All returned values will be implementation dependent. As can be seen - in the above example, the IRAS MAY also send other attributes that - were not included in CP(CFG_REQUEST) and MAY ignore the non- - mandatory attributes that it does not support. - - The responder MUST NOT send a CFG_REPLY without having first received - a CP(CFG_REQUEST) from the initiator, because we do not want the IRAS - to perform an unnecessary configuration lookup if the IRAC cannot - process the REPLY. In the case where the IRAS's configuration - requires that CP be used for a given identity IDi, but IRAC has - failed to send a CP(CFG_REQUEST), IRAS MUST fail the request, and - terminate the IKE exchange with a FAILED_CP_REQUIRED error. - -2.20. Requesting the Peer's Version - - An IKE peer wishing to inquire about the other peer's IKE software - version information MAY use the method below. This is an example of - a configuration request within an INFORMATIONAL exchange, after the - IKE_SA and first CHILD_SA have been created. - - An IKE implementation MAY decline to give out version information - prior to authentication or even after authentication to prevent - trolling in case some implementation is known to have some security - weakness. In that case, it MUST either return an empty string or no - CP payload if CP is not supported. - - Initiator Responder - ------------------------------------------------------------------- - HDR, SK{CP(CFG_REQUEST)} --> - <-- HDR, SK{CP(CFG_REPLY)} - - CP(CFG_REQUEST)= - APPLICATION_VERSION("") - - CP(CFG_REPLY) APPLICATION_VERSION("foobar v1.3beta, (c) Foo Bar - Inc.") - - - - - - -Kaufman, et al. Expires August 27, 2006 [Page 48] - -Internet-Draft IKEv2bis February 2006 - - -2.21. Error Handling - - There are many kinds of errors that can occur during IKE processing. - If a request is received that is badly formatted or unacceptable for - reasons of policy (e.g., no matching cryptographic algorithms), the - response MUST contain a Notify payload indicating the error. If an - error occurs outside the context of an IKE request (e.g., the node is - getting ESP messages on a nonexistent SPI), the node SHOULD initiate - an INFORMATIONAL exchange with a Notify payload describing the - problem. - - Errors that occur before a cryptographically protected IKE_SA is - established must be handled very carefully. There is a trade-off - between wanting to be helpful in diagnosing a problem and responding - to it and wanting to avoid being a dupe in a denial of service attack - based on forged messages. - - If a node receives a message on UDP port 500 or 4500 outside the - context of an IKE_SA known to it (and not a request to start one), it - may be the result of a recent crash of the node. If the message is - marked as a response, the node MAY audit the suspicious event but - MUST NOT respond. If the message is marked as a request, the node - MAY audit the suspicious event and MAY send a response. If a - response is sent, the response MUST be sent to the IP address and - port from whence it came with the same IKE SPIs and the Message ID - copied. The response MUST NOT be cryptographically protected and - MUST contain a Notify payload indicating INVALID_IKE_SPI. - - A node receiving such an unprotected Notify payload MUST NOT respond - and MUST NOT change the state of any existing SAs. The message might - be a forgery or might be a response the genuine correspondent was - tricked into sending. {{ Demoted two SHOULDs }} A node should treat - such a message (and also a network message like ICMP destination - unreachable) as a hint that there might be problems with SAs to that - IP address and should initiate a liveness test for any such IKE_SA. - An implementation SHOULD limit the frequency of such tests to avoid - being tricked into participating in a denial of service attack. - - A node receiving a suspicious message from an IP address with which - it has an IKE_SA MAY send an IKE Notify payload in an IKE - INFORMATIONAL exchange over that SA. {{ Demoted the SHOULD }} The - recipient MUST NOT change the state of any SAs as a result, but may - wish to audit the event to aid in diagnosing malfunctions. A node - MUST limit the rate at which it will send messages in response to - unprotected messages. - - - - - - -Kaufman, et al. Expires August 27, 2006 [Page 49] - -Internet-Draft IKEv2bis February 2006 - - -2.22. IPComp - - Use of IP compression [IPCOMP] can be negotiated as part of the setup - of a CHILD_SA. While IP compression involves an extra header in each - packet and a compression parameter index (CPI), the virtual - "compression association" has no life outside the ESP or AH SA that - contains it. Compression associations disappear when the - corresponding ESP or AH SA goes away. It is not explicitly mentioned - in any DELETE payload. - - Negotiation of IP compression is separate from the negotiation of - cryptographic parameters associated with a CHILD_SA. A node - requesting a CHILD_SA MAY advertise its support for one or more - compression algorithms through one or more Notify payloads of type - IPCOMP_SUPPORTED. The response MAY indicate acceptance of a single - compression algorithm with a Notify payload of type IPCOMP_SUPPORTED. - These payloads MUST NOT occur in messages that do not contain SA - payloads. - - Although there has been discussion of allowing multiple compression - algorithms to be accepted and to have different compression - algorithms available for the two directions of a CHILD_SA, - implementations of this specification MUST NOT accept an IPComp - algorithm that was not proposed, MUST NOT accept more than one, and - MUST NOT compress using an algorithm other than one proposed and - accepted in the setup of the CHILD_SA. - - A side effect of separating the negotiation of IPComp from - cryptographic parameters is that it is not possible to propose - multiple cryptographic suites and propose IP compression with some of - them but not others. - -2.23. NAT Traversal - - Network Address Translation (NAT) gateways are a controversial - subject. This section briefly describes what they are and how they - are likely to act on IKE traffic. Many people believe that NATs are - evil and that we should not design our protocols so as to make them - work better. IKEv2 does specify some unintuitive processing rules in - order that NATs are more likely to work. - - NATs exist primarily because of the shortage of IPv4 addresses, - though there are other rationales. IP nodes that are "behind" a NAT - have IP addresses that are not globally unique, but rather are - assigned from some space that is unique within the network behind the - NAT but that are likely to be reused by nodes behind other NATs. - Generally, nodes behind NATs can communicate with other nodes behind - the same NAT and with nodes with globally unique addresses, but not - - - -Kaufman, et al. Expires August 27, 2006 [Page 50] - -Internet-Draft IKEv2bis February 2006 - - - with nodes behind other NATs. There are exceptions to that rule. - When those nodes make connections to nodes on the real Internet, the - NAT gateway "translates" the IP source address to an address that - will be routed back to the gateway. Messages to the gateway from the - Internet have their destination addresses "translated" to the - internal address that will route the packet to the correct endnode. - - NATs are designed to be "transparent" to endnodes. Neither software - on the node behind the NAT nor the node on the Internet requires - modification to communicate through the NAT. Achieving this - transparency is more difficult with some protocols than with others. - Protocols that include IP addresses of the endpoints within the - payloads of the packet will fail unless the NAT gateway understands - the protocol and modifies the internal references as well as those in - the headers. Such knowledge is inherently unreliable, is a network - layer violation, and often results in subtle problems. - - Opening an IPsec connection through a NAT introduces special - problems. If the connection runs in transport mode, changing the IP - addresses on packets will cause the checksums to fail and the NAT - cannot correct the checksums because they are cryptographically - protected. Even in tunnel mode, there are routing problems because - transparently translating the addresses of AH and ESP packets - requires special logic in the NAT and that logic is heuristic and - unreliable in nature. For that reason, IKEv2 can negotiate UDP - encapsulation of IKE and ESP packets. This encoding is slightly less - efficient but is easier for NATs to process. In addition, firewalls - may be configured to pass IPsec traffic over UDP but not ESP/AH or - vice versa. - - It is a common practice of NATs to translate TCP and UDP port numbers - as well as addresses and use the port numbers of inbound packets to - decide which internal node should get a given packet. For this - reason, even though IKE packets MUST be sent from and to UDP port - 500, they MUST be accepted coming from any port and responses MUST be - sent to the port from whence they came. This is because the ports - may be modified as the packets pass through NATs. Similarly, IP - addresses of the IKE endpoints are generally not included in the IKE - payloads because the payloads are cryptographically protected and - could not be transparently modified by NATs. - - Port 4500 is reserved for UDP-encapsulated ESP and IKE. When working - through a NAT, it is generally better to pass IKE packets over port - 4500 because some older NATs handle IKE traffic on port 500 cleverly - in an attempt to transparently establish IPsec connections between - endpoints that don't handle NAT traversal themselves. Such NATs may - interfere with the straightforward NAT traversal envisioned by this - document. {{ Clarif-7.6 }} An IPsec endpoint that discovers a NAT - - - -Kaufman, et al. Expires August 27, 2006 [Page 51] - -Internet-Draft IKEv2bis February 2006 - - - between it and its correspondent MUST send all subsequent traffic - from port 4500, which NATs should not treat specially (as they might - with port 500). - - The specific requirements for supporting NAT traversal [NATREQ] are - listed below. Support for NAT traversal is optional. In this - section only, requirements listed as MUST apply only to - implementations supporting NAT traversal. - - o IKE MUST listen on port 4500 as well as port 500. IKE MUST - respond to the IP address and port from which packets arrived. - - o Both IKE initiator and responder MUST include in their IKE_SA_INIT - packets Notify payloads of type NAT_DETECTION_SOURCE_IP and - NAT_DETECTION_DESTINATION_IP. Those payloads can be used to - detect if there is NAT between the hosts, and which end is behind - the NAT. The location of the payloads in the IKE_SA_INIT packets - are just after the Ni and Nr payloads (before the optional CERTREQ - payload). - - o If none of the NAT_DETECTION_SOURCE_IP payload(s) received matches - the hash of the source IP and port found from the IP header of the - packet containing the payload, it means that the other end is - behind NAT (i.e., someone along the route changed the source - address of the original packet to match the address of the NAT - box). In this case, this end should allow dynamic update of the - other ends IP address, as described later. - - o If the NAT_DETECTION_DESTINATION_IP payload received does not - match the hash of the destination IP and port found from the IP - header of the packet containing the payload, it means that this - end is behind a NAT. In this case, this end SHOULD start sending - keepalive packets as explained in [UDPENCAPS]. - - o The IKE initiator MUST check these payloads if present and if they - do not match the addresses in the outer packet MUST tunnel all - future IKE and ESP packets associated with this IKE_SA over UDP - port 4500. - - o To tunnel IKE packets over UDP port 4500, the IKE header has four - octets of zero prepended and the result immediately follows the - UDP header. To tunnel ESP packets over UDP port 4500, the ESP - header immediately follows the UDP header. Since the first four - bytes of the ESP header contain the SPI, and the SPI cannot - validly be zero, it is always possible to distinguish ESP and IKE - messages. - - - - - -Kaufman, et al. Expires August 27, 2006 [Page 52] - -Internet-Draft IKEv2bis February 2006 - - - o The original source and destination IP address required for the - transport mode TCP and UDP packet checksum fixup (see [UDPENCAPS]) - are obtained from the Traffic Selectors associated with the - exchange. In the case of NAT traversal, the Traffic Selectors - MUST contain exactly one IP address, which is then used as the - original IP address. - - o There are cases where a NAT box decides to remove mappings that - are still alive (for example, the keepalive interval is too long, - or the NAT box is rebooted). To recover in these cases, hosts - that are not behind a NAT SHOULD send all packets (including - retransmission packets) to the IP address and port from the last - valid authenticated packet from the other end (i.e., dynamically - update the address). A host behind a NAT SHOULD NOT do this - because it opens a DoS attack possibility. Any authenticated IKE - packet or any authenticated UDP-encapsulated ESP packet can be - used to detect that the IP address or the port has changed. - - Note that similar but probably not identical actions will likely be - needed to make IKE work with Mobile IP, but such processing is not - addressed by this document. - -2.24. Explicit Congestion Notification (ECN) - - When IPsec tunnels behave as originally specified in [IPSECARCH-OLD], - ECN usage is not appropriate for the outer IP headers because tunnel - decapsulation processing discards ECN congestion indications to the - detriment of the network. ECN support for IPsec tunnels for IKEv1- - based IPsec requires multiple operating modes and negotiation (see - [ECN]). IKEv2 simplifies this situation by requiring that ECN be - usable in the outer IP headers of all tunnel-mode IPsec SAs created - by IKEv2. Specifically, tunnel encapsulators and decapsulators for - all tunnel-mode SAs created by IKEv2 MUST support the ECN full- - functionality option for tunnels specified in [ECN] and MUST - implement the tunnel encapsulation and decapsulation processing - specified in [IPSECARCH] to prevent discarding of ECN congestion - indications. - - -3. Header and Payload Formats - -3.1. The IKE Header - - IKE messages use UDP ports 500 and/or 4500, with one IKE message per - UDP datagram. Information from the beginning of the packet through - the UDP header is largely ignored except that the IP addresses and - UDP ports from the headers are reversed and used for return packets. - When sent on UDP port 500, IKE messages begin immediately following - - - -Kaufman, et al. Expires August 27, 2006 [Page 53] - -Internet-Draft IKEv2bis February 2006 - - - the UDP header. When sent on UDP port 4500, IKE messages have - prepended four octets of zero. These four octets of zero are not - part of the IKE message and are not included in any of the length - fields or checksums defined by IKE. Each IKE message begins with the - IKE header, denoted HDR in this memo. Following the header are one - or more IKE payloads each identified by a "Next Payload" field in the - preceding payload. Payloads are processed in the order in which they - appear in an IKE message by invoking the appropriate processing - routine according to the "Next Payload" field in the IKE header and - subsequently according to the "Next Payload" field in the IKE payload - itself until a "Next Payload" field of zero indicates that no - payloads follow. If a payload of type "Encrypted" is found, that - payload is decrypted and its contents parsed as additional payloads. - An Encrypted payload MUST be the last payload in a packet and an - Encrypted payload MUST NOT contain another Encrypted payload. - - The Recipient SPI in the header identifies an instance of an IKE - security association. It is therefore possible for a single instance - of IKE to multiplex distinct sessions with multiple peers. - - All multi-octet fields representing integers are laid out in big - endian order (aka most significant byte first, or network byte - order). - - The format of the IKE header is shown in Figure 4. - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! IKE_SA Initiator's SPI ! - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! IKE_SA Responder's SPI ! - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload ! MjVer ! MnVer ! Exchange Type ! Flags ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Message ID ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 4: IKE Header Format - - o Initiator's SPI (8 octets) - A value chosen by the initiator to - identify a unique IKE security association. This value MUST NOT - be zero. - - - - -Kaufman, et al. Expires August 27, 2006 [Page 54] - -Internet-Draft IKEv2bis February 2006 - - - o Responder's SPI (8 octets) - A value chosen by the responder to - identify a unique IKE security association. This value MUST be - zero in the first message of an IKE Initial Exchange (including - repeats of that message including a cookie). {{ The phrase "and - MUST NOT be zero in any other message" was removed; Clarif-2.1 }} - - o Next Payload (1 octet) - Indicates the type of payload that - immediately follows the header. The format and value of each - payload are defined below. - - o Major Version (4 bits) - Indicates the major version of the IKE - protocol in use. Implementations based on this version of IKE - MUST set the Major Version to 2. Implementations based on - previous versions of IKE and ISAKMP MUST set the Major Version to - 1. Implementations based on this version of IKE MUST reject or - ignore messages containing a version number greater than 2. - - o Minor Version (4 bits) - Indicates the minor version of the IKE - protocol in use. Implementations based on this version of IKE - MUST set the Minor Version to 0. They MUST ignore the minor - version number of received messages. - - o Exchange Type (1 octet) - Indicates the type of exchange being - used. This constrains the payloads sent in each message and - orderings of messages in an exchange. - - Exchange Type Value - ---------------------------------- - RESERVED 0-33 - IKE_SA_INIT 34 - IKE_AUTH 35 - CREATE_CHILD_SA 36 - INFORMATIONAL 37 - RESERVED TO IANA 38-239 - Reserved for private use 240-255 - - o Flags (1 octet) - Indicates specific options that are set for the - message. Presence of options are indicated by the appropriate bit - in the flags field being set. The bits are defined LSB first, so - bit 0 would be the least significant bit of the Flags octet. In - the description below, a bit being 'set' means its value is '1', - while 'cleared' means its value is '0'. - - * X(reserved) (bits 0-2) - These bits MUST be cleared when - sending and MUST be ignored on receipt. - - * I(nitiator) (bit 3 of Flags) - This bit MUST be set in messages - sent by the original initiator of the IKE_SA and MUST be - - - -Kaufman, et al. Expires August 27, 2006 [Page 55] - -Internet-Draft IKEv2bis February 2006 - - - cleared in messages sent by the original responder. It is used - by the recipient to determine which eight octets of the SPI - were generated by the recipient. - - * V(ersion) (bit 4 of Flags) - This bit indicates that the - transmitter is capable of speaking a higher major version - number of the protocol than the one indicated in the major - version number field. Implementations of IKEv2 must clear this - bit when sending and MUST ignore it in incoming messages. - - * R(esponse) (bit 5 of Flags) - This bit indicates that this - message is a response to a message containing the same message - ID. This bit MUST be cleared in all request messages and MUST - be set in all responses. An IKE endpoint MUST NOT generate a - response to a message that is marked as being a response. - - * X(reserved) (bits 6-7 of Flags) - These bits MUST be cleared - when sending and MUST be ignored on receipt. - - o Message ID (4 octets) - Message identifier used to control - retransmission of lost packets and matching of requests and - responses. It is essential to the security of the protocol - because it is used to prevent message replay attacks. See - Section 2.1 and Section 2.2. - - o Length (4 octets) - Length of total message (header + payloads) in - octets. - -3.2. Generic Payload Header - - Each IKE payload defined in Section 3.3 through Section 3.16 begins - with a generic payload header, shown in Figure 5. Figures for each - payload below will include the generic payload header, but for - brevity the description of each field will be omitted. - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload !C! RESERVED ! Payload Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 5: Generic Payload Header - - The Generic Payload Header fields are defined as follows: - - o Next Payload (1 octet) - Identifier for the payload type of the - next payload in the message. If the current payload is the last - in the message, then this field will be 0. This field provides a - - - -Kaufman, et al. Expires August 27, 2006 [Page 56] - -Internet-Draft IKEv2bis February 2006 - - - "chaining" capability whereby additional payloads can be added to - a message by appending it to the end of the message and setting - the "Next Payload" field of the preceding payload to indicate the - new payload's type. An Encrypted payload, which must always be - the last payload of a message, is an exception. It contains data - structures in the format of additional payloads. In the header of - an Encrypted payload, the Next Payload field is set to the payload - type of the first contained payload (instead of 0). The payload - type values are: - - Next Payload Type Notation Value - -------------------------------------------------- - No Next Payload 0 - RESERVED 1-32 - Security Association SA 33 - Key Exchange KE 34 - Identification - Initiator IDi 35 - Identification - Responder IDr 36 - Certificate CERT 37 - Certificate Request CERTREQ 38 - Authentication AUTH 39 - Nonce Ni, Nr 40 - Notify N 41 - Delete D 42 - Vendor ID V 43 - Traffic Selector - Initiator TSi 44 - Traffic Selector - Responder TSr 45 - Encrypted E 46 - Configuration CP 47 - Extensible Authentication EAP 48 - RESERVED TO IANA 49-127 - PRIVATE USE 128-255 - - (Payload type values 1-32 should not be assigned in the - future so that there is no overlap with the code assignments - for IKEv1.) - - o Critical (1 bit) - MUST be set to zero if the sender wants the - recipient to skip this payload if it does not understand the - payload type code in the Next Payload field of the previous - payload. MUST be set to one if the sender wants the recipient to - reject this entire message if it does not understand the payload - type. MUST be ignored by the recipient if the recipient - understands the payload type code. MUST be set to zero for - payload types defined in this document. Note that the critical - bit applies to the current payload rather than the "next" payload - whose type code appears in the first octet. The reasoning behind - not setting the critical bit for payloads defined in this document - - - -Kaufman, et al. Expires August 27, 2006 [Page 57] - -Internet-Draft IKEv2bis February 2006 - - - is that all implementations MUST understand all payload types - defined in this document and therefore must ignore the Critical - bit's value. Skipped payloads are expected to have valid Next - Payload and Payload Length fields. - - o RESERVED (7 bits) - MUST be sent as zero; MUST be ignored on - receipt. - - o Payload Length (2 octets) - Length in octets of the current - payload, including the generic payload header. - -3.3. Security Association Payload - - The Security Association Payload, denoted SA in this memo, is used to - negotiate attributes of a security association. Assembly of Security - Association Payloads requires great peace of mind. An SA payload MAY - contain multiple proposals. If there is more than one, they MUST be - ordered from most preferred to least preferred. Each proposal may - contain multiple IPsec protocols (where a protocol is IKE, ESP, or - AH), each protocol MAY contain multiple transforms, and each - transform MAY contain multiple attributes. When parsing an SA, an - implementation MUST check that the total Payload Length is consistent - with the payload's internal lengths and counts. Proposals, - Transforms, and Attributes each have their own variable length - encodings. They are nested such that the Payload Length of an SA - includes the combined contents of the SA, Proposal, Transform, and - Attribute information. The length of a Proposal includes the lengths - of all Transforms and Attributes it contains. The length of a - Transform includes the lengths of all Attributes it contains. - - The syntax of Security Associations, Proposals, Transforms, and - Attributes is based on ISAKMP; however the semantics are somewhat - different. The reason for the complexity and the hierarchy is to - allow for multiple possible combinations of algorithms to be encoded - in a single SA. Sometimes there is a choice of multiple algorithms, - whereas other times there is a combination of algorithms. For - example, an initiator might want to propose using (AH w/MD5 and ESP - w/3DES) OR (ESP w/MD5 and 3DES). - - One of the reasons the semantics of the SA payload has changed from - ISAKMP and IKEv1 is to make the encodings more compact in common - cases. - - The Proposal structure contains within it a Proposal # and an IPsec - protocol ID. Each structure MUST have the same Proposal # as the - previous one or be one (1) greater. The first Proposal MUST have a - Proposal # of one (1). If two successive structures have the same - Proposal number, it means that the proposal consists of the first - - - -Kaufman, et al. Expires August 27, 2006 [Page 58] - -Internet-Draft IKEv2bis February 2006 - - - structure AND the second. So a proposal of AH AND ESP would have two - proposal structures, one for AH and one for ESP and both would have - Proposal #1. A proposal of AH OR ESP would have two proposal - structures, one for AH with Proposal #1 and one for ESP with Proposal - #2. - - Each Proposal/Protocol structure is followed by one or more transform - structures. The number of different transforms is generally - determined by the Protocol. AH generally has a single transform: an - integrity check algorithm. ESP generally has two: an encryption - algorithm and an integrity check algorithm. IKE generally has four - transforms: a Diffie-Hellman group, an integrity check algorithm, a - prf algorithm, and an encryption algorithm. If an algorithm that - combines encryption and integrity protection is proposed, it MUST be - proposed as an encryption algorithm and an integrity protection - algorithm MUST NOT be proposed. For each Protocol, the set of - permissible transforms is assigned transform ID numbers, which appear - in the header of each transform. - - If there are multiple transforms with the same Transform Type, the - proposal is an OR of those transforms. If there are multiple - Transforms with different Transform Types, the proposal is an AND of - the different groups. For example, to propose ESP with (3DES or - IDEA) and (HMAC_MD5 or HMAC_SHA), the ESP proposal would contain two - Transform Type 1 candidates (one for 3DES and one for IDEA) and two - Transform Type 2 candidates (one for HMAC_MD5 and one for HMAC_SHA). - This effectively proposes four combinations of algorithms. If the - initiator wanted to propose only a subset of those, for example (3DES - and HMAC_MD5) or (IDEA and HMAC_SHA), there is no way to encode that - as multiple transforms within a single Proposal. Instead, the - initiator would have to construct two different Proposals, each with - two transforms. - - A given transform MAY have one or more Attributes. Attributes are - necessary when the transform can be used in more than one way, as - when an encryption algorithm has a variable key size. The transform - would specify the algorithm and the attribute would specify the key - size. Most transforms do not have attributes. A transform MUST NOT - have multiple attributes of the same type. To propose alternate - values for an attribute (for example, multiple key sizes for the AES - encryption algorithm), and implementation MUST include multiple - Transforms with the same Transform Type each with a single Attribute. - - Note that the semantics of Transforms and Attributes are quite - different from those in IKEv1. In IKEv1, a single Transform carried - multiple algorithms for a protocol with one carried in the Transform - and the others carried in the Attributes. - - - - -Kaufman, et al. Expires August 27, 2006 [Page 59] - -Internet-Draft IKEv2bis February 2006 - - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload !C! RESERVED ! Payload Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ <Proposals> ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 6: Security Association Payload - - o Proposals (variable) - One or more proposal substructures. - - The payload type for the Security Association Payload is thirty three - (33). - -3.3.1. Proposal Substructure - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! 0 (last) or 2 ! RESERVED ! Proposal Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Proposal # ! Protocol ID ! SPI Size !# of Transforms! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ~ SPI (variable) ~ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ <Transforms> ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 7: Proposal Substructure - - o 0 (last) or 2 (more) (1 octet) - Specifies whether this is the - last Proposal Substructure in the SA. This syntax is inherited - from ISAKMP, but is unnecessary because the last Proposal could be - identified from the length of the SA. The value (2) corresponds - to a Payload Type of Proposal in IKEv1, and the first four octets - of the Proposal structure are designed to look somewhat like the - header of a Payload. - - o RESERVED (1 octet) - MUST be sent as zero; MUST be ignored on - receipt. - - o Proposal Length (2 octets) - Length of this proposal, including - all transforms and attributes that follow. - - - -Kaufman, et al. Expires August 27, 2006 [Page 60] - -Internet-Draft IKEv2bis February 2006 - - - o Proposal # (1 octet) - When a proposal is made, the first proposal - in an SA payload MUST be #1, and subsequent proposals MUST either - be the same as the previous proposal (indicating an AND of the two - proposals) or one more than the previous proposal (indicating an - OR of the two proposals). When a proposal is accepted, all of the - proposal numbers in the SA payload MUST be the same and MUST match - the number on the proposal sent that was accepted. - - o Protocol ID (1 octet) - Specifies the IPsec protocol identifier - for the current negotiation. The defined values are: - - Protocol Protocol ID - ----------------------------------- - RESERVED 0 - IKE 1 - AH 2 - ESP 3 - RESERVED TO IANA 4-200 - PRIVATE USE 201-255 - - o SPI Size (1 octet) - For an initial IKE_SA negotiation, this field - MUST be zero; the SPI is obtained from the outer header. During - subsequent negotiations, it is equal to the size, in octets, of - the SPI of the corresponding protocol (8 for IKE, 4 for ESP and - AH). - - o # of Transforms (1 octet) - Specifies the number of transforms in - this proposal. - - o SPI (variable) - The sending entity's SPI. Even if the SPI Size - is not a multiple of 4 octets, there is no padding applied to the - payload. When the SPI Size field is zero, this field is not - present in the Security Association payload. - - o Transforms (variable) - One or more transform substructures. - - - - - - - - - - - - - - - - -Kaufman, et al. Expires August 27, 2006 [Page 61] - -Internet-Draft IKEv2bis February 2006 - - -3.3.2. Transform Substructure - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! 0 (last) or 3 ! RESERVED ! Transform Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - !Transform Type ! RESERVED ! Transform ID ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ Transform Attributes ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 8: Transform Substructure - - o 0 (last) or 3 (more) (1 octet) - Specifies whether this is the - last Transform Substructure in the Proposal. This syntax is - inherited from ISAKMP, but is unnecessary because the last - Proposal could be identified from the length of the SA. The value - (3) corresponds to a Payload Type of Transform in IKEv1, and the - first four octets of the Transform structure are designed to look - somewhat like the header of a Payload. - - o RESERVED - MUST be sent as zero; MUST be ignored on receipt. - - o Transform Length - The length (in octets) of the Transform - Substructure including Header and Attributes. - - o Transform Type (1 octet) - The type of transform being specified - in this transform. Different protocols support different - transform types. For some protocols, some of the transforms may - be optional. If a transform is optional and the initiator wishes - to propose that the transform be omitted, no transform of the - given type is included in the proposal. If the initiator wishes - to make use of the transform optional to the responder, it - includes a transform substructure with transform ID = 0 as one of - the options. - - o Transform ID (2 octets) - The specific instance of the transform - type being proposed. - - The tranform type values are: - - - - - - - - -Kaufman, et al. Expires August 27, 2006 [Page 62] - -Internet-Draft IKEv2bis February 2006 - - - Description Trans. Used In - Type - ------------------------------------------------------------------ - RESERVED 0 - Encryption Algorithm (ENCR) 1 IKE and ESP - Pseudo-random Function (PRF) 2 IKE - Integrity Algorithm (INTEG) 3 IKE, AH, optional in ESP - Diffie-Hellman Group (D-H) 4 IKE, optional in AH & ESP - Extended Sequence Numbers (ESN) 5 AH and ESP - RESERVED TO IANA 6-240 - PRIVATE USE 241-255 - - For Transform Type 1 (Encryption Algorithm), defined Transform IDs - are: - - Name Number Defined In - --------------------------------------------------- - RESERVED 0 - ENCR_DES_IV64 1 (RFC1827) - ENCR_DES 2 (RFC2405), [DES] - ENCR_3DES 3 (RFC2451) - ENCR_RC5 4 (RFC2451) - ENCR_IDEA 5 (RFC2451), [IDEA] - ENCR_CAST 6 (RFC2451) - ENCR_BLOWFISH 7 (RFC2451) - ENCR_3IDEA 8 (RFC2451) - ENCR_DES_IV32 9 - RESERVED 10 - ENCR_NULL 11 (RFC2410) - ENCR_AES_CBC 12 (RFC3602) - ENCR_AES_CTR 13 (RFC3664) - RESERVED TO IANA 14-1023 - PRIVATE USE 1024-65535 - - For Transform Type 2 (Pseudo-random Function), defined Transform IDs - are: - - Name Number Defined In - ------------------------------------------------------ - RESERVED 0 - PRF_HMAC_MD5 1 (RFC2104), [MD5] - PRF_HMAC_SHA1 2 (RFC2104), [SHA] - PRF_HMAC_TIGER 3 (RFC2104) - PRF_AES128_XCBC 4 (RFC3664) - RESERVED TO IANA 5-1023 - PRIVATE USE 1024-65535 - - For Transform Type 3 (Integrity Algorithm), defined Transform IDs - - - -Kaufman, et al. Expires August 27, 2006 [Page 63] - -Internet-Draft IKEv2bis February 2006 - - - are: - - Name Number Defined In - ---------------------------------------- - NONE 0 - AUTH_HMAC_MD5_96 1 (RFC2403) - AUTH_HMAC_SHA1_96 2 (RFC2404) - AUTH_DES_MAC 3 - AUTH_KPDK_MD5 4 (RFC1826) - AUTH_AES_XCBC_96 5 (RFC3566) - RESERVED TO IANA 6-1023 - PRIVATE USE 1024-65535 - - For Transform Type 4 (Diffie-Hellman Group), defined Transform IDs - are: - - Name Number - -------------------------------------- - NONE 0 - Defined in Appendix B 1 - 2 - RESERVED 3 - 4 - Defined in [ADDGROUP] 5 - RESERVED TO IANA 6 - 13 - Defined in [ADDGROUP] 14 - 18 - RESERVED TO IANA 19 - 1023 - PRIVATE USE 1024-65535 - - For Transform Type 5 (Extended Sequence Numbers), defined Transform - IDs are: - - Name Number - -------------------------------------------- - No Extended Sequence Numbers 0 - Extended Sequence Numbers 1 - RESERVED 2 - 65535 - -3.3.3. Valid Transform Types by Protocol - - The number and type of transforms that accompany an SA payload are - dependent on the protocol in the SA itself. An SA payload proposing - the establishment of an SA has the following mandatory and optional - transform types. A compliant implementation MUST understand all - mandatory and optional types for each protocol it supports (though it - need not accept proposals with unacceptable suites). A proposal MAY - omit the optional types if the only value for them it will accept is - NONE. - - - - - -Kaufman, et al. Expires August 27, 2006 [Page 64] - -Internet-Draft IKEv2bis February 2006 - - - Protocol Mandatory Types Optional Types - --------------------------------------------------- - IKE ENCR, PRF, INTEG, D-H - ESP ENCR, ESN INTEG, D-H - AH INTEG, ESN D-H - -3.3.4. Mandatory Transform IDs - - The specification of suites that MUST and SHOULD be supported for - interoperability has been removed from this document because they are - likely to change more rapidly than this document evolves. - - An important lesson learned from IKEv1 is that no system should only - implement the mandatory algorithms and expect them to be the best - choice for all customers. For example, at the time that this - document was written, many IKEv1 implementers were starting to - migrate to AES in Cipher Block Chaining (CBC) mode for Virtual - Private Network (VPN) applications. Many IPsec systems based on - IKEv2 will implement AES, additional Diffie-Hellman groups, and - additional hash algorithms, and some IPsec customers already require - these algorithms in addition to the ones listed above. - - It is likely that IANA will add additional transforms in the future, - and some users may want to use private suites, especially for IKE - where implementations should be capable of supporting different - parameters, up to certain size limits. In support of this goal, all - implementations of IKEv2 SHOULD include a management facility that - allows specification (by a user or system administrator) of Diffie- - Hellman (DH) parameters (the generator, modulus, and exponent lengths - and values) for new DH groups. Implementations SHOULD provide a - management interface through which these parameters and the - associated transform IDs may be entered (by a user or system - administrator), to enable negotiating such groups. - - All implementations of IKEv2 MUST include a management facility that - enables a user or system administrator to specify the suites that are - acceptable for use with IKE. Upon receipt of a payload with a set of - transform IDs, the implementation MUST compare the transmitted - transform IDs against those locally configured via the management - controls, to verify that the proposed suite is acceptable based on - local policy. The implementation MUST reject SA proposals that are - not authorized by these IKE suite controls. Note that cryptographic - suites that MUST be implemented need not be configured as acceptable - to local policy. - - - - - - - -Kaufman, et al. Expires August 27, 2006 [Page 65] - -Internet-Draft IKEv2bis February 2006 - - -3.3.5. Transform Attributes - - Each transform in a Security Association payload may include - attributes that modify or complete the specification of the - transform. These attributes are type/value pairs and are defined - below. For example, if an encryption algorithm has a variable-length - key, the key length to be used may be specified as an attribute. - Attributes can have a value with a fixed two octet length or a - variable-length value. For the latter, the attribute is encoded as - type/length/value. - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - !A! Attribute Type ! AF=0 Attribute Length ! - !F! ! AF=1 Attribute Value ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! AF=0 Attribute Value ! - ! AF=1 Not Transmitted ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 9: Data Attributes - - o Attribute Type (2 octets) - Unique identifier for each type of - attribute (see below). The most significant bit of this field is - the Attribute Format bit (AF). It indicates whether the data - attributes follow the Type/Length/Value (TLV) format or a - shortened Type/Value (TV) format. If the AF bit is zero (0), then - the Data Attributes are of the Type/Length/Value (TLV) form. If - the AF bit is a one (1), then the Data Attributes are of the Type/ - Value form. - - o Attribute Length (2 octets) - Length in octets of the Attribute - Value. When the AF bit is a one (1), the Attribute Value is only - 2 octets and the Attribute Length field is not present. - - o Attribute Value (variable length) - Value of the Attribute - associated with the Attribute Type. If the AF bit is a zero (0), - this field has a variable length defined by the Attribute Length - field. If the AF bit is a one (1), the Attribute Value has a - length of 2 octets. - - o Key Length - When using an Encryption Algorithm that has a - variable-length key, this attribute specifies the key length in - bits (MUST use network byte order). This attribute MUST NOT be - used when the specified Encryption Algorithm uses a fixed-length - key. - - - - -Kaufman, et al. Expires August 27, 2006 [Page 66] - -Internet-Draft IKEv2bis February 2006 - - - Note that only a single attribute type (Key Length) is defined, and - it is fixed length. The variable-length encoding specification is - included only for future extensions. {{ Clarif-7.11 removed the - sentence that listed, incorrectly, the algorithms defined in the - document that accept attributes. }} - - Attributes described as basic MUST NOT be encoded using the variable- - length encoding. Variable-length attributes MUST NOT be encoded as - basic even if their value can fit into two octets. NOTE: This is a - change from IKEv1, where increased flexibility may have simplified - the composer of messages but certainly complicated the parser. - - Attribute Type Value Attribute Format - ------------------------------------------------------------ - RESERVED 0-13 - Key Length (in bits) 14 TV - RESERVED 15-17 - RESERVED TO IANA 18-16383 - PRIVATE USE 16384-32767 - Values 0-13 and 15-17 were used in a similar context in - IKEv1, and should not be assigned except to matching values. - -3.3.6. Attribute Negotiation - - During security association negotiation initiators present offers to - responders. Responders MUST select a single complete set of - parameters from the offers (or reject all offers if none are - acceptable). If there are multiple proposals, the responder MUST - choose a single proposal number and return all of the Proposal - substructures with that Proposal number. If there are multiple - Transforms with the same type, the responder MUST choose a single - one. Any attributes of a selected transform MUST be returned - unmodified. The initiator of an exchange MUST check that the - accepted offer is consistent with one of its proposals, and if not - that response MUST be rejected. - - Negotiating Diffie-Hellman groups presents some special challenges. - SA offers include proposed attributes and a Diffie-Hellman public - number (KE) in the same message. If in the initial exchange the - initiator offers to use one of several Diffie-Hellman groups, it - SHOULD pick the one the responder is most likely to accept and - include a KE corresponding to that group. If the guess turns out to - be wrong, the responder will indicate the correct group in the - response and the initiator SHOULD pick an element of that group for - its KE value when retrying the first message. It SHOULD, however, - continue to propose its full supported set of groups in order to - prevent a man-in-the-middle downgrade attack. - - - - -Kaufman, et al. Expires August 27, 2006 [Page 67] - -Internet-Draft IKEv2bis February 2006 - - - Implementation Note: - - Certain negotiable attributes can have ranges or could have multiple - acceptable values. These include the key length of a variable key - length symmetric cipher. To further interoperability and to support - upgrading endpoints independently, implementers of this protocol - SHOULD accept values that they deem to supply greater security. For - instance, if a peer is configured to accept a variable-length cipher - with a key length of X bits and is offered that cipher with a larger - key length, the implementation SHOULD accept the offer if it supports - use of the longer key. - - Support of this capability allows an implementation to express a - concept of "at least" a certain level of security-- "a key length of - _at least_ X bits for cipher Y". - -3.4. Key Exchange Payload - - The Key Exchange Payload, denoted KE in this memo, is used to - exchange Diffie-Hellman public numbers as part of a Diffie-Hellman - key exchange. The Key Exchange Payload consists of the IKE generic - payload header followed by the Diffie-Hellman public value itself. - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload !C! RESERVED ! Payload Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! DH Group # ! RESERVED ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ Key Exchange Data ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 10: Key Exchange Payload Format - - A key exchange payload is constructed by copying one's Diffie-Hellman - public value into the "Key Exchange Data" portion of the payload. - The length of the Diffie-Hellman public value MUST be equal to the - length of the prime modulus over which the exponentiation was - performed, prepending zero bits to the value if necessary. - - The DH Group # identifies the Diffie-Hellman group in which the Key - Exchange Data was computed (see Section 3.3.2). If the selected - proposal uses a different Diffie-Hellman group, the message MUST be - rejected with a Notify payload of type INVALID_KE_PAYLOAD. - - - - -Kaufman, et al. Expires August 27, 2006 [Page 68] - -Internet-Draft IKEv2bis February 2006 - - - The payload type for the Key Exchange payload is thirty four (34). - -3.5. Identification Payloads - - The Identification Payloads, denoted IDi and IDr in this memo, allow - peers to assert an identity to one another. This identity may be - used for policy lookup, but does not necessarily have to match - anything in the CERT payload; both fields may be used by an - implementation to perform access control decisions. {{ Clarif-7.1 }} - When using the ID_IPV4_ADDR/ID_IPV6_ADDR identity types in IDi/IDr - payloads, IKEv2 does not require this address to match the address in - the IP header of IKEv2 packets, or anything in the TSi/TSr payloads. - The contents of IDi/IDr is used purely to fetch the policy and - authentication data related to the other party. - - NOTE: In IKEv1, two ID payloads were used in each direction to hold - Traffic Selector (TS) information for data passing over the SA. In - IKEv2, this information is carried in TS payloads (see Section 3.13). - - The Identification Payload consists of the IKE generic payload header - followed by identification fields as follows: - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload !C! RESERVED ! Payload Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ID Type ! RESERVED | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ Identification Data ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 11: Identification Payload Format - - o ID Type (1 octet) - Specifies the type of Identification being - used. - - o RESERVED - MUST be sent as zero; MUST be ignored on receipt. - - o Identification Data (variable length) - Value, as indicated by the - Identification Type. The length of the Identification Data is - computed from the size in the ID payload header. - - The payload types for the Identification Payload are thirty five (35) - for IDi and thirty six (36) for IDr. - - - - -Kaufman, et al. Expires August 27, 2006 [Page 69] - -Internet-Draft IKEv2bis February 2006 - - - The following table lists the assigned values for the Identification - Type field: - - ID Type Value - ------------------------------------------------------------------- - RESERVED 0 - - ID_IPV4_ADDR 1 - A single four (4) octet IPv4 address. - - ID_FQDN 2 - A fully-qualified domain name string. An example of a ID_FQDN - is, "example.com". The string MUST not contain any terminators - (e.g., NULL, CR, etc.). - - ID_RFC822_ADDR 3 - A fully-qualified RFC822 email address string, An example of a - ID_RFC822_ADDR is, "jsmith@example.com". The string MUST not - contain any terminators. - - RESERVED TO IANA 4 - - ID_IPV6_ADDR 5 - A single sixteen (16) octet IPv6 address. - - RESERVED TO IANA 6 - 8 - - ID_DER_ASN1_DN 9 - The binary Distinguished Encoding Rules (DER) encoding of an - ASN.1 X.500 Distinguished Name [X.501]. - - ID_DER_ASN1_GN 10 - The binary DER encoding of an ASN.1 X.500 GeneralName [X.509]. - - ID_KEY_ID 11 - An opaque octet stream which may be used to pass vendor- - specific information necessary to do certain proprietary - types of identification. - - RESERVED TO IANA 12-200 - - PRIVATE USE 201-255 - - Two implementations will interoperate only if each can generate a - type of ID acceptable to the other. To assure maximum - interoperability, implementations MUST be configurable to send at - least one of ID_IPV4_ADDR, ID_FQDN, ID_RFC822_ADDR, or ID_KEY_ID, and - MUST be configurable to accept all of these types. Implementations - - - -Kaufman, et al. Expires August 27, 2006 [Page 70] - -Internet-Draft IKEv2bis February 2006 - - - SHOULD be capable of generating and accepting all of these types. - IPv6-capable implementations MUST additionally be configurable to - accept ID_IPV6_ADDR. IPv6-only implementations MAY be configurable - to send only ID_IPV6_ADDR. - - {{ Clarif-3.4 }} EAP [EAP] does not mandate the use of any particular - type of identifier, but often EAP is used with Network Access - Identifiers (NAIs) defined in [NAI]. Although NAIs look a bit like - email addresses (e.g., "joe@example.com"), the syntax is not exactly - the same as the syntax of email address in [MAILFORMAT]. For those - NAIs that include the realm component, the ID_RFC822_ADDR - identification type SHOULD be used. Responder implementations should - not attempt to verify that the contents actually conform to the exact - syntax given in [MAILFORMAT], but instead should accept any - reasonable-looking NAI. For NAIs that do not include the realm - component,the ID_KEY_ID identification type SHOULD be used. - -3.6. Certificate Payload - - The Certificate Payload, denoted CERT in this memo, provides a means - to transport certificates or other authentication-related information - via IKE. Certificate payloads SHOULD be included in an exchange if - certificates are available to the sender unless the peer has - indicated an ability to retrieve this information from elsewhere - using an HTTP_CERT_LOOKUP_SUPPORTED Notify payload. Note that the - term "Certificate Payload" is somewhat misleading, because not all - authentication mechanisms use certificates and data other than - certificates may be passed in this payload. - - The Certificate Payload is defined as follows: - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload !C! RESERVED ! Payload Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Cert Encoding ! ! - +-+-+-+-+-+-+-+-+ ! - ~ Certificate Data ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 12: Certificate Payload Format - - o Certificate Encoding (1 octet) - This field indicates the type of - certificate or certificate-related information contained in the - Certificate Data field. - - - - -Kaufman, et al. Expires August 27, 2006 [Page 71] - -Internet-Draft IKEv2bis February 2006 - - - Certificate Encoding Value - ------------------------------------------------- - RESERVED 0 - PKCS #7 wrapped X.509 certificate 1 - PGP Certificate 2 - DNS Signed Key 3 - X.509 Certificate - Signature 4 - Kerberos Token 6 - Certificate Revocation List (CRL) 7 - Authority Revocation List (ARL) 8 - SPKI Certificate 9 - X.509 Certificate - Attribute 10 - Raw RSA Key 11 - Hash and URL of X.509 certificate 12 - Hash and URL of X.509 bundle 13 - RESERVED to IANA 14 - 200 - PRIVATE USE 201 - 255 - - o Certificate Data (variable length) - Actual encoding of - certificate data. The type of certificate is indicated by the - Certificate Encoding field. - - The payload type for the Certificate Payload is thirty seven (37). - - Specific syntax is for some of the certificate type codes above is - not defined in this document. The types whose syntax is defined in - this document are: - - o X.509 Certificate - Signature (4) contains a DER encoded X.509 - certificate whose public key is used to validate the sender's AUTH - payload. - - o Certificate Revocation List (7) contains a DER encoded X.509 - certificate revocation list. - - o {{ Added "DER-encoded RSAPublicKey structure" from Clarif-3.6 }} - Raw RSA Key (11) contains a PKCS #1 encoded RSA key, that is, a - DER-encoded RSAPublicKey structure (see [RSA] and [PKCS1]). - - o Hash and URL encodings (12-13) allow IKE messages to remain short - by replacing long data structures with a 20 octet SHA-1 hash (see - [SHA]) of the replaced value followed by a variable-length URL - that resolves to the DER encoded data structure itself. This - improves efficiency when the endpoints have certificate data - cached and makes IKE less subject to denial of service attacks - that become easier to mount when IKE messages are large enough to - require IP fragmentation [DOSUDPPROT]. - - - - -Kaufman, et al. Expires August 27, 2006 [Page 72] - -Internet-Draft IKEv2bis February 2006 - - - Use the following ASN.1 definition for an X.509 bundle: - - CertBundle - { iso(1) identified-organization(3) dod(6) internet(1) - security(5) mechanisms(5) pkix(7) id-mod(0) - id-mod-cert-bundle(34) } - - DEFINITIONS EXPLICIT TAGS ::= - BEGIN - - IMPORTS - Certificate, CertificateList - FROM PKIX1Explicit88 - { iso(1) identified-organization(3) dod(6) - internet(1) security(5) mechanisms(5) pkix(7) - id-mod(0) id-pkix1-explicit(18) } ; - - CertificateOrCRL ::= CHOICE { - cert [0] Certificate, - crl [1] CertificateList } - - CertificateBundle ::= SEQUENCE OF CertificateOrCRL - - END - - Implementations MUST be capable of being configured to send and - accept up to four X.509 certificates in support of authentication, - and also MUST be capable of being configured to send and accept the - first two Hash and URL formats (with HTTP URLs). Implementations - SHOULD be capable of being configured to send and accept Raw RSA - keys. If multiple certificates are sent, the first certificate MUST - contain the public key used to sign the AUTH payload. The other - certificates may be sent in any order. - - {{ Clarif-3.6 }} Because the contents and use of some of the - certificate types are not defined, they SHOULD NOT be used. In - specific, implementations SHOULD NOT use the following types unless - they are later defined in a standards-track document: - - PKCS #7 wrapped X.509 certificate 1 - PGP Certificate 2 - DNS Signed Key 3 - Kerberos Token 6 - SPKI Certificate 9 - - - - - - - -Kaufman, et al. Expires August 27, 2006 [Page 73] - -Internet-Draft IKEv2bis February 2006 - - -3.7. Certificate Request Payload - - The Certificate Request Payload, denoted CERTREQ in this memo, - provides a means to request preferred certificates via IKE and can - appear in the IKE_INIT_SA response and/or the IKE_AUTH request. - Certificate Request payloads MAY be included in an exchange when the - sender needs to get the certificate of the receiver. If multiple CAs - are trusted and the cert encoding does not allow a list, then - multiple Certificate Request payloads SHOULD be transmitted. - - The Certificate Request Payload is defined as follows: - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload !C! RESERVED ! Payload Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Cert Encoding ! ! - +-+-+-+-+-+-+-+-+ ! - ~ Certification Authority ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 13: Certificate Request Payload Format - - o Certificate Encoding (1 octet) - Contains an encoding of the type - or format of certificate requested. Values are listed in - Section 3.6. - - o Certification Authority (variable length) - Contains an encoding - of an acceptable certification authority for the type of - certificate requested. - - The payload type for the Certificate Request Payload is thirty eight - (38). - - The Certificate Encoding field has the same values as those defined - in Section 3.6. The Certification Authority field contains an - indicator of trusted authorities for this certificate type. The - Certification Authority value is a concatenated list of SHA-1 hashes - of the public keys of trusted Certification Authorities (CAs). Each - is encoded as the SHA-1 hash of the Subject Public Key Info element - (see section 4.1.2.7 of [PKIX]) from each Trust Anchor certificate. - The twenty-octet hashes are concatenated and included with no other - formatting. - - {{ Clarif-3.6 }} The contents of the "Certification Authority" field - are defined only for X.509 certificates, which are types 4, 10, 12, - - - -Kaufman, et al. Expires August 27, 2006 [Page 74] - -Internet-Draft IKEv2bis February 2006 - - - and 13. Other values SHOULD NOT be used until standards-track - specifications that specify their use are published. - - Note that the term "Certificate Request" is somewhat misleading, in - that values other than certificates are defined in a "Certificate" - payload and requests for those values can be present in a Certificate - Request Payload. The syntax of the Certificate Request payload in - such cases is not defined in this document. - - The Certificate Request Payload is processed by inspecting the "Cert - Encoding" field to determine whether the processor has any - certificates of this type. If so, the "Certification Authority" - field is inspected to determine if the processor has any certificates - that can be validated up to one of the specified certification - authorities. This can be a chain of certificates. - - If an end-entity certificate exists that satisfies the criteria - specified in the CERTREQ, a certificate or certificate chain SHOULD - be sent back to the certificate requestor if the recipient of the - CERTREQ: - - o is configured to use certificate authentication, - - o is allowed to send a CERT payload, - - o has matching CA trust policy governing the current negotiation, - and - - o has at least one time-wise and usage appropriate end-entity - certificate chaining to a CA provided in the CERTREQ. - - Certificate revocation checking must be considered during the - chaining process used to select a certificate. Note that even if two - peers are configured to use two different CAs, cross-certification - relationships should be supported by appropriate selection logic. - - The intent is not to prevent communication through the strict - adherence of selection of a certificate based on CERTREQ, when an - alternate certificate could be selected by the sender that would - still enable the recipient to successfully validate and trust it - through trust conveyed by cross-certification, CRLs, or other out-of- - band configured means. Thus, the processing of a CERTREQ should be - seen as a suggestion for a certificate to select, not a mandated one. - If no certificates exist, then the CERTREQ is ignored. This is not - an error condition of the protocol. There may be cases where there - is a preferred CA sent in the CERTREQ, but an alternate might be - acceptable (perhaps after prompting a human operator). - - - - -Kaufman, et al. Expires August 27, 2006 [Page 75] - -Internet-Draft IKEv2bis February 2006 - - -3.8. Authentication Payload - - The Authentication Payload, denoted AUTH in this memo, contains data - used for authentication purposes. The syntax of the Authentication - data varies according to the Auth Method as specified below. - - The Authentication Payload is defined as follows: - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload !C! RESERVED ! Payload Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Auth Method ! RESERVED ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ Authentication Data ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 14: Authentication Payload Format - - o Auth Method (1 octet) - Specifies the method of authentication - used. Values defined are: - - * RSA Digital Signature (1) - Computed as specified in - Section 2.15 using an RSA private key over a PKCS#1 padded hash - (see [RSA] and [PKCS1]). {{ Clarif-3.2 }} To promote - interoperability, implementations that support this type SHOULD - support signatures that use SHA-1 as the hash function and - SHOULD use SHA-1 as the default hash function when generating - signatures. {{ Clarif-3.3 }} A newer version of PKCS#1 (v2.1) - defines two different encoding methods (ways of "padding the - hash") for signatures. However, IKEv2 and this document point - specifically to the PKCS#1 v2.0 which has only one encoding - method for signatures (EMSA-PKCS1- v1_5). - - * Shared Key Message Integrity Code (2) - Computed as specified - in Section 2.15 using the shared key associated with the - identity in the ID payload and the negotiated prf function - - * DSS Digital Signature (3) - Computed as specified in - Section 2.15 using a DSS private key (see [DSS]) over a SHA-1 - hash. - - * The values 0 and 4-200 are reserved to IANA. The values 201- - 255 are available for private use. - - - - -Kaufman, et al. Expires August 27, 2006 [Page 76] - -Internet-Draft IKEv2bis February 2006 - - - o Authentication Data (variable length) - see Section 2.15. - - The payload type for the Authentication Payload is thirty nine (39). - -3.9. Nonce Payload - - The Nonce Payload, denoted Ni and Nr in this memo for the initiator's - and responder's nonce respectively, contains random data used to - guarantee liveness during an exchange and protect against replay - attacks. - - The Nonce Payload is defined as follows: - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload !C! RESERVED ! Payload Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ Nonce Data ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 15: Nonce Payload Format - - o Nonce Data (variable length) - Contains the random data generated - by the transmitting entity. - - The payload type for the Nonce Payload is forty (40). - - The size of a Nonce MUST be between 16 and 256 octets inclusive. - Nonce values MUST NOT be reused. - -3.10. Notify Payload - - The Notify Payload, denoted N in this document, is used to transmit - informational data, such as error conditions and state transitions, - to an IKE peer. A Notify Payload may appear in a response message - (usually specifying why a request was rejected), in an INFORMATIONAL - Exchange (to report an error not in an IKE request), or in any other - message to indicate sender capabilities or to modify the meaning of - the request. - - The Notify Payload is defined as follows: - - - - - - - -Kaufman, et al. Expires August 27, 2006 [Page 77] - -Internet-Draft IKEv2bis February 2006 - - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload !C! RESERVED ! Payload Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Protocol ID ! SPI Size ! Notify Message Type ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ Security Parameter Index (SPI) ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ Notification Data ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 16: Notify Payload Format - - o Protocol ID (1 octet) - If this notification concerns an existing - SA, this field indicates the type of that SA. For IKE_SA - notifications, this field MUST be one (1). For notifications - concerning IPsec SAs this field MUST contain either (2) to - indicate AH or (3) to indicate ESP. {{ Clarif-7.8 }} For - notifications that do not relate to an existing SA, this field - MUST be sent as zero and MUST be ignored on receipt; this is - currently only true for the INVALID_SELECTORS and REKEY_SA - notifications. All other values for this field are reserved to - IANA for future assignment. - - o SPI Size (1 octet) - Length in octets of the SPI as defined by the - IPsec protocol ID or zero if no SPI is applicable. For a - notification concerning the IKE_SA, the SPI Size MUST be zero. - - o Notify Message Type (2 octets) - Specifies the type of - notification message. - - o SPI (variable length) - Security Parameter Index. - - o Notification Data (variable length) - Informational or error data - transmitted in addition to the Notify Message Type. Values for - this field are type specific (see below). - - The payload type for the Notify Payload is forty one (41). - -3.10.1. Notify Message Types - - Notification information can be error messages specifying why an SA - could not be established. It can also be status data that a process - - - -Kaufman, et al. Expires August 27, 2006 [Page 78] - -Internet-Draft IKEv2bis February 2006 - - - managing an SA database wishes to communicate with a peer process. - The table below lists the Notification messages and their - corresponding values. The number of different error statuses was - greatly reduced from IKEv1 both for simplification and to avoid - giving configuration information to probers. - - Types in the range 0 - 16383 are intended for reporting errors. An - implementation receiving a Notify payload with one of these types - that it does not recognize in a response MUST assume that the - corresponding request has failed entirely. {{ Demoted the SHOULD }} - Unrecognized error types in a request and status types in a request - or response MUST be ignored, and they should be logged. - - Notify payloads with status types MAY be added to any message and - MUST be ignored if not recognized. They are intended to indicate - capabilities, and as part of SA negotiation are used to negotiate - non-cryptographic parameters. - - NOTIFY messages: error types Value - ------------------------------------------------------------------- - - RESERVED 0 - - UNSUPPORTED_CRITICAL_PAYLOAD 1 - Sent if the payload has the "critical" bit set and the payload - type is not recognized. Notification Data contains the one-octet - payload type. - - INVALID_IKE_SPI 4 - Indicates an IKE message was received with an unrecognized - destination SPI. This usually indicates that the recipient has - rebooted and forgotten the existence of an IKE_SA. - - INVALID_MAJOR_VERSION 5 - Indicates the recipient cannot handle the version of IKE - specified in the header. The closest version number that the - recipient can support will be in the reply header. - - INVALID_SYNTAX 7 - Indicates the IKE message that was received was invalid because - some type, length, or value was out of range or because the - request was rejected for policy reasons. To avoid a denial of - service attack using forged messages, this status may only be - returned for and in an encrypted packet if the message ID and - cryptographic checksum were valid. To avoid leaking information - to someone probing a node, this status MUST be sent in response - to any error not covered by one of the other status types. - {{ Demoted the SHOULD }} To aid debugging, more detailed error - - - -Kaufman, et al. Expires August 27, 2006 [Page 79] - -Internet-Draft IKEv2bis February 2006 - - - information should be written to a console or log. - - INVALID_MESSAGE_ID 9 - Sent when an IKE message ID outside the supported window is - received. This Notify MUST NOT be sent in a response; the invalid - request MUST NOT be acknowledged. Instead, inform the other side - by initiating an INFORMATIONAL exchange with Notification data - containing the four octet invalid message ID. Sending this - notification is optional, and notifications of this type MUST be - rate limited. - - INVALID_SPI 11 - MAY be sent in an IKE INFORMATIONAL exchange when a node receives - an ESP or AH packet with an invalid SPI. The Notification Data - contains the SPI of the invalid packet. This usually indicates a - node has rebooted and forgotten an SA. If this Informational - Message is sent outside the context of an IKE_SA, it should only - be used by the recipient as a "hint" that something might be - wrong (because it could easily be forged). - - NO_PROPOSAL_CHOSEN 14 - None of the proposed crypto suites was acceptable. - - INVALID_KE_PAYLOAD 17 - The D-H Group # field in the KE payload is not the group # - selected by the responder for this exchange. There are two octets - of data associated with this notification: the accepted D-H Group - # in big endian order. - - AUTHENTICATION_FAILED 24 - Sent in the response to an IKE_AUTH message when for some reason - the authentication failed. There is no associated data. - - SINGLE_PAIR_REQUIRED 34 - This error indicates that a CREATE_CHILD_SA request is - unacceptable because its sender is only willing to accept traffic - selectors specifying a single pair of addresses. The requestor is - expected to respond by requesting an SA for only the specific - traffic it is trying to forward. - - NO_ADDITIONAL_SAS 35 - This error indicates that a CREATE_CHILD_SA request is - unacceptable because the responder is unwilling to accept any - more CHILD_SAs on this IKE_SA. Some minimal implementations may - only accept a single CHILD_SA setup in the context of an initial - IKE exchange and reject any subsequent attempts to add more. - - INTERNAL_ADDRESS_FAILURE 36 - - - -Kaufman, et al. Expires August 27, 2006 [Page 80] - -Internet-Draft IKEv2bis February 2006 - - - Indicates an error assigning an internal address (i.e., - INTERNAL_IP4_ADDRESS or INTERNAL_IP6_ADDRESS) during the - processing of a Configuration Payload by a responder. If this - error is generated within an IKE_AUTH exchange, no CHILD_SA will - be created. - - FAILED_CP_REQUIRED 37 - Sent by responder in the case where CP(CFG_REQUEST) was expected - but not received, and so is a conflict with locally configured - policy. There is no associated data. - - TS_UNACCEPTABLE 38 - Indicates that none of the addresses/protocols/ports in the - supplied traffic selectors is acceptable. - - INVALID_SELECTORS 39 - MAY be sent in an IKE INFORMATIONAL exchange when a node receives - an ESP or AH packet whose selectors do not match those of the SA - on which it was delivered (and that caused the packet to be - dropped). The Notification Data contains the start of the - offending packet (as in ICMP messages) and the SPI field of the - notification is set to match the SPI of the IPsec SA. - - RESERVED TO IANA 40-8191 - - PRIVATE USE 8192-16383 - - - NOTIFY messages: status types Value - ------------------------------------------------------------------- - - INITIAL_CONTACT 16384 - This notification asserts that this IKE_SA is the only IKE_SA - currently active between the authenticated identities. It MAY be - sent when an IKE_SA is established after a crash, and the - recipient MAY use this information to delete any other IKE_SAs it - has to the same authenticated identity without waiting for a - timeout. This notification MUST NOT be sent by an entity that may - be replicated (e.g., a roaming user's credentials where the user - is allowed to connect to the corporate firewall from two remote - systems at the same time). {{ Clarif-7.9 }} The INITIAL_CONTACT - notification, if sent, SHOULD be in the first IKE_AUTH request, - not as a separate exchange afterwards; however, receiving - parties need to deal with it in other requests. - - SET_WINDOW_SIZE 16385 - This notification asserts that the sending endpoint is capable of - keeping state for multiple outstanding exchanges, permitting the - - - -Kaufman, et al. Expires August 27, 2006 [Page 81] - -Internet-Draft IKEv2bis February 2006 - - - recipient to send multiple requests before getting a response to - the first. The data associated with a SET_WINDOW_SIZE - notification MUST be 4 octets long and contain the big endian - representation of the number of messages the sender promises to - keep. Window size is always one until the initial exchanges - complete. - - ADDITIONAL_TS_POSSIBLE 16386 - This notification asserts that the sending endpoint narrowed the - proposed traffic selectors but that other traffic selectors would - also have been acceptable, though only in a separate SA (see - section 2.9). There is no data associated with this Notify type. - It may be sent only as an additional payload in a message - including accepted TSs. - - IPCOMP_SUPPORTED 16387 - This notification may be included only in a message containing an - SA payload negotiating a CHILD_SA and indicates a willingness by - its sender to use IPComp on this SA. The data associated with - this notification includes a two-octet IPComp CPI followed by a - one-octet transform ID optionally followed by attributes whose - length and format are defined by that transform ID. A message - proposing an SA may contain multiple IPCOMP_SUPPORTED - notifications to indicate multiple supported algorithms. A - message accepting an SA may contain at most one. - - The transform IDs currently defined are: - - Name Number Defined In - ------------------------------------- - RESERVED 0 - IPCOMP_OUI 1 - IPCOMP_DEFLATE 2 RFC 2394 - IPCOMP_LZS 3 RFC 2395 - IPCOMP_LZJH 4 RFC 3051 - RESERVED TO IANA 5-240 - PRIVATE USE 241-255 - - NAT_DETECTION_SOURCE_IP 16388 - This notification is used by its recipient to determine whether - the source is behind a NAT box. The data associated with this - notification is a SHA-1 digest of the SPIs (in the order they - appear in the header), IP address, and port on which this packet - was sent. There MAY be multiple Notify payloads of this type in a - message if the sender does not know which of several network - attachments will be used to send the packet. The recipient of - this notification MAY compare the supplied value to a SHA-1 hash - of the SPIs, source IP address, and port, and if they don't match - - - -Kaufman, et al. Expires August 27, 2006 [Page 82] - -Internet-Draft IKEv2bis February 2006 - - - it SHOULD enable NAT traversal (see section 2.23). Alternately, - it MAY reject the connection attempt if NAT traversal is not - supported. - - NAT_DETECTION_DESTINATION_IP 16389 - This notification is used by its recipient to determine whether - it is behind a NAT box. The data associated with this - notification is a SHA-1 digest of the SPIs (in the order they - appear in the header), IP address, and port to which this packet - was sent. The recipient of this notification MAY compare the - supplied value to a hash of the SPIs, destination IP address, and - port, and if they don't match it SHOULD invoke NAT traversal (see - section 2.23). If they don't match, it means that this end is - behind a NAT and this end SHOULD start sending keepalive packets - as defined in [UDPENCAPS]. Alternately, it MAY reject the - connection attempt if NAT traversal is not supported. - - COOKIE 16390 - This notification MAY be included in an IKE_SA_INIT response. It - indicates that the request should be retried with a copy of this - notification as the first payload. This notification MUST be - included in an IKE_SA_INIT request retry if a COOKIE notification - was included in the initial response. The data associated with - this notification MUST be between 1 and 64 octets in length - (inclusive). - - USE_TRANSPORT_MODE 16391 - This notification MAY be included in a request message that also - includes an SA payload requesting a CHILD_SA. It requests that - the CHILD_SA use transport mode rather than tunnel mode for the - SA created. If the request is accepted, the response MUST also - include a notification of type USE_TRANSPORT_MODE. If the - responder declines the request, the CHILD_SA will be established - in tunnel mode. If this is unacceptable to the initiator, the - initiator MUST delete the SA. Note: Except when using this option - to negotiate transport mode, all CHILD_SAs will use tunnel mode. - - Note: The ECN decapsulation modifications specified in - [IPSECARCH] MUST be performed for every tunnel mode SA created - by IKEv2. - - HTTP_CERT_LOOKUP_SUPPORTED 16392 - This notification MAY be included in any message that can include - a CERTREQ payload and indicates that the sender is capable of - looking up certificates based on an HTTP-based URL (and hence - presumably would prefer to receive certificate specifications in - that format). - - - - -Kaufman, et al. Expires August 27, 2006 [Page 83] - -Internet-Draft IKEv2bis February 2006 - - - REKEY_SA 16393 - This notification MUST be included in a CREATE_CHILD_SA exchange - if the purpose of the exchange is to replace an existing ESP or - AH SA. The SPI field identifies the SA being rekeyed. - {{ Clarif-5.4 }} The SPI placed in the REKEY_SA - notification is the SPI the exchange initiator would expect in - inbound ESP or AH packets. There is no data. - - ESP_TFC_PADDING_NOT_SUPPORTED 16394 - This notification asserts that the sending endpoint will NOT - accept packets that contain Flow Confidentiality (TFC) padding. - {{ Clarif-4.5 }} The scope of this message is a single - CHILD_SA, and thus this notification is included in messages - containing an SA payload negotiating a CHILD_SA. If neither - endpoint accepts TFC padding, this notification SHOULD be - included in both the request proposing an SA and the response - accepting it. If this notification is included in only one of - the messages, TFC padding can still be sent in the other - direction. - - NON_FIRST_FRAGMENTS_ALSO 16395 - Used for fragmentation control. See [IPSECARCH] for explanation. - {{ Clarif-4.6 }} Sending non-first fragments is - enabled only if NON_FIRST_FRAGMENTS_ALSO notification is - included in both the request proposing an SA and the response - accepting it. If the peer rejects this proposal, the peer only - omits NON_FIRST_FRAGMENTS_ALSO notification from the response, - but does not reject the whole CHILD_SA creation. - - RESERVED TO IANA 16396-40959 - - PRIVATE USE 40960-65535 - -3.11. Delete Payload - - The Delete Payload, denoted D in this memo, contains a protocol - specific security association identifier that the sender has removed - from its security association database and is, therefore, no longer - valid. Figure 17 shows the format of the Delete Payload. It is - possible to send multiple SPIs in a Delete payload; however, each SPI - MUST be for the same protocol. Mixing of protocol identifiers MUST - NOT be performed in the Delete payload. It is permitted, however, to - include multiple Delete payloads in a single INFORMATIONAL exchange - where each Delete payload lists SPIs for a different protocol. - - Deletion of the IKE_SA is indicated by a protocol ID of 1 (IKE) but - no SPIs. Deletion of a CHILD_SA, such as ESP or AH, will contain the - IPsec protocol ID of that protocol (2 for AH, 3 for ESP), and the SPI - - - -Kaufman, et al. Expires August 27, 2006 [Page 84] - -Internet-Draft IKEv2bis February 2006 - - - is the SPI the sending endpoint would expect in inbound ESP or AH - packets. - - The Delete Payload is defined as follows: - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload !C! RESERVED ! Payload Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Protocol ID ! SPI Size ! # of SPIs ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ Security Parameter Index(es) (SPI) ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 17: Delete Payload Format - - o Protocol ID (1 octet) - Must be 1 for an IKE_SA, 2 for AH, or 3 - for ESP. - - o SPI Size (1 octet) - Length in octets of the SPI as defined by the - protocol ID. It MUST be zero for IKE (SPI is in message header) - or four for AH and ESP. - - o # of SPIs (2 octets) - The number of SPIs contained in the Delete - payload. The size of each SPI is defined by the SPI Size field. - - o Security Parameter Index(es) (variable length) - Identifies the - specific security association(s) to delete. The length of this - field is determined by the SPI Size and # of SPIs fields. - - The payload type for the Delete Payload is forty two (42). - -3.12. Vendor ID Payload - - The Vendor ID Payload, denoted V in this memo, contains a vendor - defined constant. The constant is used by vendors to identify and - recognize remote instances of their implementations. This mechanism - allows a vendor to experiment with new features while maintaining - backward compatibility. - - A Vendor ID payload MAY announce that the sender is capable to - accepting certain extensions to the protocol, or it MAY simply - identify the implementation as an aid in debugging. A Vendor ID - payload MUST NOT change the interpretation of any information defined - in this specification (i.e., the critical bit MUST be set to 0). - - - -Kaufman, et al. Expires August 27, 2006 [Page 85] - -Internet-Draft IKEv2bis February 2006 - - - Multiple Vendor ID payloads MAY be sent. An implementation is NOT - REQUIRED to send any Vendor ID payload at all. - - A Vendor ID payload may be sent as part of any message. Reception of - a familiar Vendor ID payload allows an implementation to make use of - Private USE numbers described throughout this memo-- private - payloads, private exchanges, private notifications, etc. Unfamiliar - Vendor IDs MUST be ignored. - - Writers of Internet-Drafts who wish to extend this protocol MUST - define a Vendor ID payload to announce the ability to implement the - extension in the Internet-Draft. It is expected that Internet-Drafts - that gain acceptance and are standardized will be given "magic - numbers" out of the Future Use range by IANA, and the requirement to - use a Vendor ID will go away. - - The Vendor ID Payload fields are defined as follows: - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload !C! RESERVED ! Payload Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ Vendor ID (VID) ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 18: Vendor ID Payload Format - - o Vendor ID (variable length) - It is the responsibility of the - person choosing the Vendor ID to assure its uniqueness in spite of - the absence of any central registry for IDs. Good practice is to - include a company name, a person name, or some such. If you want - to show off, you might include the latitude and longitude and time - where you were when you chose the ID and some random input. A - message digest of a long unique string is preferable to the long - unique string itself. - - The payload type for the Vendor ID Payload is forty three (43). - -3.13. Traffic Selector Payload - - The Traffic Selector Payload, denoted TS in this memo, allows peers - to identify packet flows for processing by IPsec security services. - The Traffic Selector Payload consists of the IKE generic payload - header followed by individual traffic selectors as follows: - - - - -Kaufman, et al. Expires August 27, 2006 [Page 86] - -Internet-Draft IKEv2bis February 2006 - - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload !C! RESERVED ! Payload Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Number of TSs ! RESERVED ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ <Traffic Selectors> ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 19: Traffic Selectors Payload Format - - o Number of TSs (1 octet) - Number of traffic selectors being - provided. - - o RESERVED - This field MUST be sent as zero and MUST be ignored on - receipt. - - o Traffic Selectors (variable length) - One or more individual - traffic selectors. - - The length of the Traffic Selector payload includes the TS header and - all the traffic selectors. - - The payload type for the Traffic Selector payload is forty four (44) - for addresses at the initiator's end of the SA and forty five (45) - for addresses at the responder's end. - - {{ Clarif-4.7 }} There is no requirement that TSi and TSr contain the - same number of individual traffic selectors. Thus, they are - interpreted as follows: a packet matches a given TSi/TSr if it - matches at least one of the individual selectors in TSi, and at least - one of the individual selectors in TSr. - - For instance, the following traffic selectors: - - TSi = ((17, 100, 192.0.1.66-192.0.1.66), - (17, 200, 192.0.1.66-192.0.1.66)) - TSr = ((17, 300, 0.0.0.0-255.255.255.255), - (17, 400, 0.0.0.0-255.255.255.255)) - - would match UDP packets from 192.0.1.66 to anywhere, with any of the - four combinations of source/destination ports (100,300), (100,400), - (200,300), and (200, 400). - - Thus, some types of policies may require several CHILD_SA pairs. For - - - -Kaufman, et al. Expires August 27, 2006 [Page 87] - -Internet-Draft IKEv2bis February 2006 - - - instance, a policy matching only source/destination ports (100,300) - and (200,400), but not the other two combinations, cannot be - negotiated as a single CHILD_SA pair. - -3.13.1. Traffic Selector - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! TS Type !IP Protocol ID*| Selector Length | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Start Port* | End Port* | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ Starting Address* ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ Ending Address* ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 20: Traffic Selector - - *Note: All fields other than TS Type and Selector Length depend on - the TS Type. The fields shown are for TS Types 7 and 8, the only two - values currently defined. - - o TS Type (one octet) - Specifies the type of traffic selector. - - o IP protocol ID (1 octet) - Value specifying an associated IP - protocol ID (e.g., UDP/TCP/ICMP). A value of zero means that the - protocol ID is not relevant to this traffic selector-- the SA can - carry all protocols. - - o Selector Length - Specifies the length of this Traffic Selector - Substructure including the header. - - o Start Port (2 octets) - Value specifying the smallest port number - allowed by this Traffic Selector. For protocols for which port is - undefined, or if all ports are allowed, this field MUST be zero. - For the ICMP protocol, the two one-octet fields Type and Code are - treated as a single 16-bit integer (with Type in the most - significant eight bits and Code in the least significant eight - bits) port number for the purposes of filtering based on this - field. - - - - - -Kaufman, et al. Expires August 27, 2006 [Page 88] - -Internet-Draft IKEv2bis February 2006 - - - o End Port (2 octets) - Value specifying the largest port number - allowed by this Traffic Selector. For protocols for which port is - undefined, or if all ports are allowed, this field MUST be 65535. - For the ICMP protocol, the two one-octet fields Type and Code are - treated as a single 16-bit integer (with Type in the most - significant eight bits and Code in the least significant eight - bits) port number for the purposed of filtering based on this - field. - - o Starting Address - The smallest address included in this Traffic - Selector (length determined by TS type). - - o Ending Address - The largest address included in this Traffic - Selector (length determined by TS type). - - Systems that are complying with [IPSECARCH] that wish to indicate - "ANY" ports MUST set the start port to 0 and the end port to 65535; - note that according to [IPSECARCH], "ANY" includes "OPAQUE". Systems - working with [IPSECARCH] that wish to indicate "OPAQUE" ports, but - not "ANY" ports, MUST set the start port to 65535 and the end port to - 0. - - {{ Added from Clarif-4.8 }} The traffic selector types 7 and 8 can - also refer to ICMP type and code fields. Note, however, that ICMP - packets do not have separate source and destination port fields. The - method for specifying the traffic selectors for ICMP is shown by - example in Section 4.4.1.3 of [IPSECARCH]. - - {{ Added from Clarif-4.9 }} Traffic selectors can use IP Protocol ID - 135 to match the IPv6 mobility header [MIPV6]. This document does - not specify how to represent the "MH Type" field in traffic - selectors, although it is likely that a different document will - specify this in the future. Note that [IPSECARCH] says that the IPv6 - mobility header (MH) message type is placed in the most significant - eight bits of the 16-bit local port selector. The direction - semantics of TSi/TSr port fields are the same as for ICMP. - - The following table lists the assigned values for the Traffic - Selector Type field and the corresponding Address Selector Data. - - - - - - - - - - - - -Kaufman, et al. Expires August 27, 2006 [Page 89] - -Internet-Draft IKEv2bis February 2006 - - - TS Type Value - ------------------------------------------------------------------- - RESERVED 0-6 - - TS_IPV4_ADDR_RANGE 7 - - A range of IPv4 addresses, represented by two four-octet - values. The first value is the beginning IPv4 address - (inclusive) and the second value is the ending IPv4 address - (inclusive). All addresses falling between the two specified - addresses are considered to be within the list. - - TS_IPV6_ADDR_RANGE 8 - - A range of IPv6 addresses, represented by two sixteen-octet - values. The first value is the beginning IPv6 address - (inclusive) and the second value is the ending IPv6 address - (inclusive). All addresses falling between the two specified - addresses are considered to be within the list. - - RESERVED TO IANA 9-240 - PRIVATE USE 241-255 - -3.14. Encrypted Payload - - The Encrypted Payload, denoted SK{...} or E in this memo, contains - other payloads in encrypted form. The Encrypted Payload, if present - in a message, MUST be the last payload in the message. Often, it is - the only payload in the message. - - The algorithms for encryption and integrity protection are negotiated - during IKE_SA setup, and the keys are computed as specified in - Section 2.14 and Section 2.18. - - The encryption and integrity protection algorithms are modeled after - the ESP algorithms described in RFCs 2104 [HMAC], 4303 [ESP], and - 2451 [ESPCBC]. This document completely specifies the cryptographic - processing of IKE data, but those documents should be consulted for - design rationale. We require a block cipher with a fixed block size - and an integrity check algorithm that computes a fixed-length - checksum over a variable size message. - - The payload type for an Encrypted payload is forty six (46). The - Encrypted Payload consists of the IKE generic payload header followed - by individual fields as follows: - - - - - - -Kaufman, et al. Expires August 27, 2006 [Page 90] - -Internet-Draft IKEv2bis February 2006 - - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload !C! RESERVED ! Payload Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Initialization Vector ! - ! (length is block size for encryption algorithm) ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ~ Encrypted IKE Payloads ~ - + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! Padding (0-255 octets) ! - +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+ - ! ! Pad Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ~ Integrity Checksum Data ~ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 21: Encrypted Payload Format - - o Next Payload - The payload type of the first embedded payload. - Note that this is an exception in the standard header format, - since the Encrypted payload is the last payload in the message and - therefore the Next Payload field would normally be zero. But - because the content of this payload is embedded payloads and there - was no natural place to put the type of the first one, that type - is placed here. - - o Payload Length - Includes the lengths of the header, IV, Encrypted - IKE Payloads, Padding, Pad Length, and Integrity Checksum Data. - - o Initialization Vector - A randomly chosen value whose length is - equal to the block length of the underlying encryption algorithm. - Recipients MUST accept any value. Senders SHOULD either pick this - value pseudo-randomly and independently for each message or use - the final ciphertext block of the previous message sent. Senders - MUST NOT use the same value for each message, use a sequence of - values with low hamming distance (e.g., a sequence number), or use - ciphertext from a received message. - - o IKE Payloads are as specified earlier in this section. This field - is encrypted with the negotiated cipher. - - o Padding MAY contain any value chosen by the sender, and MUST have - a length that makes the combination of the Payloads, the Padding, - and the Pad Length to be a multiple of the encryption block size. - This field is encrypted with the negotiated cipher. - - - - - -Kaufman, et al. Expires August 27, 2006 [Page 91] - -Internet-Draft IKEv2bis February 2006 - - - o Pad Length is the length of the Padding field. The sender SHOULD - set the Pad Length to the minimum value that makes the combination - of the Payloads, the Padding, and the Pad Length a multiple of the - block size, but the recipient MUST accept any length that results - in proper alignment. This field is encrypted with the negotiated - cipher. - - o Integrity Checksum Data is the cryptographic checksum of the - entire message starting with the Fixed IKE Header through the Pad - Length. The checksum MUST be computed over the encrypted message. - Its length is determined by the integrity algorithm negotiated. - -3.15. Configuration Payload - - The Configuration payload, denoted CP in this document, is used to - exchange configuration information between IKE peers. The exchange - is for an IRAC to request an internal IP address from an IRAS and to - exchange other information of the sort that one would acquire with - Dynamic Host Configuration Protocol (DHCP) if the IRAC were directly - connected to a LAN. - - Configuration payloads are of type CFG_REQUEST/CFG_REPLY or CFG_SET/ - CFG_ACK (see CFG Type in the payload description below). CFG_REQUEST - and CFG_SET payloads may optionally be added to any IKE request. The - IKE response MUST include either a corresponding CFG_REPLY or CFG_ACK - or a Notify payload with an error type indicating why the request - could not be honored. An exception is that a minimal implementation - MAY ignore all CFG_REQUEST and CFG_SET payloads, so a response - message without a corresponding CFG_REPLY or CFG_ACK MUST be accepted - as an indication that the request was not supported. - - "CFG_REQUEST/CFG_REPLY" allows an IKE endpoint to request information - from its peer. If an attribute in the CFG_REQUEST Configuration - Payload is not zero-length, it is taken as a suggestion for that - attribute. The CFG_REPLY Configuration Payload MAY return that - value, or a new one. It MAY also add new attributes and not include - some requested ones. Requestors MUST ignore returned attributes that - they do not recognize. - - Some attributes MAY be multi-valued, in which case multiple attribute - values of the same type are sent and/or returned. Generally, all - values of an attribute are returned when the attribute is requested. - For some attributes (in this version of the specification only - internal addresses), multiple requests indicates a request that - multiple values be assigned. For these attributes, the number of - values returned SHOULD NOT exceed the number requested. - - If the data type requested in a CFG_REQUEST is not recognized or not - - - -Kaufman, et al. Expires August 27, 2006 [Page 92] - -Internet-Draft IKEv2bis February 2006 - - - supported, the responder MUST NOT return an error type but rather - MUST either send a CFG_REPLY that MAY be empty or a reply not - containing a CFG_REPLY payload at all. Error returns are reserved - for cases where the request is recognized but cannot be performed as - requested or the request is badly formatted. - - "CFG_SET/CFG_ACK" allows an IKE endpoint to push configuration data - to its peer. In this case, the CFG_SET Configuration Payload - contains attributes the initiator wants its peer to alter. The - responder MUST return a Configuration Payload if it accepted any of - the configuration data and it MUST contain the attributes that the - responder accepted with zero-length data. Those attributes that it - did not accept MUST NOT be in the CFG_ACK Configuration Payload. If - no attributes were accepted, the responder MUST return either an - empty CFG_ACK payload or a response message without a CFG_ACK - payload. There are currently no defined uses for the CFG_SET/CFG_ACK - exchange, though they may be used in connection with extensions based - on Vendor IDs. An minimal implementation of this specification MAY - ignore CFG_SET payloads. - - {{ Demoted the SHOULD }} Extensions via the CP payload should not be - used for general purpose management. Its main intent is to provide a - bootstrap mechanism to exchange information within IPsec from IRAS to - IRAC. While it MAY be useful to use such a method to exchange - information between some Security Gateways (SGW) or small networks, - existing management protocols such as DHCP [DHCP], RADIUS [RADIUS], - SNMP, or LDAP [LDAP] should be preferred for enterprise management as - well as subsequent information exchanges. - - The Configuration Payload is defined as follows: - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload !C! RESERVED ! Payload Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! CFG Type ! RESERVED ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ Configuration Attributes ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 22: Configuration Payload Format - - The payload type for the Configuration Payload is forty seven (47). - - - - - -Kaufman, et al. Expires August 27, 2006 [Page 93] - -Internet-Draft IKEv2bis February 2006 - - - o CFG Type (1 octet) - The type of exchange represented by the - Configuration Attributes. - - CFG Type Value - -------------------------- - RESERVED 0 - CFG_REQUEST 1 - CFG_REPLY 2 - CFG_SET 3 - CFG_ACK 4 - RESERVED TO IANA 5-127 - PRIVATE USE 128-255 - - o RESERVED (3 octets) - MUST be sent as zero; MUST be ignored on - receipt. - - o Configuration Attributes (variable length) - These are type length - values specific to the Configuration Payload and are defined - below. There may be zero or more Configuration Attributes in this - payload. - -3.15.1. Configuration Attributes - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - !R| Attribute Type ! Length | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | | - ~ Value ~ - | | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 23: Configuration Attribute Format - - o Reserved (1 bit) - This bit MUST be set to zero and MUST be - ignored on receipt. - - o Attribute Type (15 bits) - A unique identifier for each of the - Configuration Attribute Types. - - o Length (2 octets) - Length in octets of Value. - - o Value (0 or more octets) - The variable-length value of this - Configuration Attribute. The following attribute types have been - defined: - - - - - -Kaufman, et al. Expires August 27, 2006 [Page 94] - -Internet-Draft IKEv2bis February 2006 - - - Multi- - Attribute Type Value Valued Length - ------------------------------------------------------- - RESERVED 0 - INTERNAL_IP4_ADDRESS 1 YES* 0 or 4 octets - INTERNAL_IP4_NETMASK 2 NO 0 or 4 octets - INTERNAL_IP4_DNS 3 YES 0 or 4 octets - INTERNAL_IP4_NBNS 4 YES 0 or 4 octets - INTERNAL_ADDRESS_EXPIRY 5 NO 0 or 4 octets - INTERNAL_IP4_DHCP 6 YES 0 or 4 octets - APPLICATION_VERSION 7 NO 0 or more - INTERNAL_IP6_ADDRESS 8 YES* 0 or 17 octets - RESERVED 9 - INTERNAL_IP6_DNS 10 YES 0 or 16 octets - INTERNAL_IP6_NBNS 11 YES 0 or 16 octets - INTERNAL_IP6_DHCP 12 YES 0 or 16 octets - INTERNAL_IP4_SUBNET 13 YES 0 or 8 octets - SUPPORTED_ATTRIBUTES 14 NO Multiple of 2 - INTERNAL_IP6_SUBNET 15 YES 17 octets - RESERVED TO IANA 16-16383 - PRIVATE USE 16384-32767 - - * These attributes may be multi-valued on return only if - multiple values were requested. - - o INTERNAL_IP4_ADDRESS, INTERNAL_IP6_ADDRESS - An address on the - internal network, sometimes called a red node address or private - address and MAY be a private address on the Internet. {{ - Clarif-6.2}} In a request message, the address specified is a - requested address (or a zero-length address if no specific address - is requested). If a specific address is requested, it likely - indicates that a previous connection existed with this address and - the requestor would like to reuse that address. With IPv6, a - requestor MAY supply the low-order address bytes it wants to use. - Multiple internal addresses MAY be requested by requesting - multiple internal address attributes. The responder MAY only send - up to the number of addresses requested. The INTERNAL_IP6_ADDRESS - is made up of two fields: the first is a 16-octet IPv6 address, - and the second is a one-octet prefix-length as defined in - [ADDRIPV6]. - - The requested address is valid until the expiry time defined with - the INTERNAL_ADDRESS_EXPIRY attribute or there are no IKE_SAs - between the peers. - - o INTERNAL_IP4_NETMASK - The internal network's netmask. Only one - netmask is allowed in the request and reply messages (e.g., - 255.255.255.0), and it MUST be used only with an - - - -Kaufman, et al. Expires August 27, 2006 [Page 95] - -Internet-Draft IKEv2bis February 2006 - - - INTERNAL_IP4_ADDRESS attribute. {{ Clarif-6.4 }} - INTERNAL_IP4_NETMASK in a CFG_REPLY means roughly the same thing - as INTERNAL_IP4_SUBNET containing the same information ("send - traffic to these addresses through me"), but also implies a link - boundary. For instance, the client could use its own address and - the netmask to calculate the broadcast address of the link. An - empty INTERNAL_IP4_NETMASK attribute can be included in a - CFG_REQUEST to request this information (although the gateway can - send the information even when not requested). Non-empty values - for this attribute in a CFG_REQUEST do not make sense and thus - MUST NOT be included. - - o INTERNAL_IP4_DNS, INTERNAL_IP6_DNS - Specifies an address of a DNS - server within the network. Multiple DNS servers MAY be requested. - The responder MAY respond with zero or more DNS server attributes. - - o INTERNAL_IP4_NBNS, INTERNAL_IP6_NBNS - Specifies an address of a - NetBios Name Server (WINS) within the network. Multiple NBNS - servers MAY be requested. The responder MAY respond with zero or - more NBNS server attributes. {{ Clarif-6.6 }} NetBIOS is not - defined for IPv6; therefore, INTERNAL_IP6_NBNS SHOULD NOT be used. - - o INTERNAL_ADDRESS_EXPIRY - Specifies the number of seconds that the - host can use the internal IP address. The host MUST renew the IP - address before this expiry time. Only one of these attributes MAY - be present in the reply. {{ Clarif-6.7 }} Expiry times and - explicit renewals are primarily useful in environments like DHCP, - where the server cannot reliably know when the client has gone - away. However, in IKEv2, this is known, and the gateway can - simply free the address when the IKE_SA is deleted. Further, - supporting renewals is not mandatory. Thus - INTERNAL_ADDRESS_EXPIRY attribute MUST NOT be used. - - o INTERNAL_IP4_DHCP, INTERNAL_IP6_DHCP - Instructs the host to send - any internal DHCP requests to the address contained within the - attribute. Multiple DHCP servers MAY be requested. The responder - MAY respond with zero or more DHCP server attributes. - - o APPLICATION_VERSION - The version or application information of - the IPsec host. This is a string of printable ASCII characters - that is NOT null terminated. - - o INTERNAL_IP4_SUBNET - The protected sub-networks that this edge- - device protects. This attribute is made up of two fields: the - first being an IP address and the second being a netmask. - Multiple sub-networks MAY be requested. The responder MAY respond - with zero or more sub-network attributes. - - - - -Kaufman, et al. Expires August 27, 2006 [Page 96] - -Internet-Draft IKEv2bis February 2006 - - - o SUPPORTED_ATTRIBUTES - When used within a Request, this attribute - MUST be zero-length and specifies a query to the responder to - reply back with all of the attributes that it supports. The - response contains an attribute that contains a set of attribute - identifiers each in 2 octets. The length divided by 2 (octets) - would state the number of supported attributes contained in the - response. - - o INTERNAL_IP6_SUBNET - The protected sub-networks that this edge- - device protects. This attribute is made up of two fields: the - first is a 16-octet IPv6 address, and the second is a one-octet - prefix-length as defined in [ADDRIPV6]. Multiple sub-networks MAY - be requested. The responder MAY respond with zero or more sub- - network attributes. - - Note that no recommendations are made in this document as to how an - implementation actually figures out what information to send in a - reply. That is, we do not recommend any specific method of an IRAS - determining which DNS server should be returned to a requesting IRAC. - -3.15.2. Meaning of INTERNAL_IP4_SUBNET/INTERNAL_IP6_SUBNET - - {{ Section added based on Clarif-6.3 }} - - INTERNAL_IP4/6_SUBNET attributes can indicate additional subnets, - ones that need one or more separate SAs, that can be reached through - the gateway that announces the attributes. INTERNAL_IP4/6_SUBNET - attributes may also express the gateway's policy about what traffic - should be sent through the gateway; the client can choose whether - other traffic (covered by TSr, but not in INTERNAL_IP4/6_SUBNET) is - sent through the gateway or directly to the destination. Thus, - traffic to the addresses listed in the INTERNAL_IP4/6_SUBNET - attributes should be sent through the gateway that announces the - attributes. If there are no existing IPsec SAs whose traffic - selectors cover the address in question, new SAs need to be created. - - For instance, if there are two subnets, 192.0.1.0/26 and - 192.0.2.0/24, and the client's request contains the following: - - CP(CFG_REQUEST) = - INTERNAL_IP4_ADDRESS() - TSi = (0, 0-65535, 0.0.0.0-255.255.255.255) - TSr = (0, 0-65535, 0.0.0.0-255.255.255.255) - - then a valid response could be the following (in which TSr and - INTERNAL_IP4_SUBNET contain the same information): - - - - - -Kaufman, et al. Expires August 27, 2006 [Page 97] - -Internet-Draft IKEv2bis February 2006 - - - CP(CFG_REPLY) = - INTERNAL_IP4_ADDRESS(192.0.1.234) - INTERNAL_IP4_SUBNET(192.0.1.0/255.255.255.192) - INTERNAL_IP4_SUBNET(192.0.2.0/255.255.255.0) - TSi = (0, 0-65535, 192.0.1.234-192.0.1.234) - TSr = ((0, 0-65535, 192.0.1.0-192.0.1.63), - (0, 0-65535, 192.0.2.0-192.0.2.255)) - - In these cases, the INTERNAL_IP4_SUBNET does not really carry any - useful information. - - A different possible reply would have been this: - - CP(CFG_REPLY) = - INTERNAL_IP4_ADDRESS(192.0.1.234) - INTERNAL_IP4_SUBNET(192.0.1.0/255.255.255.192) - INTERNAL_IP4_SUBNET(192.0.2.0/255.255.255.0) - TSi = (0, 0-65535, 192.0.1.234-192.0.1.234) - TSr = (0, 0-65535, 0.0.0.0-255.255.255.255) - - That reply would mean that the client can send all its traffic - through the gateway, but the gateway does not mind if the client - sends traffic not included by INTERNAL_IP4_SUBNET directly to the - destination (without going through the gateway). - - A different situation arises if the gateway has a policy that - requires the traffic for the two subnets to be carried in separate - SAs. Then a response like this would indicate to the client that if - it wants access to the second subnet, it needs to create a separate - SA: - - CP(CFG_REPLY) = - INTERNAL_IP4_ADDRESS(192.0.1.234) - INTERNAL_IP4_SUBNET(192.0.1.0/255.255.255.192) - INTERNAL_IP4_SUBNET(192.0.2.0/255.255.255.0) - TSi = (0, 0-65535, 192.0.1.234-192.0.1.234) - TSr = (0, 0-65535, 192.0.1.0-192.0.1.63) - - INTERNAL_IP4_SUBNET can also be useful if the client's TSr included - only part of the address space. For instance, if the client requests - the following: - - CP(CFG_REQUEST) = - INTERNAL_IP4_ADDRESS() - TSi = (0, 0-65535, 0.0.0.0-255.255.255.255) - TSr = (0, 0-65535, 192.0.2.155-192.0.2.155) - - then the gateway's reply might be: - - - -Kaufman, et al. Expires August 27, 2006 [Page 98] - -Internet-Draft IKEv2bis February 2006 - - - CP(CFG_REPLY) = - INTERNAL_IP4_ADDRESS(192.0.1.234) - INTERNAL_IP4_SUBNET(192.0.1.0/255.255.255.192) - INTERNAL_IP4_SUBNET(192.0.2.0/255.255.255.0) - TSi = (0, 0-65535, 192.0.1.234-192.0.1.234) - TSr = (0, 0-65535, 192.0.2.155-192.0.2.155) - - Because the meaning of INTERNAL_IP4_SUBNET/INTERNAL_IP6_SUBNET is in - CFG_REQUESTs is unclear, they cannot be used reliably in - CFG_REQUESTs. - -3.15.3. Configuration payloads for IPv6 - - {{ Added this section from Clarif-6.5 }} - - The configuration payloads for IPv6 are based on the corresponding - IPv4 payloads, and do not fully follow the "normal IPv6 way of doing - things". In particular, IPv6 stateless autoconfiguration or router - advertisement messages are not used; neither is neighbor discovery. - - A client can be assigned an IPv6 address using the - INTERNAL_IP6_ADDRESS configuration payload. A minimal exchange might - look like this: - - CP(CFG_REQUEST) = - INTERNAL_IP6_ADDRESS() - INTERNAL_IP6_DNS() - TSi = (0, 0-65535, :: - FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF) - TSr = (0, 0-65535, :: - FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF) - - CP(CFG_REPLY) = - INTERNAL_IP6_ADDRESS(2001:DB8:0:1:2:3:4:5/64) - INTERNAL_IP6_DNS(2001:DB8:99:88:77:66:55:44) - TSi = (0, 0-65535, 2001:DB8:0:1:2:3:4:5 - 2001:DB8:0:1:2:3:4:5) - TSr = (0, 0-65535, :: - FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF) - - The client MAY send a non-empty INTERNAL_IP6_ADDRESS attribute in the - CFG_REQUEST to request a specific address or interface identifier. - The gateway first checks if the specified address is acceptable, and - if it is, returns that one. If the address was not acceptable, the - gateway attempts to use the interface identifier with some other - prefix; if even that fails, the gateway selects another interface - identifier. - - The INTERNAL_IP6_ADDRESS attribute also contains a prefix length - field. When used in a CFG_REPLY, this corresponds to the - INTERNAL_IP4_NETMASK attribute in the IPv4 case. - - - - -Kaufman, et al. Expires August 27, 2006 [Page 99] - -Internet-Draft IKEv2bis February 2006 - - - Although this approach to configuring IPv6 addresses is reasonably - simple, it has some limitations. IPsec tunnels configured using - IKEv2 are not fully-featured "interfaces" in the IPv6 addressing - architecture sense [IPV6ADDR]. In particular, they do not - necessarily have link-local addresses, and this may complicate the - use of protocols that assume them, such as [MLDV2]. - -3.15.4. Address Assignment Failures - - {{ Added this section from Clarif-6.8 }} - - If the responder encounters an error while attempting to assign an IP - address to the initiator, it responds with an - INTERNAL_ADDRESS_FAILURE notification. However, there are some more - complex error cases. - - If the responder does not support configuration payloads at all, it - can simply ignore all configuration payloads. This type of - implementation never sends INTERNAL_ADDRESS_FAILURE notifications. - If the initiator requires the assignment of an IP address, it will - treat a response without CFG_REPLY as an error. - - The initiator may request a particular type of address (IPv4 or IPv6) - that the responder does not support, even though the responder - supports configuration payloads. In this case, the responder simply - ignores the type of address it does not support and processes the - rest of the request as usual. - - If the initiator requests multiple addresses of a type that the - responder supports, and some (but not all) of the requests fail, the - responder replies with the successful addresses only. The responder - sends INTERNAL_ADDRESS_FAILURE only if no addresses can be assigned. - -3.16. Extensible Authentication Protocol (EAP) Payload - - The Extensible Authentication Protocol Payload, denoted EAP in this - memo, allows IKE_SAs to be authenticated using the protocol defined - in RFC 3748 [EAP] and subsequent extensions to that protocol. The - full set of acceptable values for the payload is defined elsewhere, - but a short summary of RFC 3748 is included here to make this - document stand alone in the common cases. - - - - - - - - - - -Kaufman, et al. Expires August 27, 2006 [Page 100] - -Internet-Draft IKEv2bis February 2006 - - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload !C! RESERVED ! Payload Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ EAP Message ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 24: EAP Payload Format - - The payload type for an EAP Payload is forty eight (48). - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Code ! Identifier ! Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Type ! Type_Data... - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+- - - Figure 25: EAP Message Format - - o Code (1 octet) indicates whether this message is a Request (1), - Response (2), Success (3), or Failure (4). - - o Identifier (1 octet) is used in PPP to distinguish replayed - messages from repeated ones. Since in IKE, EAP runs over a - reliable protocol, it serves no function here. In a response - message, this octet MUST be set to match the identifier in the - corresponding request. In other messages, this field MAY be set - to any value. - - o Length (2 octets) is the length of the EAP message and MUST be - four less than the Payload Length of the encapsulating payload. - - o Type (1 octet) is present only if the Code field is Request (1) or - Response (2). For other codes, the EAP message length MUST be - four octets and the Type and Type_Data fields MUST NOT be present. - In a Request (1) message, Type indicates the data being requested. - In a Response (2) message, Type MUST either be Nak or match the - type of the data requested. The following types are defined in - RFC 3748: - - - - - - - -Kaufman, et al. Expires August 27, 2006 [Page 101] - -Internet-Draft IKEv2bis February 2006 - - - 1 Identity - 2 Notification - 3 Nak (Response Only) - 4 MD5-Challenge - 5 One-Time Password (OTP) - 6 Generic Token Card - - o Type_Data (Variable Length) varies with the Type of Request and - the associated Response. For the documentation of the EAP - methods, see [EAP]. - - {{ Demoted the SHOULD NOT and SHOULD }} Note that since IKE passes an - indication of initiator identity in message 3 of the protocol, the - responder should not send EAP Identity requests. The initiator may, - however, respond to such requests if it receives them. - - -4. Conformance Requirements - - In order to assure that all implementations of IKEv2 can - interoperate, there are "MUST support" requirements in addition to - those listed elsewhere. Of course, IKEv2 is a security protocol, and - one of its major functions is to allow only authorized parties to - successfully complete establishment of SAs. So a particular - implementation may be configured with any of a number of restrictions - concerning algorithms and trusted authorities that will prevent - universal interoperability. - - IKEv2 is designed to permit minimal implementations that can - interoperate with all compliant implementations. There are a series - of optional features that can easily be ignored by a particular - implementation if it does not support that feature. Those features - include: - - o Ability to negotiate SAs through a NAT and tunnel the resulting - ESP SA over UDP. - - o Ability to request (and respond to a request for) a temporary IP - address on the remote end of a tunnel. - - o Ability to support various types of legacy authentication. - - o Ability to support window sizes greater than one. - - o Ability to establish multiple ESP and/or AH SAs within a single - IKE_SA. - - - - - -Kaufman, et al. Expires August 27, 2006 [Page 102] - -Internet-Draft IKEv2bis February 2006 - - - o Ability to rekey SAs. - - To assure interoperability, all implementations MUST be capable of - parsing all payload types (if only to skip over them) and to ignore - payload types that it does not support unless the critical bit is set - in the payload header. If the critical bit is set in an unsupported - payload header, all implementations MUST reject the messages - containing those payloads. - - Every implementation MUST be capable of doing four-message - IKE_SA_INIT and IKE_AUTH exchanges establishing two SAs (one for IKE, - one for ESP and/or AH). Implementations MAY be initiate-only or - respond-only if appropriate for their platform. Every implementation - MUST be capable of responding to an INFORMATIONAL exchange, but a - minimal implementation MAY respond to any INFORMATIONAL message with - an empty INFORMATIONAL reply (note that within the context of an - IKE_SA, an "empty" message consists of an IKE header followed by an - Encrypted payload with no payloads contained in it). A minimal - implementation MAY support the CREATE_CHILD_SA exchange only in so - far as to recognize requests and reject them with a Notify payload of - type NO_ADDITIONAL_SAS. A minimal implementation need not be able to - initiate CREATE_CHILD_SA or INFORMATIONAL exchanges. When an SA - expires (based on locally configured values of either lifetime or - octets passed), and implementation MAY either try to renew it with a - CREATE_CHILD_SA exchange or it MAY delete (close) the old SA and - create a new one. If the responder rejects the CREATE_CHILD_SA - request with a NO_ADDITIONAL_SAS notification, the implementation - MUST be capable of instead deleting the old SA and creating a new - one. - - Implementations are not required to support requesting temporary IP - addresses or responding to such requests. If an implementation does - support issuing such requests, it MUST include a CP payload in - message 3 containing at least a field of type INTERNAL_IP4_ADDRESS or - INTERNAL_IP6_ADDRESS. All other fields are optional. If an - implementation supports responding to such requests, it MUST parse - the CP payload of type CFG_REQUEST in message 3 and recognize a field - of type INTERNAL_IP4_ADDRESS or INTERNAL_IP6_ADDRESS. If it supports - leasing an address of the appropriate type, it MUST return a CP - payload of type CFG_REPLY containing an address of the requested - type. {{ Demoted the SHOULD }} The responder may include any other - related attributes. - - A minimal IPv4 responder implementation will ignore the contents of - the CP payload except to determine that it includes an - INTERNAL_IP4_ADDRESS attribute and will respond with the address and - other related attributes regardless of whether the initiator - requested them. - - - -Kaufman, et al. Expires August 27, 2006 [Page 103] - -Internet-Draft IKEv2bis February 2006 - - - A minimal IPv4 initiator will generate a CP payload containing only - an INTERNAL_IP4_ADDRESS attribute and will parse the response - ignoring attributes it does not know how to use. {{ Clarif-6.7 - removes the sentence about processing INTERNAL_ADDRESS_EXPIRY. }} - Minimal initiators need not be able to request lease renewals and - minimal responders need not respond to them. - - For an implementation to be called conforming to this specification, - it MUST be possible to configure it to accept the following: - - o PKIX Certificates containing and signed by RSA keys of size 1024 - or 2048 bits, where the ID passed is any of ID_KEY_ID, ID_FQDN, - ID_RFC822_ADDR, or ID_DER_ASN1_DN. - - o Shared key authentication where the ID passes is any of ID_KEY_ID, - ID_FQDN, or ID_RFC822_ADDR. - - o Authentication where the responder is authenticated using PKIX - Certificates and the initiator is authenticated using shared key - authentication. - - -5. Security Considerations - - While this protocol is designed to minimize disclosure of - configuration information to unauthenticated peers, some such - disclosure is unavoidable. One peer or the other must identify - itself first and prove its identity first. To avoid probing, the - initiator of an exchange is required to identify itself first, and - usually is required to authenticate itself first. The initiator can, - however, learn that the responder supports IKE and what cryptographic - protocols it supports. The responder (or someone impersonating the - responder) can probe the initiator not only for its identity, but - using CERTREQ payloads may be able to determine what certificates the - initiator is willing to use. - - Use of EAP authentication changes the probing possibilities somewhat. - When EAP authentication is used, the responder proves its identity - before the initiator does, so an initiator that knew the name of a - valid initiator could probe the responder for both its name and - certificates. - - Repeated rekeying using CREATE_CHILD_SA without additional Diffie- - Hellman exchanges leaves all SAs vulnerable to cryptanalysis of a - single key or overrun of either endpoint. Implementers should take - note of this fact and set a limit on CREATE_CHILD_SA exchanges - between exponentiations. This memo does not prescribe such a limit. - - - - -Kaufman, et al. Expires August 27, 2006 [Page 104] - -Internet-Draft IKEv2bis February 2006 - - - The strength of a key derived from a Diffie-Hellman exchange using - any of the groups defined here depends on the inherent strength of - the group, the size of the exponent used, and the entropy provided by - the random number generator used. Due to these inputs, it is - difficult to determine the strength of a key for any of the defined - groups. Diffie-Hellman group number two, when used with a strong - random number generator and an exponent no less than 200 bits, is - common for use with 3DES. Group five provides greater security than - group two. Group one is for historic purposes only and does not - provide sufficient strength except for use with DES, which is also - for historic use only. Implementations should make note of these - estimates when establishing policy and negotiating security - parameters. - - Note that these limitations are on the Diffie-Hellman groups - themselves. There is nothing in IKE that prohibits using stronger - groups nor is there anything that will dilute the strength obtained - from stronger groups (limited by the strength of the other algorithms - negotiated including the prf function). In fact, the extensible - framework of IKE encourages the definition of more groups; use of - elliptical curve groups may greatly increase strength using much - smaller numbers. - - It is assumed that all Diffie-Hellman exponents are erased from - memory after use. In particular, these exponents MUST NOT be derived - from long-lived secrets like the seed to a pseudo-random generator - that is not erased after use. - - The strength of all keys is limited by the size of the output of the - negotiated prf function. For this reason, a prf function whose - output is less than 128 bits (e.g., 3DES-CBC) MUST NOT be used with - this protocol. - - The security of this protocol is critically dependent on the - randomness of the randomly chosen parameters. These should be - generated by a strong random or properly seeded pseudo-random source - (see [RANDOMNESS]). Implementers should take care to ensure that use - of random numbers for both keys and nonces is engineered in a fashion - that does not undermine the security of the keys. - - For information on the rationale of many of the cryptographic design - choices in this protocol, see [SIGMA] and [SKEME]. Though the - security of negotiated CHILD_SAs does not depend on the strength of - the encryption and integrity protection negotiated in the IKE_SA, - implementations MUST NOT negotiate NONE as the IKE integrity - protection algorithm or ENCR_NULL as the IKE encryption algorithm. - - When using pre-shared keys, a critical consideration is how to assure - - - -Kaufman, et al. Expires August 27, 2006 [Page 105] - -Internet-Draft IKEv2bis February 2006 - - - the randomness of these secrets. The strongest practice is to ensure - that any pre-shared key contain as much randomness as the strongest - key being negotiated. Deriving a shared secret from a password, - name, or other low-entropy source is not secure. These sources are - subject to dictionary and social engineering attacks, among others. - - The NAT_DETECTION_*_IP notifications contain a hash of the addresses - and ports in an attempt to hide internal IP addresses behind a NAT. - Since the IPv4 address space is only 32 bits, and it is usually very - sparse, it would be possible for an attacker to find out the internal - address used behind the NAT box by trying all possible IP addresses - and trying to find the matching hash. The port numbers are normally - fixed to 500, and the SPIs can be extracted from the packet. This - reduces the number of hash calculations to 2^32. With an educated - guess of the use of private address space, the number of hash - calculations is much smaller. Designers should therefore not assume - that use of IKE will not leak internal address information. - - When using an EAP authentication method that does not generate a - shared key for protecting a subsequent AUTH payload, certain man-in- - the-middle and server impersonation attacks are possible [EAPMITM]. - These vulnerabilities occur when EAP is also used in protocols that - are not protected with a secure tunnel. Since EAP is a general- - purpose authentication protocol, which is often used to provide - single-signon facilities, a deployed IPsec solution that relies on an - EAP authentication method that does not generate a shared key (also - known as a non-key-generating EAP method) can become compromised due - to the deployment of an entirely unrelated application that also - happens to use the same non-key-generating EAP method, but in an - unprotected fashion. Note that this vulnerability is not limited to - just EAP, but can occur in other scenarios where an authentication - infrastructure is reused. For example, if the EAP mechanism used by - IKEv2 utilizes a token authenticator, a man-in-the-middle attacker - could impersonate the web server, intercept the token authentication - exchange, and use it to initiate an IKEv2 connection. For this - reason, use of non-key-generating EAP methods SHOULD be avoided where - possible. Where they are used, it is extremely important that all - usages of these EAP methods SHOULD utilize a protected tunnel, where - the initiator validates the responder's certificate before initiating - the EAP exchange. {{ Demoted the SHOULD }} Implementers should - describe the vulnerabilities of using non-key-generating EAP methods - in the documentation of their implementations so that the - administrators deploying IPsec solutions are aware of these dangers. - - An implementation using EAP MUST also use a public-key-based - authentication of the server to the client before the EAP exchange - begins, even if the EAP method offers mutual authentication. This - avoids having additional IKEv2 protocol variations and protects the - - - -Kaufman, et al. Expires August 27, 2006 [Page 106] - -Internet-Draft IKEv2bis February 2006 - - - EAP data from active attackers. - - If the messages of IKEv2 are long enough that IP-level fragmentation - is necessary, it is possible that attackers could prevent the - exchange from completing by exhausting the reassembly buffers. The - chances of this can be minimized by using the Hash and URL encodings - instead of sending certificates (see Section 3.6). Additional - mitigations are discussed in [DOSUDPPROT]. - -5.1. Traffic selector authorization - - {{ Added this section from Clarif-4.13 }} - - IKEv2 relies on information in the Peer Authorization Database (PAD) - when determining what kind of IPsec SAs a peer is allowed to create. - This process is described in [IPSECARCH] Section 4.4.3. When a peer - requests the creation of an IPsec SA with some traffic selectors, the - PAD must contain "Child SA Authorization Data" linking the identity - authenticated by IKEv2 and the addresses permitted for traffic - selectors. - - For example, the PAD might be configured so that authenticated - identity "sgw23.example.com" is allowed to create IPsec SAs for - 192.0.2.0/24, meaning this security gateway is a valid - "representative" for these addresses. Host-to-host IPsec requires - similar entries, linking, for example, "fooserver4.example.com" with - 192.0.1.66/32, meaning this identity a valid "owner" or - "representative" of the address in question. - - As noted in [IPSECARCH], "It is necessary to impose these constraints - on creation of child SAs to prevent an authenticated peer from - spoofing IDs associated with other, legitimate peers." In the - example given above, a correct configuration of the PAD prevents - sgw23 from creating IPsec SAs with address 192.0.1.66, and prevents - fooserver4 from creating IPsec SAs with addresses from 192.0.2.0/24. - - It is important to note that simply sending IKEv2 packets using some - particular address does not imply a permission to create IPsec SAs - with that address in the traffic selectors. For example, even if - sgw23 would be able to spoof its IP address as 192.0.1.66, it could - not create IPsec SAs matching fooserver4's traffic. - - The IKEv2 specification does not specify how exactly IP address - assignment using configuration payloads interacts with the PAD. Our - interpretation is that when a security gateway assigns an address - using configuration payloads, it also creates a temporary PAD entry - linking the authenticated peer identity and the newly allocated inner - address. - - - -Kaufman, et al. Expires August 27, 2006 [Page 107] - -Internet-Draft IKEv2bis February 2006 - - - It has been recognized that configuring the PAD correctly may be - difficult in some environments. For instance, if IPsec is used - between a pair of hosts whose addresses are allocated dynamically - using DHCP, it is extremely difficult to ensure that the PAD - specifies the correct "owner" for each IP address. This would - require a mechanism to securely convey address assignments from the - DHCP server, and link them to identities authenticated using IKEv2. - - Due to this limitation, some vendors have been known to configure - their PADs to allow an authenticated peer to create IPsec SAs with - traffic selectors containing the same address that was used for the - IKEv2 packets. In environments where IP spoofing is possible (i.e., - almost everywhere) this essentially allows any peer to create IPsec - SAs with any traffic selectors. This is not an appropriate or secure - configuration in most circumstances. See [H2HIPSEC] for an extensive - discussion about this issue, and the limitations of host-to-host - IPsec in general. - - -6. IANA Considerations - - {{ This section was changed to not re-define any new IANA registries. - }} - - [IKEV2] defined many field types and values. IANA has already - registered those types and values, so the are not listed here again. - No new types or values are registered in this document. - - -7. Acknowledgements - - The acknowledgements from the IKEv2 document were: - - This document is a collaborative effort of the entire IPsec WG. If - there were no limit to the number of authors that could appear on an - RFC, the following, in alphabetical order, would have been listed: - Bill Aiello, Stephane Beaulieu, Steve Bellovin, Sara Bitan, Matt - Blaze, Ran Canetti, Darren Dukes, Dan Harkins, Paul Hoffman, John - Ioannidis, Charlie Kaufman, Steve Kent, Angelos Keromytis, Tero - Kivinen, Hugo Krawczyk, Andrew Krywaniuk, Radia Perlman, Omer - Reingold, and Michael Richardson. Many other people contributed to - the design. It is an evolution of IKEv1, ISAKMP, and the IPsec DOI, - each of which has its own list of authors. Hugh Daniel suggested the - feature of having the initiator, in message 3, specify a name for the - responder, and gave the feature the cute name "You Tarzan, Me Jane". - David Faucher and Valery Smyzlov helped refine the design of the - traffic selector negotiation. - - - - -Kaufman, et al. Expires August 27, 2006 [Page 108] - -Internet-Draft IKEv2bis February 2006 - - - This paragraph lists references that appear only in figures. The - section is only here to keep the 'xml2rfc' program happy, and will be - removed when the document is published. Feel free to ignore it. - [DES] [IDEA] [MD5] [X.501] [X.509] - - -8. References - -8.1. Normative References - - [ADDGROUP] - Kivinen, T. and M. Kojo, "More Modular Exponential (MODP) - Diffie-Hellman groups for Internet Key Exchange (IKE)", - RFC 3526, May 2003. - - [ADDRIPV6] - Hinden, R. and S. Deering, "Internet Protocol Version 6 - (IPv6) Addressing Architecture", RFC 3513, April 2003. - - [Clarif] "IKEv2 Clarifications and Implementation Guidelines", - draft-eronen-ipsec-ikev2-clarifications (work in - progress). - - [EAP] Aboba, B., Blunk, L., Vollbrecht, J., Carlson, J., and H. - Levkowetz, "Extensible Authentication Protocol (EAP)", - RFC 3748, June 2004. - - [ECN] Ramakrishnan, K., Floyd, S., and D. Black, "The Addition - of Explicit Congestion Notification (ECN) to IP", - RFC 3168, September 2001. - - [ESPCBC] Pereira, R. and R. Adams, "The ESP CBC-Mode Cipher - Algorithms", RFC 2451, November 1998. - - [IANACONS] - Narten, T. and H. Alvestrand, "Guidelines for Writing an - IANA Considerations Section in RFCs", BCP 26, RFC 2434. - - [IKEV2] Kaufman, C., "Internet Key Exchange (IKEv2) Protocol", - RFC 4306, December 2005. - - [IPSECARCH] - Kent, S. and K. Seo, "Security Architecture for the - Internet Protocol", RFC 4301, December 2005. - - [MUSTSHOULD] - Bradner, S., "Key Words for use in RFCs to indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. - - - -Kaufman, et al. Expires August 27, 2006 [Page 109] - -Internet-Draft IKEv2bis February 2006 - - - [PKIX] Housley, R., Polk, W., Ford, W., and D. Solo, "Internet - X.509 Public Key Infrastructure Certificate and - Certificate Revocation List (CRL) Profile", RFC 3280, - April 2002. - - [UDPENCAPS] - Huttunen, A., Swander, B., Volpe, V., DiBurro, L., and M. - Stenberg, "UDP Encapsulation of IPsec ESP Packets", - RFC 3948, January 2005. - -8.2. Informative References - - [AH] Kent, S., "IP Authentication Header", RFC 4302, - December 2005. - - [ARCHGUIDEPHIL] - Bush, R. and D. Meyer, "Some Internet Architectural - Guidelines and Philosophy", RFC 3439, December 2002. - - [ARCHPRINC] - Carpenter, B., "Architectural Principles of the Internet", - RFC 1958, June 1996. - - [DES] American National Standards Institute, "American National - Standard for Information Systems-Data Link Encryption", - ANSI X3.106, 1983. - - [DH] Diffie, W. and M. Hellman, "New Directions in - Cryptography", IEEE Transactions on Information Theory, - V.IT-22 n. 6, June 1977. - - [DHCP] Droms, R., "Dynamic Host Configuration Protocol", - RFC 2131, March 1997. - - [DIFFSERVARCH] - Blake, S., Black, D., Carlson, M., Davies, E., Wang, Z., - and W. Weiss, "An Architecture for Differentiated - Services", RFC 2475. - - [DIFFSERVFIELD] - Nichols, K., Blake, S., Baker, F., and D. Black, - "Definition of the Differentiated Services Field (DS - Field) in the IPv4 and IPv6 Headers", RFC 2474, - December 1998. - - [DIFFTUNNEL] - Black, D., "Differentiated Services and Tunnels", - RFC 2983, October 2000. - - - -Kaufman, et al. Expires August 27, 2006 [Page 110] - -Internet-Draft IKEv2bis February 2006 - - - [DOI] Piper, D., "The Internet IP Security Domain of - Interpretation for ISAKMP", RFC 2407, November 1998. - - [DOSUDPPROT] - C. Kaufman, R. Perlman, and B. Sommerfeld, "DoS protection - for UDP-based protocols", ACM Conference on Computer and - Communications Security , October 2003. - - [DSS] National Institute of Standards and Technology, U.S. - Department of Commerce, "Digital Signature Standard", - FIPS 186, May 1994. - - [EAPMITM] N. Asokan, V. Nierni, and K. Nyberg, "Man-in-the-Middle in - Tunneled Authentication Protocols", November 2002, - <http://eprint.iacr.org/2002/163>. - - [ESP] Kent, S., "IP Encapsulating Security Payload (ESP)", - RFC 4303, December 2005. - - [EXCHANGEANALYSIS] - R. Perlman and C. Kaufman, "Analysis of the IPsec key - exchange Standard", WET-ICE Security Conference, MIT , - 2001, - <http://sec.femto.org/wetice-2001/papers/radia-paper.pdf>. - - [H2HIPSEC] - Aura, T., Roe, M., and A. Mohammed, "Experiences with - Host-to-Host IPsec", 13th International Workshop on - Security Protocols, Cambridge, UK, April 2005. - - [HMAC] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- - Hashing for Message Authentication", RFC 2104, - February 1997. - - [IDEA] X. Lai, "On the Design and Security of Block Ciphers", ETH - Series in Information Processing, v. 1, Konstanz: Hartung- - Gorre Verlag, 1992. - - [IKEV1] Harkins, D. and D. Carrel, "The Internet Key Exchange - (IKE)", RFC 2409, November 1998. - - [IPCOMP] Shacham, A., Monsour, B., Pereira, R., and M. Thomas, "IP - Payload Compression Protocol (IPComp)", RFC 3173, - September 2001. - - [IPSECARCH-OLD] - Kent, S. and R. Atkinson, "Security Architecture for the - Internet Protocol", RFC 2401, November 1998. - - - -Kaufman, et al. Expires August 27, 2006 [Page 111] - -Internet-Draft IKEv2bis February 2006 - - - [IPV6ADDR] - Hinden, R. and S. Deering, "Internet Protocol Version 6 - (IPv6) Addressing Architecture", RFC 3513, April 2003. - - [ISAKMP] Maughan, D., Schneider, M., and M. Schertler, "Internet - Security Association and Key Management Protocol - (ISAKMP)", RFC 2408, November 1998. - - [LDAP] Wahl, M., Howes, T., and S. Kille, "Lightweight Directory - Access Protocol (v3)", RFC 2251, December 1997. - - [MAILFORMAT] - Resnick, P., "Internet Message Format", RFC 2822, - April 2001. - - [MD5] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, - April 1992. - - [MIPV6] Johnson, D., Perkins, C., and J. Arkko, "Mobility Support - in IPv6", RFC 3775, June 2004. - - [MLDV2] Vida, R. and L. Costa, "Multicast Listener Discovery - Version 2 (MLDv2) for IPv6", RFC 3810, June 2004. - - [NAI] Aboba, B. and M. Beadles, "The Network Access Identifier", - RFC 2486, January 1999. - - [NATREQ] Aboba, B. and W. Dixon, "IPsec-Network Address Translation - (NAT) Compatibility Requirements", RFC 3715, March 2004. - - [OAKLEY] Orman, H., "The OAKLEY Key Determination Protocol", - RFC 2412, November 1998. - - [PFKEY] McDonald, D., Metz, C., and B. Phan, "PF_KEY Key - Management API, Version 2", RFC 2367, July 1998. - - [PHOTURIS] - Karn, P. and W. Simpson, "Photuris: Session-Key Management - Protocol", RFC 2522, March 1999. - - [PKCS1] B. Kaliski and J. Staddon, "PKCS #1: RSA Cryptography - Specifications Version 2", September 1998. - - [PRFAES128CBC] - Hoffman, P., "The AES-XCBC-PRF-128 Algorithm for the - Internet Key Exchange Protocol (IKE)", RFC 3664, - January 2004. - - - - -Kaufman, et al. Expires August 27, 2006 [Page 112] - -Internet-Draft IKEv2bis February 2006 - - - [PRFAES128CBC-bis] - Hoffman, P., "The AES-XCBC-PRF-128 Algorithm for the - Internet Key Exchange Protocol (IKE)", - draft-hoffman-rfc3664bis (work in progress), October 2005. - - [RADIUS] Rigney, C., Rubens, A., Simpson, W., and S. Willens, - "Remote Authentication Dial In User Service (RADIUS)", - RFC 2138, April 1997. - - [RANDOMNESS] - Eastlake, D., Schiller, J., and S. Crocker, "Randomness - Requirements for Security", BCP 106, RFC 4086, June 2005. - - [REAUTH] Nir, Y., ""Repeated Authentication in IKEv2", - draft-nir-ikev2-auth-lt (work in progress), May 2005. - - [RSA] R. Rivest, A. Shamir, and L. Adleman, "A Method for - Obtaining Digital Signatures and Public-Key - Cryptosystems", February 1978. - - [SHA] National Institute of Standards and Technology, U.S. - Department of Commerce, "Secure Hash Standard", - FIPS 180-1, May 1994. - - [SIGMA] H. Krawczyk, "SIGMA: the `SIGn-and-MAc' Approach to - Authenticated Diffie-Hellman and its Use in the IKE - Protocols", Advances in Cryptography - CRYPTO 2003 - Proceedings LNCS 2729, 2003, <http:// - www.informatik.uni-trier.de/~ley/db/conf/crypto/ - crypto2003.html>. - - [SKEME] H. Krawczyk, "SKEME: A Versatile Secure Key Exchange - Mechanism for Internet", IEEE Proceedings of the 1996 - Symposium on Network and Distributed Systems Security , - 1996. - - [TRANSPARENCY] - Carpenter, B., "Internet Transparency", RFC 2775, - February 2000. - - [X.501] ITU-T, "Recommendation X.501: Information Technology - - Open Systems Interconnection - The Directory: Models", - 1993. - - [X.509] ITU-T, "Recommendation X.509 (1997 E): Information - Technology - Open Systems Interconnection - The Directory: - Authentication Framework", 1997. - - - - -Kaufman, et al. Expires August 27, 2006 [Page 113] - -Internet-Draft IKEv2bis February 2006 - - -Appendix A. Summary of changes from IKEv1 - - The goals of this revision to IKE are: - - 1. To define the entire IKE protocol in a single document, - replacing RFCs 2407, 2408, and 2409 and incorporating subsequent - changes to support NAT Traversal, Extensible Authentication, and - Remote Address acquisition; - - 2. To simplify IKE by replacing the eight different initial - exchanges with a single four-message exchange (with changes in - authentication mechanisms affecting only a single AUTH payload - rather than restructuring the entire exchange) see - [EXCHANGEANALYSIS]; - - 3. To remove the Domain of Interpretation (DOI), Situation (SIT), - and Labeled Domain Identifier fields, and the Commit and - Authentication only bits; - - 4. To decrease IKE's latency in the common case by making the - initial exchange be 2 round trips (4 messages), and allowing the - ability to piggyback setup of a CHILD_SA on that exchange; - - 5. To replace the cryptographic syntax for protecting the IKE - messages themselves with one based closely on ESP to simplify - implementation and security analysis; - - 6. To reduce the number of possible error states by making the - protocol reliable (all messages are acknowledged) and sequenced. - This allows shortening CREATE_CHILD_SA exchanges from 3 messages - to 2; - - 7. To increase robustness by allowing the responder to not do - significant processing until it receives a message proving that - the initiator can receive messages at its claimed IP address, - and not commit any state to an exchange until the initiator can - be cryptographically authenticated; - - 8. To fix cryptographic weaknesses such as the problem with - symmetries in hashes used for authentication documented by Tero - Kivinen; - - 9. To specify Traffic Selectors in their own payloads type rather - than overloading ID payloads, and making more flexible the - Traffic Selectors that may be specified; - - 10. To specify required behavior under certain error conditions or - when data that is not understood is received in order to make it - - - -Kaufman, et al. Expires August 27, 2006 [Page 114] - -Internet-Draft IKEv2bis February 2006 - - - easier to make future revisions in a way that does not break - backwards compatibility; - - 11. To simplify and clarify how shared state is maintained in the - presence of network failures and Denial of Service attacks; and - - 12. To maintain existing syntax and magic numbers to the extent - possible to make it likely that implementations of IKEv1 can be - enhanced to support IKEv2 with minimum effort. - - -Appendix B. Diffie-Hellman Groups - - There are two Diffie-Hellman groups defined here for use in IKE. - These groups were generated by Richard Schroeppel at the University - of Arizona. Properties of these primes are described in [OAKLEY]. - - The strength supplied by group one may not be sufficient for the - mandatory-to-implement encryption algorithm and is here for historic - reasons. - - Additional Diffie-Hellman groups have been defined in [ADDGROUP]. - -B.1. Group 1 - 768 Bit MODP - - This group is assigned id 1 (one). - - The prime is: 2^768 - 2 ^704 - 1 + 2^64 * { [2^638 pi] + 149686 } - Its hexadecimal value is: - - FFFFFFFF FFFFFFFF C90FDAA2 2168C234 C4C6628B 80DC1CD1 - 29024E08 8A67CC74 020BBEA6 3B139B22 514A0879 8E3404DD - EF9519B3 CD3A431B 302B0A6D F25F1437 4FE1356D 6D51C245 - E485B576 625E7EC6 F44C42E9 A63A3620 FFFFFFFF FFFFFFFF - - The generator is 2. - -B.2. Group 2 - 1024 Bit MODP - - This group is assigned id 2 (two). - - - - - - - - - - - -Kaufman, et al. Expires August 27, 2006 [Page 115] - -Internet-Draft IKEv2bis February 2006 - - - The prime is 2^1024 - 2^960 - 1 + 2^64 * { [2^894 pi] + 129093 }. - Its hexadecimal value is: - - FFFFFFFF FFFFFFFF C90FDAA2 2168C234 C4C6628B 80DC1CD1 - 29024E08 8A67CC74 020BBEA6 3B139B22 514A0879 8E3404DD - EF9519B3 CD3A431B 302B0A6D F25F1437 4FE1356D 6D51C245 - E485B576 625E7EC6 F44C42E9 A637ED6B 0BFF5CB6 F406B7ED - EE386BFB 5A899FA5 AE9F2411 7C4B1FE6 49286651 ECE65381 - FFFFFFFF FFFFFFFF - - The generator is 2. - - -Appendix C. Exchanges and Payloads - - {{ Clarif-AppA }} - - This appendix contains a short summary of the IKEv2 exchanges, and - what payloads can appear in which message. This appendix is purely - informative; if it disagrees with the body of this document, the - other text is considered correct. - - Vendor-ID (V) payloads may be included in any place in any message. - This sequence here shows what are the most logical places for them. - -C.1. IKE_SA_INIT Exchange - - request --> [N(COOKIE)], - SA, KE, Ni, - [N(NAT_DETECTION_SOURCE_IP)+, - N(NAT_DETECTION_DESTINATION_IP)], - [V+] - - normal response <-- SA, KE, Nr, - (no cookie) [N(NAT_DETECTION_SOURCE_IP), - N(NAT_DETECTION_DESTINATION_IP)], - [[N(HTTP_CERT_LOOKUP_SUPPORTED)], CERTREQ+], - [V+] - - - - - - - - - - - - - -Kaufman, et al. Expires August 27, 2006 [Page 116] - -Internet-Draft IKEv2bis February 2006 - - -C.2. IKE_AUTH Exchange without EAP - - request --> IDi, [CERT+], - [N(INITIAL_CONTACT)], - [[N(HTTP_CERT_LOOKUP_SUPPORTED)], CERTREQ+], - [IDr], - AUTH, - [CP(CFG_REQUEST)], - [N(IPCOMP_SUPPORTED)+], - [N(USE_TRANSPORT_MODE)], - [N(ESP_TFC_PADDING_NOT_SUPPORTED)], - [N(NON_FIRST_FRAGMENTS_ALSO)], - SA, TSi, TSr, - [V+] - - response <-- IDr, [CERT+], - AUTH, - [CP(CFG_REPLY)], - [N(IPCOMP_SUPPORTED)], - [N(USE_TRANSPORT_MODE)], - [N(ESP_TFC_PADDING_NOT_SUPPORTED)], - [N(NON_FIRST_FRAGMENTS_ALSO)], - SA, TSi, TSr, - [N(ADDITIONAL_TS_POSSIBLE)], - [V+] - - - - - - - - - - - - - - - - - - - - - - - - - - -Kaufman, et al. Expires August 27, 2006 [Page 117] - -Internet-Draft IKEv2bis February 2006 - - -C.3. IKE_AUTH Exchange with EAP - - first request --> IDi, - [N(INITIAL_CONTACT)], - [[N(HTTP_CERT_LOOKUP_SUPPORTED)], CERTREQ+], - [IDr], - [CP(CFG_REQUEST)], - [N(IPCOMP_SUPPORTED)+], - [N(USE_TRANSPORT_MODE)], - [N(ESP_TFC_PADDING_NOT_SUPPORTED)], - [N(NON_FIRST_FRAGMENTS_ALSO)], - SA, TSi, TSr, - [V+] - - first response <-- IDr, [CERT+], AUTH, - EAP, - [V+] - - / --> EAP - repeat 1..N times | - \ <-- EAP - - last request --> AUTH - - last response <-- AUTH, - [CP(CFG_REPLY)], - [N(IPCOMP_SUPPORTED)], - [N(USE_TRANSPORT_MODE)], - [N(ESP_TFC_PADDING_NOT_SUPPORTED)], - [N(NON_FIRST_FRAGMENTS_ALSO)], - SA, TSi, TSr, - [N(ADDITIONAL_TS_POSSIBLE)], - [V+] - - - - - - - - - - - - - - - - - - -Kaufman, et al. Expires August 27, 2006 [Page 118] - -Internet-Draft IKEv2bis February 2006 - - -C.4. CREATE_CHILD_SA Exchange for Creating or Rekeying CHILD_SAs - - request --> [N(REKEY_SA)], - [N(IPCOMP_SUPPORTED)+], - [N(USE_TRANSPORT_MODE)], - [N(ESP_TFC_PADDING_NOT_SUPPORTED)], - [N(NON_FIRST_FRAGMENTS_ALSO)], - SA, Ni, [KEi], TSi, TSr - - response <-- [N(IPCOMP_SUPPORTED)], - [N(USE_TRANSPORT_MODE)], - [N(ESP_TFC_PADDING_NOT_SUPPORTED)], - [N(NON_FIRST_FRAGMENTS_ALSO)], - SA, Nr, [KEr], TSi, TSr, - [N(ADDITIONAL_TS_POSSIBLE)] - -C.5. CREATE_CHILD_SA Exchange for Rekeying the IKE_SA - - request --> SA, Ni, [KEi] - - response <-- SA, Nr, [KEr] - -C.6. INFORMATIONAL Exchange - - request --> [N+], - [D+], - [CP(CFG_REQUEST)] - - response <-- [N+], - [D+], - [CP(CFG_REPLY)] - - -Appendix D. Changes Between Internet Draft Versions - - This section will be removed before publication as an RFC. - -D.1. Changes from IKEv2 to draft -00 - - There were a zillion additions from the Clarifications document. - These are noted with "{{ Clarif-nn }}". The numbers used in the text - of this version are based on - draft-eronen-ipsec-ikev2-clarifications-08.txt, which has different - numbers than earlier versions of that draft. - - Cleaned up many of the figures. Made the table headings consistent. - Made some tables easier to read by removing blank spaces. Removed - the "reserved to IANA" and "private use" text wording and moved it - - - -Kaufman, et al. Expires August 27, 2006 [Page 119] - -Internet-Draft IKEv2bis February 2006 - - - into the tables. - - Changed many SHOULD requirements to better match RFC 2119. These are - also marked with comments such as "{{ Demoted the SHOULD }}". - - In Section 2.16, changed the MUST requirement of authenticating the - responder from "public key signature based" to "strong" because that - is what most current IKEv2 implementations do, and it better matches - the actual security requirement. - - -Authors' Addresses - - Charlie Kaufman - Microsoft - 1 Microsoft Way - Redmond, WA 98052 - US - - Phone: 1-425-707-3335 - Email: charliek@microsoft.com - - - Paul Hoffman - VPN Consortium - 127 Segre Place - Santa Cruz, CA 95060 - US - - Phone: 1-831-426-9827 - Email: paul.hoffman@vpnc.org - - - Pasi Eronen - Nokia Research Center - P.O. Box 407 - FIN-00045 Nokia Group - Finland - - Email: pasi.eronen@nokia.com - - -Full Copyright Statement - - Copyright (C) The Internet Society (2006). - - This document is subject to the rights, licenses and restrictions - contained in BCP 78, and except as set forth therein, the authors - - - -Kaufman, et al. Expires August 27, 2006 [Page 120] - -Internet-Draft IKEv2bis February 2006 - - - retain all their rights. - - This document and the information contained herein are provided on an - "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS - OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET - ENGINEERING TASK FORCE DISCLAIM 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. - - -Intellectual Property - - The IETF takes no position regarding the validity or scope of any - Intellectual Property Rights or other rights that might be claimed to - pertain to the implementation or use of the technology described in - this document or the extent to which any license under such rights - might or might not be available; nor does it represent that it has - made any independent effort to identify any such rights. Information - on the procedures with respect to rights in RFC documents can be - found in BCP 78 and BCP 79. - - Copies of IPR disclosures made to the IETF Secretariat and any - assurances of licenses to be made available, or the result of an - attempt made to obtain a general license or permission for the use of - such proprietary rights by implementers or users of this - specification can be obtained from the IETF on-line IPR repository at - http://www.ietf.org/ipr. - - The IETF invites any interested party to bring to its attention any - copyrights, patents or patent applications, or other proprietary - rights that may cover technology that may be required to implement - this standard. Please address the information to the IETF at - ietf-ipr@ietf.org. - - -Acknowledgment - - Funding for the RFC Editor function is currently provided by the - Internet Society. - - - - - - - - - - - -Kaufman, et al. Expires August 27, 2006 [Page 121] - diff --git a/src/charon/doc/standards/draft-myers-ikev2-ocsp-03.txt b/src/charon/doc/standards/draft-myers-ikev2-ocsp-03.txt deleted file mode 100644 index fb59fc958..000000000 --- a/src/charon/doc/standards/draft-myers-ikev2-ocsp-03.txt +++ /dev/null @@ -1,785 +0,0 @@ - - - -Network Working Group M. Myers -Internet-Draft TraceRoute Security LLC -Expires: January 12, 2007 H. Tschofenig - Siemens - July 11, 2006 - - - OCSP Extensions to IKEv2 - draft-myers-ikev2-ocsp-03.txt - -Status of this Memo - - By submitting this Internet-Draft, each author represents that any - applicable patent or other IPR claims of which he or she is aware - have been or will be disclosed, and any of which he or she becomes - aware will be disclosed, in accordance with Section 6 of BCP 79. - - 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 January 12, 2007. - -Copyright Notice - - Copyright (C) The Internet Society (2006). - -Abstract - - While IKEv2 supports public key based authentication (PKI), the - corresponding use of in-band CRLs is problematic due to unbounded CRL - size. The size of an OCSP response is however well-bounded and - small. This document defines the "OCSP Content" extension to IKEv2. - A CERTREQ payload with "OCSP Content" identifies one or more trusted - OCSP responders and is a request for inclusion of an OCSP response in - the IKEv2 handshake. A cooperative recipient of such a request - - - -Myers & Tschofenig Expires January 12, 2007 [Page 1] - -Internet-Draft OCSP Extensions to IKEv2 July 2006 - - - responds with a CERT payload containing the appropriate OCSP - response. This content is recognizable via the same "OCSP Content" - identifier. - - When certificates are used with IKEv2, the communicating peers need a - mechanism to determine the revocation status of the peer's - certificate. OCSP is one such mechanism. This document applies when - OCSP is desired and security policy prevents one of the IKEv2 peers - from accessing the relevant OCSP responder directly. Firewalls are - often deployed in a manner that prevents such access by IKEv2 peers - outside of an enterprise network. - - -Table of Contents - - 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 - 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 - 3. Extension Definition . . . . . . . . . . . . . . . . . . . . . 5 - 3.1. OCSP Request . . . . . . . . . . . . . . . . . . . . . . . 5 - 3.2. OCSP Response . . . . . . . . . . . . . . . . . . . . . . 5 - 4. Extension Requirements . . . . . . . . . . . . . . . . . . . . 6 - 4.1. OCSP Request . . . . . . . . . . . . . . . . . . . . . . . 6 - 4.2. OCSP Response . . . . . . . . . . . . . . . . . . . . . . 6 - 5. Examples and Discussion . . . . . . . . . . . . . . . . . . . 8 - 5.1. Peer to Peer . . . . . . . . . . . . . . . . . . . . . . . 8 - 5.2. Extended Authentication Protocol (EAP) . . . . . . . . . . 9 - 6. Security Considerations . . . . . . . . . . . . . . . . . . . 10 - 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 - 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 12 - 9. Normative References . . . . . . . . . . . . . . . . . . . . . 12 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 13 - Intellectual Property and Copyright Statements . . . . . . . . . . 14 - - - - - - - - - - - - - - - - - - - -Myers & Tschofenig Expires January 12, 2007 [Page 2] - -Internet-Draft OCSP Extensions to IKEv2 July 2006 - - -1. Introduction - - Version 2 of the Internet Key Exchange (IKE) protocol [IKEv2] - supports a range of authentication mechanisms, including the use of - public key based authentication. Confirmation of certificate - reliability is essential to achieve the security assurances public - key cryptography provides. One fundamental element of such - confirmation is reference to certificate revocation status (see - [RFC3280] for additional detail). - - The historic means of determining certificate revocation status is - through the use of Certificate Revocation Lists (CRLs). IKEv2 allows - CRLs to be exchanged in-band via the CERT payload. - - CRLs can however grow unbounded in size. Many real-world examples - exist to demonstrate the impracticality of including a multi-megabyte - file in an IKE exchange. This constraint is particularly acute in - bandwidth limited environments (e.g., mobile communications). The - net effect is exclusion of in-band CRLs in favor of out-of-band (OOB) - acquisition of these data, should they even be used at all. - - Reliance on OOB methods can be further complicated if access to - revocation data requires use of IPsec (and therefore IKE) to - establish secure and authorized access to the CRLs of an IKE - participant. Such network access deadlock further contributes to a - reduced reliance on certificate revocation status in favor of blind - trust. - - OCSP [RFC2560] offers a useful alternative. The size of an OCSP - response is bounded and small and therefore suitable for in-band - IKEv2 signaling of a certificate's revocation status. - - This document defines an extension to IKEv2 that enables the use of - OCSP for in-band signaling of certificate revocation status. A new - content encoding is defined for use in the CERTREQ and CERT payloads. - A CERTREQ payload with "OCSP Content" identifies one or more trusted - OCSP responders and is a request for inclusion of an OCSP response in - the IKEv2 handshake. A cooperative recipient of such a request - responds with a CERT payload containing the appropriate OCSP - response. This content is recognizable via the same "OCSP Content" - identifier. - - - - - - - - - - -Myers & Tschofenig Expires January 12, 2007 [Page 3] - -Internet-Draft OCSP Extensions to IKEv2 July 2006 - - -2. Terminology - - 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 RFC 2119 [RFC2119]. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Myers & Tschofenig Expires January 12, 2007 [Page 4] - -Internet-Draft OCSP Extensions to IKEv2 July 2006 - - -3. Extension Definition - - With reference to Section 3.6 of [IKEv2], the values for the Cert - Encoding field of the CERT payload are extended as follows (see also - the IANA Considerations section of this document): - - Certificate Encoding Value - -------------------- ----- - OCSP Content 14 - -3.1. OCSP Request - - A value of OCSP Content (14) in the Cert Encoding field of a CERTREQ - Payload indicates the presence of one or more OCSP Responder - certificate hashes in the Certificate Authority field of the CERTREQ - payload. - - The presence of OCSP Content (14) in a CERTREQ message: - - 1. identifies one or more OCSP responders trusted by the sender; - - 2. notifies the recipient of sender's support for the OCSP extension - to IKEv2; and - - 3. notifies the recipient of sender's desire to receive OCSP - confirmation in a subsequent CERT payload. - -3.2. OCSP Response - - A value of OCSP Content (14) in the Cert Encoding field of a CERT - Payload indicates the presence of an OCSP Response in the Certificate - Data field of the CERT payload. - - Correlation between an OCSP Response CERT payload and a corresponding - CERT payload carrying a certificate can be achieved by matching the - OCSP response CertID field to the certificate. See [RFC2560] for the - definition of OCSP response content. - - - - - - - - - - - - - - -Myers & Tschofenig Expires January 12, 2007 [Page 5] - -Internet-Draft OCSP Extensions to IKEv2 July 2006 - - -4. Extension Requirements - -4.1. OCSP Request - - Section 3.7 of [IKEv2] allows for the concatenation of trust anchor - hashes as the Certification Authority value of a single CERTREQ - message. There is no means however to indicate which among those - hashes relates to the certificate of a trusted OCSP responder. - - Therefore an OCSP Request as defined in Section 3.1 above SHALL be - transmitted separate from any other CERTREQ payloads in an IKEv2 - exchange. - - Where it is useful to identify more than one trusted OCSP responder, - each such identification SHALL be concatenated in a manner identical - to the method documented in Section 3.7 of [IKEv2] regarding the - assembly of multiple trust anchor hashes. - - The Certification Authority value in an OCSP Request CERTREQ SHALL be - computed and produced in a manner identical to that of trust anchor - hashes as documented in Section 3.7 of [IKEv2]. - - Upon receipt of an OCSP Response CERT payload corresponding to a - prior OCSP Request CERTREQ, the CERTREQ sender SHALL incorporate the - OCSP response into path validation logic defined by [RFC3280]. - - The sender of an OCSP Request CERTREQ MAY abort an IKEv2 exchange if - either: - - 1. the corresponding OCSP Response CERT payload indicates that the - subject certificate is revoked; OR - - 2. the corresponding OCSP Response CERT payload indicates an OCSP - error (e.g., malformedRequest, internalError, tryLater, - sigRequired, unauthorized, etc.). - - The sender of an OCSP Request CERTREQ SHOULD accept an IKEv2 exchange - if a corresponding OCSP Response CERT payload is not received. This - might be an indication that this OCSP extension is not supported. - -4.2. OCSP Response - - Upon receipt of an OCSP Request CERTREQ payload, the recipient SHOULD - acquire the related OCSP-based assertion and produce and transmit an - OCSP Response CERT payload corresponding to the certificate needed to - verify its signature on IKEv2 payloads. - - An OCSP Response CERT payload SHALL be transmitted separate from any - - - -Myers & Tschofenig Expires January 12, 2007 [Page 6] - -Internet-Draft OCSP Extensions to IKEv2 July 2006 - - - other CERT payload in an IKEv2 exchange. - - The means by which an OCSP response may be acquired for production of - an OCSP Response CERT payload is out of scope of this document. - - The structure and encoding of the Certificate Data field of an OCSP - Response CERT payload SHALL be identical to that defined in - [RFC2560]. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Myers & Tschofenig Expires January 12, 2007 [Page 7] - -Internet-Draft OCSP Extensions to IKEv2 July 2006 - - -5. Examples and Discussion - - This section shows the standard IKEv2 message examples with both - peers, the initiator and the responder, using public key based - authentication, CERTREQ and CERT payloads. The first instance - corresponds to Section 1.2 of [IKEv2], the illustrations of which are - reproduced below for reference. - -5.1. Peer to Peer - - Application of the IKEv2 extensions defined in this document to the - peer-to-peer exchange defined in Section 1.2 of [IKEv2] is as - follows. Messages are numbered for ease of reference. - - - Initiator Responder - ----------- ----------- - (1) HDR, SAi1, KEi, Ni --> - - (2) <-- HDR, SAr1, KEr, Nr, - CERTREQ(OCSP Request) - (3) HDR, SK {IDi, CERT(certificate),--> - CERT(OCSP Response), - CERTREQ(OCSP Request), - [IDr,] AUTH, SAi2, TSi, TSr} - - (4) <-- HDR, SK {IDr, - CERT(certificate), - CERT(OCSP Response), - AUTH, SAr2, TSi, TSr} - - In (2) Responder sends an OCSP Request CERTREQ payload identifying - one or more OCSP responders trusted by Responder. In response, - Initiator sends in (3) both a CERT payload carrying its certificate - and an OCSP Response CERT payload covering that certificate. In (3) - Initiator also requests an OCSP response via the OCSP Request CERTREQ - payload. In (4) Responder returns its certificate and a separate - OCSP Response CERT payload covering that certificate. - - It is important to note that in this scenario, the Responder in (2) - does not yet possess the Initiator's certificate and therefore cannot - form an OCSP request. [RFC2560] allows for pre-produced responses. - It is thus easily inferred that OCSP responses can be produced in the - absence of a corresponding request (OCSP nonces notwithstanding). In - such instances OCSP Requests are simply index values into these data. - - It is also important in extending IKEv2 towards OCSP in this scenario - that the Initiator has certain knowledge that the Responder is - - - -Myers & Tschofenig Expires January 12, 2007 [Page 8] - -Internet-Draft OCSP Extensions to IKEv2 July 2006 - - - capable of and willing to participate in the extension. Yet the - Responder will only trust one or more OCSP responder signatures. - These factors motivate the definition of OCSP Responder Hash - extension. - -5.2. Extended Authentication Protocol (EAP) - - Another scenario of pressing interest is the use of EAP to - accommodate multiple end users seeking enterprise access to an IPsec - gateway. As with the preceding section, the following illustration - is extracted from [IKEv2]. In the event of a conflict between this - document and[IKEv2] regarding these illustrations, [IKEv2] SHALL - dominate. - - - Initiator Responder - ----------- ----------- - (1) HDR, SAi1, KEi, Ni --> - (2) <-- HDR, SAr1, KEr, Nr - (3) HDR, SK {IDi, --> - CERTREQ(OCSP Request), - [IDr,] AUTH, SAi2, TSi, TSr} - (4) <-- HDR, SK {IDr, - CERT(certificate), - CERT(OCSP Response), - AUTH, EAP} - (5) HDR, SK {EAP} --> - - (6) <-- HDR, SK {EAP (success)} - - (7) HDR, SK {AUTH} --> - - (8) <-- HDR, SK {AUTH, SAr2, TSi, - TSr } - - In the EAP scenario, messages (5) through (8) are not relevant to - this document. Note that while [IKEv2] allows for the optional - inclusion of a CERTREQ in (2), this document asserts no need of its - use. It is assumed that environments including this optional payload - and yet wishing to implement the OCSP extension to IKEv2 are - sufficiently robust as to accommodate this redundant payload. - - - - - - - - - - -Myers & Tschofenig Expires January 12, 2007 [Page 9] - -Internet-Draft OCSP Extensions to IKEv2 July 2006 - - -6. Security Considerations - - For the reasons noted above, OCSP request as defined in Section 3.1 - is used in place of OCSP request syntax to trigger production and - transmission of an OCSP response. OCSP as defined in [RFC2560] may - contain a nonce request extension to improve security against replay - attacks (see Section 4.4.1 of [RFC2560] for further details). The - OCSP Request defined by this document cannot accommodate nonces. - [RFC2560] deals with this aspect by allowing pre-produced responses. - - [RFC2560] points to this replay vulnerability and indicates: "The use - of precomputed responses allows replay attacks in which an old (good) - response is replayed prior to its expiration date but after the - certificate has been revoked. Deployments of OCSP should carefully - evaluate the benefit of precomputed responses against the probability - of a replay attack and the costs associated with its successful - execution." Nodes SHOULD make the required freshness of an OCSP - Response configurable. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Myers & Tschofenig Expires January 12, 2007 [Page 10] - -Internet-Draft OCSP Extensions to IKEv2 July 2006 - - -7. IANA Considerations - - This document defines one new field type for use in the IKEv2 Cert - Encoding field of the Certificate Payload format. Official - assignment of the "OCSP Content" extension to the Cert Encoding table - of Section 3.6 of [IKEv2] needs to be acquired from IANA. - - Certificate Encoding Value - -------------------- ----- - OCSP Content 14 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Myers & Tschofenig Expires January 12, 2007 [Page 11] - -Internet-Draft OCSP Extensions to IKEv2 July 2006 - - -8. Acknowledgements - - The authors would like to thank Russ Housley for his support. - Additionally, we would like to thank Pasi Eronen, Nicolas Williams, - Liqiang (Larry) Zhu, Lakshminath Dondeti and Paul Hoffman for their - review. - -9. Normative References - - [IKEv2] Kaufman, C., "Internet Key Exchange (IKEv2) Protocol", - RFC 4306, December 2005. - - [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. - - [RFC2560] Myers, M., Ankney, R., Malpani, A., Galperin, S., and C. - Adams, "X.509 Internet Public Key Infrastructure Online - Certificate Status Protocol - OCSP", RFC 2560, June 1999. - - [RFC3280] Housley, R., Polk, W., Ford, W., and D. Solo, "Internet - X.509 Public Key Infrastructure Certificate and - Certificate Revocation List (CRL) Profile", RFC 3280, - April 2002. - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Myers & Tschofenig Expires January 12, 2007 [Page 12] - -Internet-Draft OCSP Extensions to IKEv2 July 2006 - - -Authors' Addresses - - Michael Myers - TraceRoute Security LLC - - - Email: mmyers@fastq.com - - - Hannes Tschofenig - Siemens - Otto-Hahn-Ring 6 - Munich, Bavaria 81739 - Germany - - Email: Hannes.Tschofenig@siemens.com - URI: http://www.tschofenig.com - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Myers & Tschofenig Expires January 12, 2007 [Page 13] - -Internet-Draft OCSP Extensions to IKEv2 July 2006 - - -Intellectual Property Statement - - The IETF takes no position regarding the validity or scope of any - Intellectual Property Rights or other rights that might be claimed to - pertain to the implementation or use of the technology described in - this document or the extent to which any license under such rights - might or might not be available; nor does it represent that it has - made any independent effort to identify any such rights. Information - on the procedures with respect to rights in RFC documents can be - found in BCP 78 and BCP 79. - - Copies of IPR disclosures made to the IETF Secretariat and any - assurances of licenses to be made available, or the result of an - attempt made to obtain a general license or permission for the use of - such proprietary rights by implementers or users of this - specification can be obtained from the IETF on-line IPR repository at - http://www.ietf.org/ipr. - - The IETF invites any interested party to bring to its attention any - copyrights, patents or patent applications, or other proprietary - rights that may cover technology that may be required to implement - this standard. Please address the information to the IETF at - ietf-ipr@ietf.org. - - -Disclaimer of Validity - - This document and the information contained herein are provided on an - "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS - OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET - ENGINEERING TASK FORCE DISCLAIM 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. - - -Copyright Statement - - Copyright (C) The Internet Society (2006). This document is subject - to the rights, licenses and restrictions contained in BCP 78, and - except as set forth therein, the authors retain all their rights. - - -Acknowledgment - - Funding for the RFC Editor function is currently provided by the - Internet Society. - - - - -Myers & Tschofenig Expires January 12, 2007 [Page 14] - - diff --git a/src/charon/doc/standards/rfc3748.txt b/src/charon/doc/standards/rfc3748.txt deleted file mode 100644 index 75600c1f2..000000000 --- a/src/charon/doc/standards/rfc3748.txt +++ /dev/null @@ -1,3755 +0,0 @@ - - - - - - -Network Working Group B. Aboba -Request for Comments: 3748 Microsoft -Obsoletes: 2284 L. Blunk -Category: Standards Track Merit Network, Inc - J. Vollbrecht - Vollbrecht Consulting LLC - J. Carlson - Sun - H. Levkowetz, Ed. - ipUnplugged - June 2004 - - - Extensible Authentication Protocol (EAP) - -Status of this Memo - - This document specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" (STD 1) for the standardization state - and status of this protocol. Distribution of this memo is unlimited. - -Copyright Notice - - Copyright (C) The Internet Society (2004). - -Abstract - - This document defines the Extensible Authentication Protocol (EAP), - an authentication framework which supports multiple authentication - methods. EAP typically runs directly over data link layers such as - Point-to-Point Protocol (PPP) or IEEE 802, without requiring IP. EAP - provides its own support for duplicate elimination and - retransmission, but is reliant on lower layer ordering guarantees. - Fragmentation is not supported within EAP itself; however, individual - EAP methods may support this. - - This document obsoletes RFC 2284. A summary of the changes between - this document and RFC 2284 is available in Appendix A. - - - - - - - - - - - -Aboba, et al. Standards Track [Page 1] - -RFC 3748 EAP June 2004 - - -Table of Contents - - 1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . 3 - 1.1. Specification of Requirements . . . . . . . . . . . . . 4 - 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . 4 - 1.3. Applicability . . . . . . . . . . . . . . . . . . . . . 6 - 2. Extensible Authentication Protocol (EAP). . . . . . . . . . . 7 - 2.1. Support for Sequences . . . . . . . . . . . . . . . . . 9 - 2.2. EAP Multiplexing Model. . . . . . . . . . . . . . . . . 10 - 2.3. Pass-Through Behavior . . . . . . . . . . . . . . . . . 12 - 2.4. Peer-to-Peer Operation. . . . . . . . . . . . . . . . . 14 - 3. Lower Layer Behavior. . . . . . . . . . . . . . . . . . . . . 15 - 3.1. Lower Layer Requirements. . . . . . . . . . . . . . . . 15 - 3.2. EAP Usage Within PPP. . . . . . . . . . . . . . . . . . 18 - 3.2.1. PPP Configuration Option Format. . . . . . . . . 18 - 3.3. EAP Usage Within IEEE 802 . . . . . . . . . . . . . . . 19 - 3.4. Lower Layer Indications . . . . . . . . . . . . . . . . 19 - 4. EAP Packet Format . . . . . . . . . . . . . . . . . . . . . . 20 - 4.1. Request and Response. . . . . . . . . . . . . . . . . . 21 - 4.2. Success and Failure . . . . . . . . . . . . . . . . . . 23 - 4.3. Retransmission Behavior . . . . . . . . . . . . . . . . 26 - 5. Initial EAP Request/Response Types. . . . . . . . . . . . . . 27 - 5.1. Identity. . . . . . . . . . . . . . . . . . . . . . . . 28 - 5.2. Notification. . . . . . . . . . . . . . . . . . . . . . 29 - 5.3. Nak . . . . . . . . . . . . . . . . . . . . . . . . . . 31 - 5.3.1. Legacy Nak . . . . . . . . . . . . . . . . . . . 31 - 5.3.2. Expanded Nak . . . . . . . . . . . . . . . . . . 32 - 5.4. MD5-Challenge . . . . . . . . . . . . . . . . . . . . . 35 - 5.5. One-Time Password (OTP) . . . . . . . . . . . . . . . . 36 - 5.6. Generic Token Card (GTC). . . . . . . . . . . . . . . . 37 - 5.7. Expanded Types. . . . . . . . . . . . . . . . . . . . . 38 - 5.8. Experimental. . . . . . . . . . . . . . . . . . . . . . 40 - 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 40 - 6.1. Packet Codes. . . . . . . . . . . . . . . . . . . . . . 41 - 6.2. Method Types. . . . . . . . . . . . . . . . . . . . . . 41 - 7. Security Considerations . . . . . . . . . . . . . . . . . . . 42 - 7.1. Threat Model. . . . . . . . . . . . . . . . . . . . . . 42 - 7.2. Security Claims . . . . . . . . . . . . . . . . . . . . 43 - 7.2.1. Security Claims Terminology for EAP Methods. . . 44 - 7.3. Identity Protection . . . . . . . . . . . . . . . . . . 46 - 7.4. Man-in-the-Middle Attacks . . . . . . . . . . . . . . . 47 - 7.5. Packet Modification Attacks . . . . . . . . . . . . . . 48 - 7.6. Dictionary Attacks. . . . . . . . . . . . . . . . . . . 49 - 7.7. Connection to an Untrusted Network. . . . . . . . . . . 49 - 7.8. Negotiation Attacks . . . . . . . . . . . . . . . . . . 50 - 7.9. Implementation Idiosyncrasies . . . . . . . . . . . . . 50 - 7.10. Key Derivation. . . . . . . . . . . . . . . . . . . . . 51 - 7.11. Weak Ciphersuites . . . . . . . . . . . . . . . . . . . 53 - - - -Aboba, et al. Standards Track [Page 2] - -RFC 3748 EAP June 2004 - - - 7.12. Link Layer. . . . . . . . . . . . . . . . . . . . . . . 53 - 7.13. Separation of Authenticator and Backend Authentication - Server. . . . . . . . . . . . . . . . . . . . . . . . . 54 - 7.14. Cleartext Passwords . . . . . . . . . . . . . . . . . . 55 - 7.15. Channel Binding . . . . . . . . . . . . . . . . . . . . 55 - 7.16. Protected Result Indications. . . . . . . . . . . . . . 56 - 8. Acknowledgements. . . . . . . . . . . . . . . . . . . . . . . 58 - 9. References. . . . . . . . . . . . . . . . . . . . . . . . . . 59 - 9.1. Normative References. . . . . . . . . . . . . . . . . . 59 - 9.2. Informative References. . . . . . . . . . . . . . . . . 60 - Appendix A. Changes from RFC 2284. . . . . . . . . . . . . . . . . 64 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 66 - Full Copyright Statement . . . . . . . . . . . . . . . . . . . . . 67 - -1. Introduction - - This document defines the Extensible Authentication Protocol (EAP), - an authentication framework which supports multiple authentication - methods. EAP typically runs directly over data link layers such as - Point-to-Point Protocol (PPP) or IEEE 802, without requiring IP. EAP - provides its own support for duplicate elimination and - retransmission, but is reliant on lower layer ordering guarantees. - Fragmentation is not supported within EAP itself; however, individual - EAP methods may support this. - - EAP may be used on dedicated links, as well as switched circuits, and - wired as well as wireless links. To date, EAP has been implemented - with hosts and routers that connect via switched circuits or dial-up - lines using PPP [RFC1661]. It has also been implemented with - switches and access points using IEEE 802 [IEEE-802]. EAP - encapsulation on IEEE 802 wired media is described in [IEEE-802.1X], - and encapsulation on IEEE wireless LANs in [IEEE-802.11i]. - - One of the advantages of the EAP architecture is its flexibility. - EAP is used to select a specific authentication mechanism, typically - after the authenticator requests more information in order to - determine the specific authentication method to be used. Rather than - requiring the authenticator to be updated to support each new - authentication method, EAP permits the use of a backend - authentication server, which may implement some or all authentication - methods, with the authenticator acting as a pass-through for some or - all methods and peers. - - Within this document, authenticator requirements apply regardless of - whether the authenticator is operating as a pass-through or not. - Where the requirement is meant to apply to either the authenticator - or backend authentication server, depending on where the EAP - authentication is terminated, the term "EAP server" will be used. - - - -Aboba, et al. Standards Track [Page 3] - -RFC 3748 EAP June 2004 - - -1.1. Specification of Requirements - - In this document, several words are used to signify the requirements - of the specification. 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]. - -1.2. Terminology - - This document frequently uses the following terms: - - authenticator - The end of the link initiating EAP authentication. The term - authenticator is used in [IEEE-802.1X], and has the same meaning - in this document. - - peer - The end of the link that responds to the authenticator. In - [IEEE-802.1X], this end is known as the Supplicant. - - Supplicant - The end of the link that responds to the authenticator in [IEEE- - 802.1X]. In this document, this end of the link is called the - peer. - - backend authentication server - A backend authentication server is an entity that provides an - authentication service to an authenticator. When used, this - server typically executes EAP methods for the authenticator. This - terminology is also used in [IEEE-802.1X]. - - AAA - Authentication, Authorization, and Accounting. AAA protocols with - EAP support include RADIUS [RFC3579] and Diameter [DIAM-EAP]. In - this document, the terms "AAA server" and "backend authentication - server" are used interchangeably. - - Displayable Message - This is interpreted to be a human readable string of characters. - The message encoding MUST follow the UTF-8 transformation format - [RFC2279]. - - - - - - - - - -Aboba, et al. Standards Track [Page 4] - -RFC 3748 EAP June 2004 - - - EAP server - The entity that terminates the EAP authentication method with the - peer. In the case where no backend authentication server is used, - the EAP server is part of the authenticator. In the case where - the authenticator operates in pass-through mode, the EAP server is - located on the backend authentication server. - - Silently Discard - This means the implementation discards the packet without further - processing. The implementation SHOULD provide the capability of - logging the event, including the contents of the silently - discarded packet, and SHOULD record the event in a statistics - counter. - - Successful Authentication - In the context of this document, "successful authentication" is an - exchange of EAP messages, as a result of which the authenticator - decides to allow access by the peer, and the peer decides to use - this access. The authenticator's decision typically involves both - authentication and authorization aspects; the peer may - successfully authenticate to the authenticator, but access may be - denied by the authenticator due to policy reasons. - - Message Integrity Check (MIC) - A keyed hash function used for authentication and integrity - protection of data. This is usually called a Message - Authentication Code (MAC), but IEEE 802 specifications (and this - document) use the acronym MIC to avoid confusion with Medium - Access Control. - - Cryptographic Separation - Two keys (x and y) are "cryptographically separate" if an - adversary that knows all messages exchanged in the protocol cannot - compute x from y or y from x without "breaking" some cryptographic - assumption. In particular, this definition allows that the - adversary has the knowledge of all nonces sent in cleartext, as - well as all predictable counter values used in the protocol. - Breaking a cryptographic assumption would typically require - inverting a one-way function or predicting the outcome of a - cryptographic pseudo-random number generator without knowledge of - the secret state. In other words, if the keys are - cryptographically separate, there is no shortcut to compute x from - y or y from x, but the work an adversary must do to perform this - computation is equivalent to performing an exhaustive search for - the secret state value. - - - - - - -Aboba, et al. Standards Track [Page 5] - -RFC 3748 EAP June 2004 - - - Master Session Key (MSK) - Keying material that is derived between the EAP peer and server - and exported by the EAP method. The MSK is at least 64 octets in - length. In existing implementations, a AAA server acting as an - EAP server transports the MSK to the authenticator. - - Extended Master Session Key (EMSK) - Additional keying material derived between the EAP client and - server that is exported by the EAP method. The EMSK is at least - 64 octets in length. The EMSK is not shared with the - authenticator or any other third party. The EMSK is reserved for - future uses that are not defined yet. - - Result indications - A method provides result indications if after the method's last - message is sent and received: - - 1) The peer is aware of whether it has authenticated the server, - as well as whether the server has authenticated it. - - 2) The server is aware of whether it has authenticated the peer, - as well as whether the peer has authenticated it. - - In the case where successful authentication is sufficient to - authorize access, then the peer and authenticator will also know if - the other party is willing to provide or accept access. This may not - always be the case. An authenticated peer may be denied access due - to lack of authorization (e.g., session limit) or other reasons. - Since the EAP exchange is run between the peer and the server, other - nodes (such as AAA proxies) may also affect the authorization - decision. This is discussed in more detail in Section 7.16. - -1.3. Applicability - - EAP was designed for use in network access authentication, where IP - layer connectivity may not be available. Use of EAP for other - purposes, such as bulk data transport, is NOT RECOMMENDED. - - Since EAP does not require IP connectivity, it provides just enough - support for the reliable transport of authentication protocols, and - no more. - - EAP is a lock-step protocol which only supports a single packet in - flight. As a result, EAP cannot efficiently transport bulk data, - unlike transport protocols such as TCP [RFC793] or SCTP [RFC2960]. - - - - - - -Aboba, et al. Standards Track [Page 6] - -RFC 3748 EAP June 2004 - - - While EAP provides support for retransmission, it assumes ordering - guarantees provided by the lower layer, so out of order reception is - not supported. - - Since EAP does not support fragmentation and reassembly, EAP - authentication methods generating payloads larger than the minimum - EAP MTU need to provide fragmentation support. - - While authentication methods such as EAP-TLS [RFC2716] provide - support for fragmentation and reassembly, the EAP methods defined in - this document do not. As a result, if the EAP packet size exceeds - the EAP MTU of the link, these methods will encounter difficulties. - - EAP authentication is initiated by the server (authenticator), - whereas many authentication protocols are initiated by the client - (peer). As a result, it may be necessary for an authentication - algorithm to add one or two additional messages (at most one - roundtrip) in order to run over EAP. - - Where certificate-based authentication is supported, the number of - additional roundtrips may be much larger due to fragmentation of - certificate chains. In general, a fragmented EAP packet will require - as many round-trips to send as there are fragments. For example, a - certificate chain 14960 octets in size would require ten round-trips - to send with a 1496 octet EAP MTU. - - Where EAP runs over a lower layer in which significant packet loss is - experienced, or where the connection between the authenticator and - authentication server experiences significant packet loss, EAP - methods requiring many round-trips can experience difficulties. In - these situations, use of EAP methods with fewer roundtrips is - advisable. - -2. Extensible Authentication Protocol (EAP) - - The EAP authentication exchange proceeds as follows: - - [1] The authenticator sends a Request to authenticate the peer. The - Request has a Type field to indicate what is being requested. - Examples of Request Types include Identity, MD5-challenge, etc. - The MD5-challenge Type corresponds closely to the CHAP - authentication protocol [RFC1994]. Typically, the authenticator - will send an initial Identity Request; however, an initial - Identity Request is not required, and MAY be bypassed. For - example, the identity may not be required where it is determined - by the port to which the peer has connected (leased lines, - - - - - -Aboba, et al. Standards Track [Page 7] - -RFC 3748 EAP June 2004 - - - dedicated switch or dial-up ports), or where the identity is - obtained in another fashion (via calling station identity or MAC - address, in the Name field of the MD5-Challenge Response, etc.). - - [2] The peer sends a Response packet in reply to a valid Request. As - with the Request packet, the Response packet contains a Type - field, which corresponds to the Type field of the Request. - - [3] The authenticator sends an additional Request packet, and the - peer replies with a Response. The sequence of Requests and - Responses continues as long as needed. EAP is a 'lock step' - protocol, so that other than the initial Request, a new Request - cannot be sent prior to receiving a valid Response. The - authenticator is responsible for retransmitting requests as - described in Section 4.1. After a suitable number of - retransmissions, the authenticator SHOULD end the EAP - conversation. The authenticator MUST NOT send a Success or - Failure packet when retransmitting or when it fails to get a - response from the peer. - - [4] The conversation continues until the authenticator cannot - authenticate the peer (unacceptable Responses to one or more - Requests), in which case the authenticator implementation MUST - transmit an EAP Failure (Code 4). Alternatively, the - authentication conversation can continue until the authenticator - determines that successful authentication has occurred, in which - case the authenticator MUST transmit an EAP Success (Code 3). - - Advantages: - - o The EAP protocol can support multiple authentication mechanisms - without having to pre-negotiate a particular one. - - o Network Access Server (NAS) devices (e.g., a switch or access - point) do not have to understand each authentication method and - MAY act as a pass-through agent for a backend authentication - server. Support for pass-through is optional. An authenticator - MAY authenticate local peers, while at the same time acting as a - pass-through for non-local peers and authentication methods it - does not implement locally. - - o Separation of the authenticator from the backend authentication - server simplifies credentials management and policy decision - making. - - - - - - - -Aboba, et al. Standards Track [Page 8] - -RFC 3748 EAP June 2004 - - - Disadvantages: - - o For use in PPP, EAP requires the addition of a new authentication - Type to PPP LCP and thus PPP implementations will need to be - modified to use it. It also strays from the previous PPP - authentication model of negotiating a specific authentication - mechanism during LCP. Similarly, switch or access point - implementations need to support [IEEE-802.1X] in order to use EAP. - - o Where the authenticator is separate from the backend - authentication server, this complicates the security analysis and, - if needed, key distribution. - -2.1. Support for Sequences - - An EAP conversation MAY utilize a sequence of methods. A common - example of this is an Identity request followed by a single EAP - authentication method such as an MD5-Challenge. However, the peer - and authenticator MUST utilize only one authentication method (Type 4 - or greater) within an EAP conversation, after which the authenticator - MUST send a Success or Failure packet. - - Once a peer has sent a Response of the same Type as the initial - Request, an authenticator MUST NOT send a Request of a different Type - prior to completion of the final round of a given method (with the - exception of a Notification-Request) and MUST NOT send a Request for - an additional method of any Type after completion of the initial - authentication method; a peer receiving such Requests MUST treat them - as invalid, and silently discard them. As a result, Identity Requery - is not supported. - - A peer MUST NOT send a Nak (legacy or expanded) in reply to a Request - after an initial non-Nak Response has been sent. Since spoofed EAP - Request packets may be sent by an attacker, an authenticator - receiving an unexpected Nak SHOULD discard it and log the event. - - Multiple authentication methods within an EAP conversation are not - supported due to their vulnerability to man-in-the-middle attacks - (see Section 7.4) and incompatibility with existing implementations. - - Where a single EAP authentication method is utilized, but other - methods are run within it (a "tunneled" method), the prohibition - against multiple authentication methods does not apply. Such - "tunneled" methods appear as a single authentication method to EAP. - Backward compatibility can be provided, since a peer not supporting a - "tunneled" method can reply to the initial EAP-Request with a Nak - - - - - -Aboba, et al. Standards Track [Page 9] - -RFC 3748 EAP June 2004 - - - (legacy or expanded). To address security vulnerabilities, - "tunneled" methods MUST support protection against man-in-the-middle - attacks. - -2.2. EAP Multiplexing Model - - Conceptually, EAP implementations consist of the following - components: - - [a] Lower layer. The lower layer is responsible for transmitting and - receiving EAP frames between the peer and authenticator. EAP has - been run over a variety of lower layers including PPP, wired IEEE - 802 LANs [IEEE-802.1X], IEEE 802.11 wireless LANs [IEEE-802.11], - UDP (L2TP [RFC2661] and IKEv2 [IKEv2]), and TCP [PIC]. Lower - layer behavior is discussed in Section 3. - - [b] EAP layer. The EAP layer receives and transmits EAP packets via - the lower layer, implements duplicate detection and - retransmission, and delivers and receives EAP messages to and - from the EAP peer and authenticator layers. - - [c] EAP peer and authenticator layers. Based on the Code field, the - EAP layer demultiplexes incoming EAP packets to the EAP peer and - authenticator layers. Typically, an EAP implementation on a - given host will support either peer or authenticator - functionality, but it is possible for a host to act as both an - EAP peer and authenticator. In such an implementation both EAP - peer and authenticator layers will be present. - - [d] EAP method layers. EAP methods implement the authentication - algorithms and receive and transmit EAP messages via the EAP peer - and authenticator layers. Since fragmentation support is not - provided by EAP itself, this is the responsibility of EAP - methods, which are discussed in Section 5. - - The EAP multiplexing model is illustrated in Figure 1 below. Note - that there is no requirement that an implementation conform to this - model, as long as the on-the-wire behavior is consistent with it. - - - - - - - - - - - - - -Aboba, et al. Standards Track [Page 10] - -RFC 3748 EAP June 2004 - - - +-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+ - | | | | | | - | EAP method| EAP method| | EAP method| EAP method| - | Type = X | Type = Y | | Type = X | Type = Y | - | V | | | ^ | | - +-+-+-+-!-+-+-+-+-+-+-+-+ +-+-+-+-!-+-+-+-+-+-+-+-+ - | ! | | ! | - | EAP ! Peer layer | | EAP ! Auth. layer | - | ! | | ! | - +-+-+-+-!-+-+-+-+-+-+-+-+ +-+-+-+-!-+-+-+-+-+-+-+-+ - | ! | | ! | - | EAP ! layer | | EAP ! layer | - | ! | | ! | - +-+-+-+-!-+-+-+-+-+-+-+-+ +-+-+-+-!-+-+-+-+-+-+-+-+ - | ! | | ! | - | Lower ! layer | | Lower ! layer | - | ! | | ! | - +-+-+-+-!-+-+-+-+-+-+-+-+ +-+-+-+-!-+-+-+-+-+-+-+-+ - ! ! - ! Peer ! Authenticator - +------------>-------------+ - - Figure 1: EAP Multiplexing Model - - Within EAP, the Code field functions much like a protocol number in - IP. It is assumed that the EAP layer demultiplexes incoming EAP - packets according to the Code field. Received EAP packets with - Code=1 (Request), 3 (Success), and 4 (Failure) are delivered by the - EAP layer to the EAP peer layer, if implemented. EAP packets with - Code=2 (Response) are delivered to the EAP authenticator layer, if - implemented. - - Within EAP, the Type field functions much like a port number in UDP - or TCP. It is assumed that the EAP peer and authenticator layers - demultiplex incoming EAP packets according to their Type, and deliver - them only to the EAP method corresponding to that Type. An EAP - method implementation on a host may register to receive packets from - the peer or authenticator layers, or both, depending on which role(s) - it supports. - - Since EAP authentication methods may wish to access the Identity, - implementations SHOULD make the Identity Request and Response - accessible to authentication methods (Types 4 or greater), in - addition to the Identity method. The Identity Type is discussed in - Section 5.1. - - - - - - -Aboba, et al. Standards Track [Page 11] - -RFC 3748 EAP June 2004 - - - A Notification Response is only used as confirmation that the peer - received the Notification Request, not that it has processed it, or - displayed the message to the user. It cannot be assumed that the - contents of the Notification Request or Response are available to - another method. The Notification Type is discussed in Section 5.2. - - Nak (Type 3) or Expanded Nak (Type 254) are utilized for the purposes - of method negotiation. Peers respond to an initial EAP Request for - an unacceptable Type with a Nak Response (Type 3) or Expanded Nak - Response (Type 254). It cannot be assumed that the contents of the - Nak Response(s) are available to another method. The Nak Type(s) are - discussed in Section 5.3. - - EAP packets with Codes of Success or Failure do not include a Type - field, and are not delivered to an EAP method. Success and Failure - are discussed in Section 4.2. - - Given these considerations, the Success, Failure, Nak Response(s), - and Notification Request/Response messages MUST NOT be used to carry - data destined for delivery to other EAP methods. - -2.3. Pass-Through Behavior - - When operating as a "pass-through authenticator", an authenticator - performs checks on the Code, Identifier, and Length fields as - described in Section 4.1. It forwards EAP packets received from the - peer and destined to its authenticator layer to the backend - authentication server; packets received from the backend - authentication server destined to the peer are forwarded to it. - - A host receiving an EAP packet may only do one of three things with - it: act on it, drop it, or forward it. The forwarding decision is - typically based only on examination of the Code, Identifier, and - Length fields. A pass-through authenticator implementation MUST be - capable of forwarding EAP packets received from the peer with Code=2 - (Response) to the backend authentication server. It also MUST be - capable of receiving EAP packets from the backend authentication - server and forwarding EAP packets of Code=1 (Request), Code=3 - (Success), and Code=4 (Failure) to the peer. - - Unless the authenticator implements one or more authentication - methods locally which support the authenticator role, the EAP method - layer header fields (Type, Type-Data) are not examined as part of the - forwarding decision. Where the authenticator supports local - authentication methods, it MAY examine the Type field to determine - whether to act on the packet itself or forward it. Compliant pass- - through authenticator implementations MUST by default forward EAP - packets of any Type. - - - -Aboba, et al. Standards Track [Page 12] - -RFC 3748 EAP June 2004 - - - EAP packets received with Code=1 (Request), Code=3 (Success), and - Code=4 (Failure) are demultiplexed by the EAP layer and delivered to - the peer layer. Therefore, unless a host implements an EAP peer - layer, these packets will be silently discarded. Similarly, EAP - packets received with Code=2 (Response) are demultiplexed by the EAP - layer and delivered to the authenticator layer. Therefore, unless a - host implements an EAP authenticator layer, these packets will be - silently discarded. The behavior of a "pass-through peer" is - undefined within this specification, and is unsupported by AAA - protocols such as RADIUS [RFC3579] and Diameter [DIAM-EAP]. - - The forwarding model is illustrated in Figure 2. - - Peer Pass-through Authenticator Authentication - Server - - +-+-+-+-+-+-+ +-+-+-+-+-+-+ - | | | | - |EAP method | |EAP method | - | V | | ^ | - +-+-+-!-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-!-+-+-+ - | ! | |EAP | EAP | | | ! | - | ! | |Peer | Auth.| EAP Auth. | | ! | - |EAP ! peer| | | +-----------+ | |EAP !Auth.| - | ! | | | ! | ! | | ! | - +-+-+-!-+-+-+ +-+-+-+-!-+-+-+-+-+-!-+-+-+-+ +-+-+-!-+-+-+ - | ! | | ! | ! | | ! | - |EAP !layer| | EAP !layer| EAP !layer | |EAP !layer| - | ! | | ! | ! | | ! | - +-+-+-!-+-+-+ +-+-+-+-!-+-+-+-+-+-!-+-+-+-+ +-+-+-!-+-+-+ - | ! | | ! | ! | | ! | - |Lower!layer| | Lower!layer| AAA ! /IP | | AAA ! /IP | - | ! | | ! | ! | | ! | - +-+-+-!-+-+-+ +-+-+-+-!-+-+-+-+-+-!-+-+-+-+ +-+-+-!-+-+-+ - ! ! ! ! - ! ! ! ! - +-------->--------+ +--------->-------+ - - - Figure 2: Pass-through Authenticator - - For sessions in which the authenticator acts as a pass-through, it - MUST determine the outcome of the authentication solely based on the - Accept/Reject indication sent by the backend authentication server; - the outcome MUST NOT be determined by the contents of an EAP packet - sent along with the Accept/Reject indication, or the absence of such - an encapsulated EAP packet. - - - - -Aboba, et al. Standards Track [Page 13] - -RFC 3748 EAP June 2004 - - -2.4. Peer-to-Peer Operation - - Since EAP is a peer-to-peer protocol, an independent and simultaneous - authentication may take place in the reverse direction (depending on - the capabilities of the lower layer). Both ends of the link may act - as authenticators and peers at the same time. In this case, it is - necessary for both ends to implement EAP authenticator and peer - layers. In addition, the EAP method implementations on both peers - must support both authenticator and peer functionality. - - Although EAP supports peer-to-peer operation, some EAP - implementations, methods, AAA protocols, and link layers may not - support this. Some EAP methods may support asymmetric - authentication, with one type of credential being required for the - peer and another type for the authenticator. Hosts supporting peer- - to-peer operation with such a method would need to be provisioned - with both types of credentials. - - For example, EAP-TLS [RFC2716] is a client-server protocol in which - distinct certificate profiles are typically utilized for the client - and server. This implies that a host supporting peer-to-peer - authentication with EAP-TLS would need to implement both the EAP peer - and authenticator layers, support both peer and authenticator roles - in the EAP-TLS implementation, and provision certificates appropriate - for each role. - - AAA protocols such as RADIUS/EAP [RFC3579] and Diameter EAP [DIAM- - EAP] only support "pass-through authenticator" operation. As noted - in [RFC3579] Section 2.6.2, a RADIUS server responds to an Access- - Request encapsulating an EAP-Request, Success, or Failure packet with - an Access-Reject. There is therefore no support for "pass-through - peer" operation. - - Even where a method is used which supports mutual authentication and - result indications, several considerations may dictate that two EAP - authentications (one in each direction) are required. These include: - - [1] Support for bi-directional session key derivation in the lower - layer. Lower layers such as IEEE 802.11 may only support uni- - directional derivation and transport of transient session keys. - For example, the group-key handshake defined in [IEEE-802.11i] is - uni-directional, since in IEEE 802.11 infrastructure mode, only - the Access Point (AP) sends multicast/broadcast traffic. In IEEE - 802.11 ad hoc mode, where either peer may send - multicast/broadcast traffic, two uni-directional group-key - - - - - - -Aboba, et al. Standards Track [Page 14] - -RFC 3748 EAP June 2004 - - - exchanges are required. Due to limitations of the design, this - also implies the need for unicast key derivations and EAP method - exchanges to occur in each direction. - - [2] Support for tie-breaking in the lower layer. Lower layers such - as IEEE 802.11 ad hoc do not support "tie breaking" wherein two - hosts initiating authentication with each other will only go - forward with a single authentication. This implies that even if - 802.11 were to support a bi-directional group-key handshake, then - two authentications, one in each direction, might still occur. - - [3] Peer policy satisfaction. EAP methods may support result - indications, enabling the peer to indicate to the EAP server - within the method that it successfully authenticated the EAP - server, as well as for the server to indicate that it has - authenticated the peer. However, a pass-through authenticator - will not be aware that the peer has accepted the credentials - offered by the EAP server, unless this information is provided to - the authenticator via the AAA protocol. The authenticator SHOULD - interpret the receipt of a key attribute within an Accept packet - as an indication that the peer has successfully authenticated the - server. - - However, it is possible that the EAP peer's access policy was not - satisfied during the initial EAP exchange, even though mutual - authentication occurred. For example, the EAP authenticator may not - have demonstrated authorization to act in both peer and authenticator - roles. As a result, the peer may require an additional - authentication in the reverse direction, even if the peer provided an - indication that the EAP server had successfully authenticated to it. - -3. Lower Layer Behavior - -3.1. Lower Layer Requirements - - EAP makes the following assumptions about lower layers: - - [1] Unreliable transport. In EAP, the authenticator retransmits - Requests that have not yet received Responses so that EAP does - not assume that lower layers are reliable. Since EAP defines its - own retransmission behavior, it is possible (though undesirable) - for retransmission to occur both in the lower layer and the EAP - layer when EAP is run over a reliable lower layer. - - - - - - - - -Aboba, et al. Standards Track [Page 15] - -RFC 3748 EAP June 2004 - - - Note that EAP Success and Failure packets are not retransmitted. - Without a reliable lower layer, and with a non-negligible error rate, - these packets can be lost, resulting in timeouts. It is therefore - desirable for implementations to improve their resilience to loss of - EAP Success or Failure packets, as described in Section 4.2. - - [2] Lower layer error detection. While EAP does not assume that the - lower layer is reliable, it does rely on lower layer error - detection (e.g., CRC, Checksum, MIC, etc.). EAP methods may not - include a MIC, or if they do, it may not be computed over all the - fields in the EAP packet, such as the Code, Identifier, Length, - or Type fields. As a result, without lower layer error - detection, undetected errors could creep into the EAP layer or - EAP method layer header fields, resulting in authentication - failures. - - For example, EAP TLS [RFC2716], which computes its MIC over the - Type-Data field only, regards MIC validation failures as a fatal - error. Without lower layer error detection, this method, and - others like it, will not perform reliably. - - [3] Lower layer security. EAP does not require lower layers to - provide security services such as per-packet confidentiality, - authentication, integrity, and replay protection. However, where - these security services are available, EAP methods supporting Key - Derivation (see Section 7.2.1) can be used to provide dynamic - keying material. This makes it possible to bind the EAP - authentication to subsequent data and protect against data - modification, spoofing, or replay. See Section 7.1 for details. - - [4] Minimum MTU. EAP is capable of functioning on lower layers that - provide an EAP MTU size of 1020 octets or greater. - - EAP does not support path MTU discovery, and fragmentation and - reassembly is not supported by EAP, nor by the methods defined in - this specification: Identity (1), Notification (2), Nak Response - (3), MD5-Challenge (4), One Time Password (5), Generic Token Card - (6), and expanded Nak Response (254) Types. - - Typically, the EAP peer obtains information on the EAP MTU from - the lower layers and sets the EAP frame size to an appropriate - value. Where the authenticator operates in pass-through mode, - the authentication server does not have a direct way of - determining the EAP MTU, and therefore relies on the - authenticator to provide it with this information, such as via - the Framed-MTU attribute, as described in [RFC3579], Section 2.4. - - - - - -Aboba, et al. Standards Track [Page 16] - -RFC 3748 EAP June 2004 - - - While methods such as EAP-TLS [RFC2716] support fragmentation and - reassembly, EAP methods originally designed for use within PPP - where a 1500 octet MTU is guaranteed for control frames (see - [RFC1661], Section 6.1) may lack fragmentation and reassembly - features. - - EAP methods can assume a minimum EAP MTU of 1020 octets in the - absence of other information. EAP methods SHOULD include support - for fragmentation and reassembly if their payloads can be larger - than this minimum EAP MTU. - - EAP is a lock-step protocol, which implies a certain inefficiency - when handling fragmentation and reassembly. Therefore, if the - lower layer supports fragmentation and reassembly (such as where - EAP is transported over IP), it may be preferable for - fragmentation and reassembly to occur in the lower layer rather - than in EAP. This can be accomplished by providing an - artificially large EAP MTU to EAP, causing fragmentation and - reassembly to be handled within the lower layer. - - [5] Possible duplication. Where the lower layer is reliable, it will - provide the EAP layer with a non-duplicated stream of packets. - However, while it is desirable that lower layers provide for - non-duplication, this is not a requirement. The Identifier field - provides both the peer and authenticator with the ability to - detect duplicates. - - [6] Ordering guarantees. EAP does not require the Identifier to be - monotonically increasing, and so is reliant on lower layer - ordering guarantees for correct operation. EAP was originally - defined to run on PPP, and [RFC1661] Section 1 has an ordering - requirement: - - "The Point-to-Point Protocol is designed for simple links - which transport packets between two peers. These links - provide full-duplex simultaneous bi-directional operation, - and are assumed to deliver packets in order." - - Lower layer transports for EAP MUST preserve ordering between a - source and destination at a given priority level (the ordering - guarantee provided by [IEEE-802]). - - Reordering, if it occurs, will typically result in an EAP - authentication failure, causing EAP authentication to be re-run. - In an environment in which reordering is likely, it is therefore - expected that EAP authentication failures will be common. It is - RECOMMENDED that EAP only be run over lower layers that provide - ordering guarantees; running EAP over raw IP or UDP transport is - - - -Aboba, et al. Standards Track [Page 17] - -RFC 3748 EAP June 2004 - - - NOT RECOMMENDED. Encapsulation of EAP within RADIUS [RFC3579] - satisfies ordering requirements, since RADIUS is a "lockstep" - protocol that delivers packets in order. - -3.2. EAP Usage Within PPP - - In order to establish communications over a point-to-point link, each - end of the PPP link first sends LCP packets to configure the data - link during the Link Establishment phase. After the link has been - established, PPP provides for an optional Authentication phase before - proceeding to the Network-Layer Protocol phase. - - By default, authentication is not mandatory. If authentication of - the link is desired, an implementation MUST specify the - Authentication Protocol Configuration Option during the Link - Establishment phase. - - If the identity of the peer has been established in the - Authentication phase, the server can use that identity in the - selection of options for the following network layer negotiations. - - When implemented within PPP, EAP does not select a specific - authentication mechanism at the PPP Link Control Phase, but rather - postpones this until the Authentication Phase. This allows the - authenticator to request more information before determining the - specific authentication mechanism. This also permits the use of a - "backend" server which actually implements the various mechanisms - while the PPP authenticator merely passes through the authentication - exchange. The PPP Link Establishment and Authentication phases, and - the Authentication Protocol Configuration Option, are defined in The - Point-to-Point Protocol (PPP) [RFC1661]. - -3.2.1. PPP Configuration Option Format - - A summary of the PPP Authentication Protocol Configuration Option - format to negotiate EAP follows. The fields are transmitted from - left to right. - - Exactly one EAP packet is encapsulated in the Information field of a - PPP Data Link Layer frame where the protocol field indicates type hex - C227 (PPP EAP). - - - - - - - - - - -Aboba, et al. Standards Track [Page 18] - -RFC 3748 EAP June 2004 - - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Type | Length | Authentication Protocol | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Type - - 3 - - Length - - 4 - - Authentication Protocol - - C227 (Hex) for Extensible Authentication Protocol (EAP) - -3.3. EAP Usage Within IEEE 802 - - The encapsulation of EAP over IEEE 802 is defined in [IEEE-802.1X]. - The IEEE 802 encapsulation of EAP does not involve PPP, and IEEE - 802.1X does not include support for link or network layer - negotiations. As a result, within IEEE 802.1X, it is not possible to - negotiate non-EAP authentication mechanisms, such as PAP or CHAP - [RFC1994]. - -3.4. Lower Layer Indications - - The reliability and security of lower layer indications is dependent - on the lower layer. Since EAP is media independent, the presence or - absence of lower layer security is not taken into account in the - processing of EAP messages. - - To improve reliability, if a peer receives a lower layer success - indication as defined in Section 7.2, it MAY conclude that a Success - packet has been lost, and behave as if it had actually received a - Success packet. This includes choosing to ignore the Success in some - circumstances as described in Section 4.2. - - A discussion of some reliability and security issues with lower layer - indications in PPP, IEEE 802 wired networks, and IEEE 802.11 wireless - LANs can be found in the Security Considerations, Section 7.12. - - After EAP authentication is complete, the peer will typically - transmit and receive data via the authenticator. It is desirable to - provide assurance that the entities transmitting data are the same - ones that successfully completed EAP authentication. To accomplish - - - -Aboba, et al. Standards Track [Page 19] - -RFC 3748 EAP June 2004 - - - this, it is necessary for the lower layer to provide per-packet - integrity, authentication and replay protection, and to bind these - per-packet services to the keys derived during EAP authentication. - Otherwise, it is possible for subsequent data traffic to be modified, - spoofed, or replayed. - - Where keying material for the lower layer ciphersuite is itself - provided by EAP, ciphersuite negotiation and key activation are - controlled by the lower layer. In PPP, ciphersuites are negotiated - within ECP so that it is not possible to use keys derived from EAP - authentication until the completion of ECP. Therefore, an initial - EAP exchange cannot be protected by a PPP ciphersuite, although EAP - re-authentication can be protected. - - In IEEE 802 media, initial key activation also typically occurs after - completion of EAP authentication. Therefore an initial EAP exchange - typically cannot be protected by the lower layer ciphersuite, - although an EAP re-authentication or pre-authentication exchange can - be protected. - -4. EAP Packet Format - - A summary of the EAP packet format is shown below. The fields are - transmitted from left to right. - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Code | Identifier | Length | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Data ... - +-+-+-+-+ - - Code - - The Code field is one octet and identifies the Type of EAP packet. - EAP Codes are assigned as follows: - - 1 Request - 2 Response - 3 Success - 4 Failure - - Since EAP only defines Codes 1-4, EAP packets with other codes - MUST be silently discarded by both authenticators and peers. - - - - - - -Aboba, et al. Standards Track [Page 20] - -RFC 3748 EAP June 2004 - - - Identifier - - The Identifier field is one octet and aids in matching Responses - with Requests. - - Length - - The Length field is two octets and indicates the length, in - octets, of the EAP packet including the Code, Identifier, Length, - and Data fields. Octets outside the range of the Length field - should be treated as Data Link Layer padding and MUST be ignored - upon reception. A message with the Length field set to a value - larger than the number of received octets MUST be silently - discarded. - - Data - - The Data field is zero or more octets. The format of the Data - field is determined by the Code field. - -4.1. Request and Response - - Description - - The Request packet (Code field set to 1) is sent by the - authenticator to the peer. Each Request has a Type field which - serves to indicate what is being requested. Additional Request - packets MUST be sent until a valid Response packet is received, an - optional retry counter expires, or a lower layer failure - indication is received. - - Retransmitted Requests MUST be sent with the same Identifier value - in order to distinguish them from new Requests. The content of - the data field is dependent on the Request Type. The peer MUST - send a Response packet in reply to a valid Request packet. - Responses MUST only be sent in reply to a valid Request and never - be retransmitted on a timer. - - If a peer receives a valid duplicate Request for which it has - already sent a Response, it MUST resend its original Response - without reprocessing the Request. Requests MUST be processed in - the order that they are received, and MUST be processed to their - completion before inspecting the next Request. - - A summary of the Request and Response packet format follows. The - fields are transmitted from left to right. - - - - - -Aboba, et al. Standards Track [Page 21] - -RFC 3748 EAP June 2004 - - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Code | Identifier | Length | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Type | Type-Data ... - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+- - - Code - - 1 for Request - 2 for Response - - Identifier - - The Identifier field is one octet. The Identifier field MUST be - the same if a Request packet is retransmitted due to a timeout - while waiting for a Response. Any new (non-retransmission) - Requests MUST modify the Identifier field. - - The Identifier field of the Response MUST match that of the - currently outstanding Request. An authenticator receiving a - Response whose Identifier value does not match that of the - currently outstanding Request MUST silently discard the Response. - - In order to avoid confusion between new Requests and - retransmissions, the Identifier value chosen for each new Request - need only be different from the previous Request, but need not be - unique within the conversation. One way to achieve this is to - start the Identifier at an initial value and increment it for each - new Request. Initializing the first Identifier with a random - number rather than starting from zero is recommended, since it - makes sequence attacks somewhat more difficult. - - Since the Identifier space is unique to each session, - authenticators are not restricted to only 256 simultaneous - authentication conversations. Similarly, with re-authentication, - an EAP conversation might continue over a long period of time, and - is not limited to only 256 roundtrips. - - Implementation Note: The authenticator is responsible for - retransmitting Request messages. If the Request message is obtained - from elsewhere (such as from a backend authentication server), then - the authenticator will need to save a copy of the Request in order to - accomplish this. The peer is responsible for detecting and handling - duplicate Request messages before processing them in any way, - including passing them on to an outside party. The authenticator is - also responsible for discarding Response messages with a non-matching - - - -Aboba, et al. Standards Track [Page 22] - -RFC 3748 EAP June 2004 - - - Identifier value before acting on them in any way, including passing - them on to the backend authentication server for verification. Since - the authenticator can retransmit before receiving a Response from the - peer, the authenticator can receive multiple Responses, each with a - matching Identifier. Until a new Request is received by the - authenticator, the Identifier value is not updated, so that the - authenticator forwards Responses to the backend authentication - server, one at a time. - - Length - - The Length field is two octets and indicates the length of the EAP - packet including the Code, Identifier, Length, Type, and Type-Data - fields. Octets outside the range of the Length field should be - treated as Data Link Layer padding and MUST be ignored upon - reception. A message with the Length field set to a value larger - than the number of received octets MUST be silently discarded. - - Type - - The Type field is one octet. This field indicates the Type of - Request or Response. A single Type MUST be specified for each EAP - Request or Response. An initial specification of Types follows in - Section 5 of this document. - - The Type field of a Response MUST either match that of the - Request, or correspond to a legacy or Expanded Nak (see Section - 5.3) indicating that a Request Type is unacceptable to the peer. - A peer MUST NOT send a Nak (legacy or expanded) in response to a - Request, after an initial non-Nak Response has been sent. An EAP - server receiving a Response not meeting these requirements MUST - silently discard it. - - Type-Data - - The Type-Data field varies with the Type of Request and the - associated Response. - -4.2. Success and Failure - - The Success packet is sent by the authenticator to the peer after - completion of an EAP authentication method (Type 4 or greater) to - indicate that the peer has authenticated successfully to the - authenticator. The authenticator MUST transmit an EAP packet with - the Code field set to 3 (Success). If the authenticator cannot - authenticate the peer (unacceptable Responses to one or more - Requests), then after unsuccessful completion of the EAP method in - progress, the implementation MUST transmit an EAP packet with the - - - -Aboba, et al. Standards Track [Page 23] - -RFC 3748 EAP June 2004 - - - Code field set to 4 (Failure). An authenticator MAY wish to issue - multiple Requests before sending a Failure response in order to allow - for human typing mistakes. Success and Failure packets MUST NOT - contain additional data. - - Success and Failure packets MUST NOT be sent by an EAP authenticator - if the specification of the given method does not explicitly permit - the method to finish at that point. A peer EAP implementation - receiving a Success or Failure packet where sending one is not - explicitly permitted MUST silently discard it. By default, an EAP - peer MUST silently discard a "canned" Success packet (a Success - packet sent immediately upon connection). This ensures that a rogue - authenticator will not be able to bypass mutual authentication by - sending a Success packet prior to conclusion of the EAP method - conversation. - - Implementation Note: Because the Success and Failure packets are not - acknowledged, they are not retransmitted by the authenticator, and - may be potentially lost. A peer MUST allow for this circumstance as - described in this note. See also Section 3.4 for guidance on the - processing of lower layer success and failure indications. - - As described in Section 2.1, only a single EAP authentication method - is allowed within an EAP conversation. EAP methods may implement - result indications. After the authenticator sends a failure result - indication to the peer, regardless of the response from the peer, it - MUST subsequently send a Failure packet. After the authenticator - sends a success result indication to the peer and receives a success - result indication from the peer, it MUST subsequently send a Success - packet. - - On the peer, once the method completes unsuccessfully (that is, - either the authenticator sends a failure result indication, or the - peer decides that it does not want to continue the conversation, - possibly after sending a failure result indication), the peer MUST - terminate the conversation and indicate failure to the lower layer. - The peer MUST silently discard Success packets and MAY silently - discard Failure packets. As a result, loss of a Failure packet need - not result in a timeout. - - On the peer, after success result indications have been exchanged by - both sides, a Failure packet MUST be silently discarded. The peer - MAY, in the event that an EAP Success is not received, conclude that - the EAP Success packet was lost and that authentication concluded - successfully. - - - - - - -Aboba, et al. Standards Track [Page 24] - -RFC 3748 EAP June 2004 - - - If the authenticator has not sent a result indication, and the peer - is willing to continue the conversation, the peer waits for a Success - or Failure packet once the method completes, and MUST NOT silently - discard either of them. In the event that neither a Success nor - Failure packet is received, the peer SHOULD terminate the - conversation to avoid lengthy timeouts in case the lost packet was an - EAP Failure. - - If the peer attempts to authenticate to the authenticator and fails - to do so, the authenticator MUST send a Failure packet and MUST NOT - grant access by sending a Success packet. However, an authenticator - MAY omit having the peer authenticate to it in situations where - limited access is offered (e.g., guest access). In this case, the - authenticator MUST send a Success packet. - - Where the peer authenticates successfully to the authenticator, but - the authenticator does not send a result indication, the - authenticator MAY deny access by sending a Failure packet where the - peer is not currently authorized for network access. - - A summary of the Success and Failure packet format is shown below. - The fields are transmitted from left to right. - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Code | Identifier | Length | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Code - - 3 for Success - 4 for Failure - - Identifier - - The Identifier field is one octet and aids in matching replies to - Responses. The Identifier field MUST match the Identifier field - of the Response packet that it is sent in response to. - - Length - - 4 - - - - - - - - -Aboba, et al. Standards Track [Page 25] - -RFC 3748 EAP June 2004 - - -4.3. Retransmission Behavior - - Because the authentication process will often involve user input, - some care must be taken when deciding upon retransmission strategies - and authentication timeouts. By default, where EAP is run over an - unreliable lower layer, the EAP retransmission timer SHOULD be - dynamically estimated. A maximum of 3-5 retransmissions is - suggested. - - When run over a reliable lower layer (e.g., EAP over ISAKMP/TCP, as - within [PIC]), the authenticator retransmission timer SHOULD be set - to an infinite value, so that retransmissions do not occur at the EAP - layer. The peer may still maintain a timeout value so as to avoid - waiting indefinitely for a Request. - - Where the authentication process requires user input, the measured - round trip times may be determined by user responsiveness rather than - network characteristics, so that dynamic RTO estimation may not be - helpful. Instead, the retransmission timer SHOULD be set so as to - provide sufficient time for the user to respond, with longer timeouts - required in certain cases, such as where Token Cards (see Section - 5.6) are involved. - - In order to provide the EAP authenticator with guidance as to the - appropriate timeout value, a hint can be communicated to the - authenticator by the backend authentication server (such as via the - RADIUS Session-Timeout attribute). - - In order to dynamically estimate the EAP retransmission timer, the - algorithms for the estimation of SRTT, RTTVAR, and RTO described in - [RFC2988] are RECOMMENDED, including use of Karn's algorithm, with - the following potential modifications: - - [a] In order to avoid synchronization behaviors that can occur with - fixed timers among distributed systems, the retransmission timer - is calculated with a jitter by using the RTO value and randomly - adding a value drawn between -RTOmin/2 and RTOmin/2. Alternative - calculations to create jitter MAY be used. These MUST be - pseudo-random. For a discussion of pseudo-random number - generation, see [RFC1750]. - - [b] When EAP is transported over a single link (as opposed to over - the Internet), smaller values of RTOinitial, RTOmin, and RTOmax - MAY be used. Recommended values are RTOinitial=1 second, - RTOmin=200ms, and RTOmax=20 seconds. - - - - - - -Aboba, et al. Standards Track [Page 26] - -RFC 3748 EAP June 2004 - - - [c] When EAP is transported over a single link (as opposed to over - the Internet), estimates MAY be done on a per-authenticator - basis, rather than a per-session basis. This enables the - retransmission estimate to make the most use of information on - link-layer behavior. - - [d] An EAP implementation MAY clear SRTT and RTTVAR after backing off - the timer multiple times, as it is likely that the current SRTT - and RTTVAR are bogus in this situation. Once SRTT and RTTVAR are - cleared, they should be initialized with the next RTT sample - taken as described in [RFC2988] equation 2.2. - -5. Initial EAP Request/Response Types - - This section defines the initial set of EAP Types used in Request/ - Response exchanges. More Types may be defined in future documents. - The Type field is one octet and identifies the structure of an EAP - Request or Response packet. The first 3 Types are considered special - case Types. - - The remaining Types define authentication exchanges. Nak (Type 3) or - Expanded Nak (Type 254) are valid only for Response packets, they - MUST NOT be sent in a Request. - - All EAP implementations MUST support Types 1-4, which are defined in - this document, and SHOULD support Type 254. Implementations MAY - support other Types defined here or in future RFCs. - - 1 Identity - 2 Notification - 3 Nak (Response only) - 4 MD5-Challenge - 5 One Time Password (OTP) - 6 Generic Token Card (GTC) - 254 Expanded Types - 255 Experimental use - - EAP methods MAY support authentication based on shared secrets. If - the shared secret is a passphrase entered by the user, - implementations MAY support entering passphrases with non-ASCII - characters. In this case, the input should be processed using an - appropriate stringprep [RFC3454] profile, and encoded in octets using - UTF-8 encoding [RFC2279]. A preliminary version of a possible - stringprep profile is described in [SASLPREP]. - - - - - - - -Aboba, et al. Standards Track [Page 27] - -RFC 3748 EAP June 2004 - - -5.1. Identity - - Description - - The Identity Type is used to query the identity of the peer. - Generally, the authenticator will issue this as the initial - Request. An optional displayable message MAY be included to - prompt the peer in the case where there is an expectation of - interaction with a user. A Response of Type 1 (Identity) SHOULD - be sent in Response to a Request with a Type of 1 (Identity). - - Some EAP implementations piggy-back various options into the - Identity Request after a NUL-character. By default, an EAP - implementation SHOULD NOT assume that an Identity Request or - Response can be larger than 1020 octets. - - It is RECOMMENDED that the Identity Response be used primarily for - routing purposes and selecting which EAP method to use. EAP - Methods SHOULD include a method-specific mechanism for obtaining - the identity, so that they do not have to rely on the Identity - Response. Identity Requests and Responses are sent in cleartext, - so an attacker may snoop on the identity, or even modify or spoof - identity exchanges. To address these threats, it is preferable - for an EAP method to include an identity exchange that supports - per-packet authentication, integrity and replay protection, and - confidentiality. The Identity Response may not be the appropriate - identity for the method; it may have been truncated or obfuscated - so as to provide privacy, or it may have been decorated for - routing purposes. Where the peer is configured to only accept - authentication methods supporting protected identity exchanges, - the peer MAY provide an abbreviated Identity Response (such as - omitting the peer-name portion of the NAI [RFC2486]). For further - discussion of identity protection, see Section 7.3. - - Implementation Note: The peer MAY obtain the Identity via user input. - It is suggested that the authenticator retry the Identity Request in - the case of an invalid Identity or authentication failure to allow - for potential typos on the part of the user. It is suggested that - the Identity Request be retried a minimum of 3 times before - terminating the authentication. The Notification Request MAY be used - to indicate an invalid authentication attempt prior to transmitting a - new Identity Request (optionally, the failure MAY be indicated within - the message of the new Identity Request itself). - - - - - - - - -Aboba, et al. Standards Track [Page 28] - -RFC 3748 EAP June 2004 - - - Type - - 1 - - Type-Data - - This field MAY contain a displayable message in the Request, - containing UTF-8 encoded ISO 10646 characters [RFC2279]. Where - the Request contains a null, only the portion of the field prior - to the null is displayed. If the Identity is unknown, the - Identity Response field should be zero bytes in length. The - Identity Response field MUST NOT be null terminated. In all - cases, the length of the Type-Data field is derived from the - Length field of the Request/Response packet. - - Security Claims (see Section 7.2): - - Auth. mechanism: None - Ciphersuite negotiation: No - Mutual authentication: No - Integrity protection: No - Replay protection: No - Confidentiality: No - Key derivation: No - Key strength: N/A - Dictionary attack prot.: N/A - Fast reconnect: No - Crypt. binding: N/A - Session independence: N/A - Fragmentation: No - Channel binding: No - -5.2. Notification - - Description - - The Notification Type is optionally used to convey a displayable - message from the authenticator to the peer. An authenticator MAY - send a Notification Request to the peer at any time when there is - no outstanding Request, prior to completion of an EAP - authentication method. The peer MUST respond to a Notification - Request with a Notification Response unless the EAP authentication - method specification prohibits the use of Notification messages. - In any case, a Nak Response MUST NOT be sent in response to a - Notification Request. Note that the default maximum length of a - Notification Request is 1020 octets. By default, this leaves at - most 1015 octets for the human readable message. - - - - -Aboba, et al. Standards Track [Page 29] - -RFC 3748 EAP June 2004 - - - An EAP method MAY indicate within its specification that - Notification messages must not be sent during that method. In - this case, the peer MUST silently discard Notification Requests - from the point where an initial Request for that Type is answered - with a Response of the same Type. - - The peer SHOULD display this message to the user or log it if it - cannot be displayed. The Notification Type is intended to provide - an acknowledged notification of some imperative nature, but it is - not an error indication, and therefore does not change the state - of the peer. Examples include a password with an expiration time - that is about to expire, an OTP sequence integer which is nearing - 0, an authentication failure warning, etc. In most circumstances, - Notification should not be required. - - Type - - 2 - - Type-Data - - The Type-Data field in the Request contains a displayable message - greater than zero octets in length, containing UTF-8 encoded ISO - 10646 characters [RFC2279]. The length of the message is - determined by the Length field of the Request packet. The message - MUST NOT be null terminated. A Response MUST be sent in reply to - the Request with a Type field of 2 (Notification). The Type-Data - field of the Response is zero octets in length. The Response - should be sent immediately (independent of how the message is - displayed or logged). - - Security Claims (see Section 7.2): - - Auth. mechanism: None - Ciphersuite negotiation: No - Mutual authentication: No - Integrity protection: No - Replay protection: No - Confidentiality: No - Key derivation: No - Key strength: N/A - Dictionary attack prot.: N/A - Fast reconnect: No - Crypt. binding: N/A - Session independence: N/A - Fragmentation: No - Channel binding: No - - - - -Aboba, et al. Standards Track [Page 30] - -RFC 3748 EAP June 2004 - - -5.3. Nak - -5.3.1. Legacy Nak - - Description - - The legacy Nak Type is valid only in Response messages. It is - sent in reply to a Request where the desired authentication Type - is unacceptable. Authentication Types are numbered 4 and above. - The Response contains one or more authentication Types desired by - the Peer. Type zero (0) is used to indicate that the sender has - no viable alternatives, and therefore the authenticator SHOULD NOT - send another Request after receiving a Nak Response containing a - zero value. - - Since the legacy Nak Type is valid only in Responses and has very - limited functionality, it MUST NOT be used as a general purpose - error indication, such as for communication of error messages, or - negotiation of parameters specific to a particular EAP method. - - Code - - 2 for Response. - - Identifier - - The Identifier field is one octet and aids in matching Responses - with Requests. The Identifier field of a legacy Nak Response MUST - match the Identifier field of the Request packet that it is sent - in response to. - - Length - - >=6 - - Type - - 3 - - Type-Data - - Where a peer receives a Request for an unacceptable authentication - Type (4-253,255), or a peer lacking support for Expanded Types - receives a Request for Type 254, a Nak Response (Type 3) MUST be - sent. The Type-Data field of the Nak Response (Type 3) MUST - contain one or more octets indicating the desired authentication - Type(s), one octet per Type, or the value zero (0) to indicate no - proposed alternative. A peer supporting Expanded Types that - - - -Aboba, et al. Standards Track [Page 31] - -RFC 3748 EAP June 2004 - - - receives a Request for an unacceptable authentication Type (4-253, - 255) MAY include the value 254 in the Nak Response (Type 3) to - indicate the desire for an Expanded authentication Type. If the - authenticator can accommodate this preference, it will respond - with an Expanded Type Request (Type 254). - - Security Claims (see Section 7.2): - - Auth. mechanism: None - Ciphersuite negotiation: No - Mutual authentication: No - Integrity protection: No - Replay protection: No - Confidentiality: No - Key derivation: No - Key strength: N/A - Dictionary attack prot.: N/A - Fast reconnect: No - Crypt. binding: N/A - Session independence: N/A - Fragmentation: No - Channel binding: No - - -5.3.2. Expanded Nak - - Description - - The Expanded Nak Type is valid only in Response messages. It MUST - be sent only in reply to a Request of Type 254 (Expanded Type) - where the authentication Type is unacceptable. The Expanded Nak - Type uses the Expanded Type format itself, and the Response - contains one or more authentication Types desired by the peer, all - in Expanded Type format. Type zero (0) is used to indicate that - the sender has no viable alternatives. The general format of the - Expanded Type is described in Section 5.7. - - Since the Expanded Nak Type is valid only in Responses and has - very limited functionality, it MUST NOT be used as a general - purpose error indication, such as for communication of error - messages, or negotiation of parameters specific to a particular - EAP method. - - Code - - 2 for Response. - - - - - -Aboba, et al. Standards Track [Page 32] - -RFC 3748 EAP June 2004 - - - Identifier - - The Identifier field is one octet and aids in matching Responses - with Requests. The Identifier field of an Expanded Nak Response - MUST match the Identifier field of the Request packet that it is - sent in response to. - - Length - - >=20 - - Type - - 254 - - Vendor-Id - - 0 (IETF) - - Vendor-Type - - 3 (Nak) - - Vendor-Data - - The Expanded Nak Type is only sent when the Request contains an - Expanded Type (254) as defined in Section 5.7. The Vendor-Data - field of the Nak Response MUST contain one or more authentication - Types (4 or greater), all in expanded format, 8 octets per Type, - or the value zero (0), also in Expanded Type format, to indicate - no proposed alternative. The desired authentication Types may - include a mixture of Vendor-Specific and IETF Types. For example, - an Expanded Nak Response indicating a preference for OTP (Type 5), - and an MIT (Vendor-Id=20) Expanded Type of 6 would appear as - follows: - - - - - - - - - - - - - - - - -Aboba, et al. Standards Track [Page 33] - -RFC 3748 EAP June 2004 - - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | 2 | Identifier | Length=28 | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Type=254 | 0 (IETF) | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | 3 (Nak) | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Type=254 | 0 (IETF) | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | 5 (OTP) | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Type=254 | 20 (MIT) | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | 6 | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - An Expanded Nak Response indicating a no desired alternative would - appear as follows: - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | 2 | Identifier | Length=20 | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Type=254 | 0 (IETF) | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | 3 (Nak) | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Type=254 | 0 (IETF) | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | 0 (No alternative) | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Security Claims (see Section 7.2): - - Auth. mechanism: None - Ciphersuite negotiation: No - Mutual authentication: No - Integrity protection: No - Replay protection: No - Confidentiality: No - Key derivation: No - Key strength: N/A - Dictionary attack prot.: N/A - Fast reconnect: No - Crypt. binding: N/A - - - -Aboba, et al. Standards Track [Page 34] - -RFC 3748 EAP June 2004 - - - Session independence: N/A - Fragmentation: No - Channel binding: No - - -5.4. MD5-Challenge - - Description - - The MD5-Challenge Type is analogous to the PPP CHAP protocol - [RFC1994] (with MD5 as the specified algorithm). The Request - contains a "challenge" message to the peer. A Response MUST be - sent in reply to the Request. The Response MAY be either of Type - 4 (MD5-Challenge), Nak (Type 3), or Expanded Nak (Type 254). The - Nak reply indicates the peer's desired authentication Type(s). - EAP peer and EAP server implementations MUST support the MD5- - Challenge mechanism. An authenticator that supports only pass- - through MUST allow communication with a backend authentication - server that is capable of supporting MD5-Challenge, although the - EAP authenticator implementation need not support MD5-Challenge - itself. However, if the EAP authenticator can be configured to - authenticate peers locally (e.g., not operate in pass-through), - then the requirement for support of the MD5-Challenge mechanism - applies. - - Note that the use of the Identifier field in the MD5-Challenge - Type is different from that described in [RFC1994]. EAP allows - for retransmission of MD5-Challenge Request packets, while - [RFC1994] states that both the Identifier and Challenge fields - MUST change each time a Challenge (the CHAP equivalent of the - MD5-Challenge Request packet) is sent. - - Note: [RFC1994] treats the shared secret as an octet string, and - does not specify how it is entered into the system (or if it is - handled by the user at all). EAP MD5-Challenge implementations - MAY support entering passphrases with non-ASCII characters. See - Section 5 for instructions how the input should be processed and - encoded into octets. - - Type - - 4 - - Type-Data - - The contents of the Type-Data field is summarized below. For - reference on the use of these fields, see the PPP Challenge - Handshake Authentication Protocol [RFC1994]. - - - -Aboba, et al. Standards Track [Page 35] - -RFC 3748 EAP June 2004 - - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Value-Size | Value ... - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Name ... - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Security Claims (see Section 7.2): - - Auth. mechanism: Password or pre-shared key. - Ciphersuite negotiation: No - Mutual authentication: No - Integrity protection: No - Replay protection: No - Confidentiality: No - Key derivation: No - Key strength: N/A - Dictionary attack prot.: No - Fast reconnect: No - Crypt. binding: N/A - Session independence: N/A - Fragmentation: No - Channel binding: No - -5.5. One-Time Password (OTP) - - Description - - The One-Time Password system is defined in "A One-Time Password - System" [RFC2289] and "OTP Extended Responses" [RFC2243]. The - Request contains an OTP challenge in the format described in - [RFC2289]. A Response MUST be sent in reply to the Request. The - Response MUST be of Type 5 (OTP), Nak (Type 3), or Expanded Nak - (Type 254). The Nak Response indicates the peer's desired - authentication Type(s). The EAP OTP method is intended for use - with the One-Time Password system only, and MUST NOT be used to - provide support for cleartext passwords. - - Type - - 5 - - - - - - - - - -Aboba, et al. Standards Track [Page 36] - -RFC 3748 EAP June 2004 - - - Type-Data - - The Type-Data field contains the OTP "challenge" as a displayable - message in the Request. In the Response, this field is used for - the 6 words from the OTP dictionary [RFC2289]. The messages MUST - NOT be null terminated. The length of the field is derived from - the Length field of the Request/Reply packet. - - Note: [RFC2289] does not specify how the secret pass-phrase is - entered by the user, or how the pass-phrase is converted into - octets. EAP OTP implementations MAY support entering passphrases - with non-ASCII characters. See Section 5 for instructions on how - the input should be processed and encoded into octets. - - Security Claims (see Section 7.2): - - Auth. mechanism: One-Time Password - Ciphersuite negotiation: No - Mutual authentication: No - Integrity protection: No - Replay protection: Yes - Confidentiality: No - Key derivation: No - Key strength: N/A - Dictionary attack prot.: No - Fast reconnect: No - Crypt. binding: N/A - Session independence: N/A - Fragmentation: No - Channel binding: No - - -5.6. Generic Token Card (GTC) - - Description - - The Generic Token Card Type is defined for use with various Token - Card implementations which require user input. The Request - contains a displayable message and the Response contains the Token - Card information necessary for authentication. Typically, this - would be information read by a user from the Token card device and - entered as ASCII text. A Response MUST be sent in reply to the - Request. The Response MUST be of Type 6 (GTC), Nak (Type 3), or - Expanded Nak (Type 254). The Nak Response indicates the peer's - desired authentication Type(s). The EAP GTC method is intended - for use with the Token Cards supporting challenge/response - - - - - -Aboba, et al. Standards Track [Page 37] - -RFC 3748 EAP June 2004 - - - authentication and MUST NOT be used to provide support for - cleartext passwords in the absence of a protected tunnel with - server authentication. - - Type - - 6 - - Type-Data - - The Type-Data field in the Request contains a displayable message - greater than zero octets in length. The length of the message is - determined by the Length field of the Request packet. The message - MUST NOT be null terminated. A Response MUST be sent in reply to - the Request with a Type field of 6 (Generic Token Card). The - Response contains data from the Token Card required for - authentication. The length of the data is determined by the - Length field of the Response packet. - - EAP GTC implementations MAY support entering a response with non- - ASCII characters. See Section 5 for instructions how the input - should be processed and encoded into octets. - - Security Claims (see Section 7.2): - - Auth. mechanism: Hardware token. - Ciphersuite negotiation: No - Mutual authentication: No - Integrity protection: No - Replay protection: No - Confidentiality: No - Key derivation: No - Key strength: N/A - Dictionary attack prot.: No - Fast reconnect: No - Crypt. binding: N/A - Session independence: N/A - Fragmentation: No - Channel binding: No - - -5.7. Expanded Types - - Description - - Since many of the existing uses of EAP are vendor-specific, the - Expanded method Type is available to allow vendors to support - their own Expanded Types not suitable for general usage. - - - -Aboba, et al. Standards Track [Page 38] - -RFC 3748 EAP June 2004 - - - The Expanded Type is also used to expand the global Method Type - space beyond the original 255 values. A Vendor-Id of 0 maps the - original 255 possible Types onto a space of 2^32-1 possible Types. - (Type 0 is only used in a Nak Response to indicate no acceptable - alternative). - - An implementation that supports the Expanded attribute MUST treat - EAP Types that are less than 256 equivalently, whether they appear - as a single octet or as the 32-bit Vendor-Type within an Expanded - Type where Vendor-Id is 0. Peers not equipped to interpret the - Expanded Type MUST send a Nak as described in Section 5.3.1, and - negotiate a more suitable authentication method. - - A summary of the Expanded Type format is shown below. The fields - are transmitted from left to right. - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Type | Vendor-Id | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Vendor-Type | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Vendor data... - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Type - - 254 for Expanded Type - - Vendor-Id - - The Vendor-Id is 3 octets and represents the SMI Network - Management Private Enterprise Code of the Vendor in network byte - order, as allocated by IANA. A Vendor-Id of zero is reserved for - use by the IETF in providing an expanded global EAP Type space. - - Vendor-Type - - The Vendor-Type field is four octets and represents the vendor- - specific method Type. - - If the Vendor-Id is zero, the Vendor-Type field is an extension - and superset of the existing namespace for EAP Types. The first - 256 Types are reserved for compatibility with single-octet EAP - Types that have already been assigned or may be assigned in the - future. Thus, EAP Types from 0 through 255 are semantically - identical, whether they appear as single octet EAP Types or as - - - -Aboba, et al. Standards Track [Page 39] - -RFC 3748 EAP June 2004 - - - Vendor-Types when Vendor-Id is zero. There is one exception to - this rule: Expanded Nak and Legacy Nak packets share the same - Type, but must be treated differently because they have a - different format. - - Vendor-Data - - The Vendor-Data field is defined by the vendor. Where a Vendor-Id - of zero is present, the Vendor-Data field will be used for - transporting the contents of EAP methods of Types defined by the - IETF. - -5.8. Experimental - - Description - - The Experimental Type has no fixed format or content. It is - intended for use when experimenting with new EAP Types. This Type - is intended for experimental and testing purposes. No guarantee - is made for interoperability between peers using this Type, as - outlined in [RFC3692]. - - Type - - 255 - - Type-Data - - Undefined - -6. IANA Considerations - - This section provides guidance to the Internet Assigned Numbers - Authority (IANA) regarding registration of values related to the EAP - protocol, in accordance with BCP 26, [RFC2434]. - - There are two name spaces in EAP that require registration: Packet - Codes and method Types. - - EAP is not intended as a general-purpose protocol, and allocations - SHOULD NOT be made for purposes unrelated to authentication. - - The following terms are used here with the meanings defined in BCP - 26: "name space", "assigned value", "registration". - - The following policies are used here with the meanings defined in BCP - 26: "Private Use", "First Come First Served", "Expert Review", - "Specification Required", "IETF Consensus", "Standards Action". - - - -Aboba, et al. Standards Track [Page 40] - -RFC 3748 EAP June 2004 - - - For registration requests where a Designated Expert should be - consulted, the responsible IESG area director should appoint the - Designated Expert. The intention is that any allocation will be - accompanied by a published RFC. But in order to allow for the - allocation of values prior to the RFC being approved for publication, - the Designated Expert can approve allocations once it seems clear - that an RFC will be published. The Designated expert will post a - request to the EAP WG mailing list (or a successor designated by the - Area Director) for comment and review, including an Internet-Draft. - Before a period of 30 days has passed, the Designated Expert will - either approve or deny the registration request and publish a notice - of the decision to the EAP WG mailing list or its successor, as well - as informing IANA. A denial notice must be justified by an - explanation, and in the cases where it is possible, concrete - suggestions on how the request can be modified so as to become - acceptable should be provided. - -6.1. Packet Codes - - Packet Codes have a range from 1 to 255, of which 1-4 have been - allocated. Because a new Packet Code has considerable impact on - interoperability, a new Packet Code requires Standards Action, and - should be allocated starting at 5. - -6.2. Method Types - - The original EAP method Type space has a range from 1 to 255, and is - the scarcest resource in EAP, and thus must be allocated with care. - Method Types 1-45 have been allocated, with 20 available for re-use. - Method Types 20 and 46-191 may be allocated on the advice of a - Designated Expert, with Specification Required. - - Allocation of blocks of method Types (more than one for a given - purpose) should require IETF Consensus. EAP Type Values 192-253 are - reserved and allocation requires Standards Action. - - Method Type 254 is allocated for the Expanded Type. Where the - Vendor-Id field is non-zero, the Expanded Type is used for functions - specific only to one vendor's implementation of EAP, where no - interoperability is deemed useful. When used with a Vendor-Id of - zero, method Type 254 can also be used to provide for an expanded - IETF method Type space. Method Type values 256-4294967295 may be - allocated after Type values 1-191 have been allocated, on the advice - of a Designated Expert, with Specification Required. - - Method Type 255 is allocated for Experimental use, such as testing of - new EAP methods before a permanent Type is allocated. - - - - -Aboba, et al. Standards Track [Page 41] - -RFC 3748 EAP June 2004 - - -7. Security Considerations - - This section defines a generic threat model as well as the EAP method - security claims mitigating those threats. - - It is expected that the generic threat model and corresponding - security claims will used to define EAP method requirements for use - in specific environments. An example of such a requirements analysis - is provided in [IEEE-802.11i-req]. A security claims section is - required in EAP method specifications, so that EAP methods can be - evaluated against the requirements. - -7.1. Threat Model - - EAP was developed for use with PPP [RFC1661] and was later adapted - for use in wired IEEE 802 networks [IEEE-802] in [IEEE-802.1X]. - Subsequently, EAP has been proposed for use on wireless LAN networks - and over the Internet. In all these situations, it is possible for - an attacker to gain access to links over which EAP packets are - transmitted. For example, attacks on telephone infrastructure are - documented in [DECEPTION]. - - An attacker with access to the link may carry out a number of - attacks, including: - - [1] An attacker may try to discover user identities by snooping - authentication traffic. - - [2] An attacker may try to modify or spoof EAP packets. - - [3] An attacker may launch denial of service attacks by spoofing - lower layer indications or Success/Failure packets, by replaying - EAP packets, or by generating packets with overlapping - Identifiers. - - [4] An attacker may attempt to recover the pass-phrase by mounting - an offline dictionary attack. - - [5] An attacker may attempt to convince the peer to connect to an - untrusted network by mounting a man-in-the-middle attack. - - [6] An attacker may attempt to disrupt the EAP negotiation in order - cause a weak authentication method to be selected. - - [7] An attacker may attempt to recover keys by taking advantage of - weak key derivation techniques used within EAP methods. - - - - - -Aboba, et al. Standards Track [Page 42] - -RFC 3748 EAP June 2004 - - - [8] An attacker may attempt to take advantage of weak ciphersuites - subsequently used after the EAP conversation is complete. - - [9] An attacker may attempt to perform downgrading attacks on lower - layer ciphersuite negotiation in order to ensure that a weaker - ciphersuite is used subsequently to EAP authentication. - - [10] An attacker acting as an authenticator may provide incorrect - information to the EAP peer and/or server via out-of-band - mechanisms (such as via a AAA or lower layer protocol). This - includes impersonating another authenticator, or providing - inconsistent information to the peer and EAP server. - - Depending on the lower layer, these attacks may be carried out - without requiring physical proximity. Where EAP is used over - wireless networks, EAP packets may be forwarded by authenticators - (e.g., pre-authentication) so that the attacker need not be within - the coverage area of an authenticator in order to carry out an attack - on it or its peers. Where EAP is used over the Internet, attacks may - be carried out at an even greater distance. - -7.2. Security Claims - - In order to clearly articulate the security provided by an EAP - method, EAP method specifications MUST include a Security Claims - section, including the following declarations: - - [a] Mechanism. This is a statement of the authentication technology: - certificates, pre-shared keys, passwords, token cards, etc. - - [b] Security claims. This is a statement of the claimed security - properties of the method, using terms defined in Section 7.2.1: - mutual authentication, integrity protection, replay protection, - confidentiality, key derivation, dictionary attack resistance, - fast reconnect, cryptographic binding. The Security Claims - section of an EAP method specification SHOULD provide - justification for the claims that are made. This can be - accomplished by including a proof in an Appendix, or including a - reference to a proof. - - [c] Key strength. If the method derives keys, then the effective key - strength MUST be estimated. This estimate is meant for potential - users of the method to determine if the keys produced are strong - enough for the intended application. - - - - - - - -Aboba, et al. Standards Track [Page 43] - -RFC 3748 EAP June 2004 - - - The effective key strength SHOULD be stated as a number of bits, - defined as follows: If the effective key strength is N bits, the - best currently known methods to recover the key (with non- - negligible probability) require, on average, an effort comparable - to 2^(N-1) operations of a typical block cipher. The statement - SHOULD be accompanied by a short rationale, explaining how this - number was derived. This explanation SHOULD include the - parameters required to achieve the stated key strength based on - current knowledge of the algorithms. - - (Note: Although it is difficult to define what "comparable - effort" and "typical block cipher" exactly mean, reasonable - approximations are sufficient here. Refer to e.g. [SILVERMAN] - for more discussion.) - - The key strength depends on the methods used to derive the keys. - For instance, if keys are derived from a shared secret (such as a - password or a long-term secret), and possibly some public - information such as nonces, the effective key strength is limited - by the strength of the long-term secret (assuming that the - derivation procedure is computationally simple). To take another - example, when using public key algorithms, the strength of the - symmetric key depends on the strength of the public keys used. - - [d] Description of key hierarchy. EAP methods deriving keys MUST - either provide a reference to a key hierarchy specification, or - describe how Master Session Keys (MSKs) and Extended Master - Session Keys (EMSKs) are to be derived. - - [e] Indication of vulnerabilities. In addition to the security - claims that are made, the specification MUST indicate which of - the security claims detailed in Section 7.2.1 are NOT being made. - -7.2.1. Security Claims Terminology for EAP Methods - - These terms are used to describe the security properties of EAP - methods: - - Protected ciphersuite negotiation - This refers to the ability of an EAP method to negotiate the - ciphersuite used to protect the EAP conversation, as well as to - integrity protect the negotiation. It does not refer to the - ability to negotiate the ciphersuite used to protect data. - - - - - - - - -Aboba, et al. Standards Track [Page 44] - -RFC 3748 EAP June 2004 - - - Mutual authentication - This refers to an EAP method in which, within an interlocked - exchange, the authenticator authenticates the peer and the peer - authenticates the authenticator. Two independent one-way methods, - running in opposite directions do not provide mutual - authentication as defined here. - - Integrity protection - This refers to providing data origin authentication and protection - against unauthorized modification of information for EAP packets - (including EAP Requests and Responses). When making this claim, a - method specification MUST describe the EAP packets and fields - within the EAP packet that are protected. - - Replay protection - This refers to protection against replay of an EAP method or its - messages, including success and failure result indications. - - Confidentiality - This refers to encryption of EAP messages, including EAP Requests - and Responses, and success and failure result indications. A - method making this claim MUST support identity protection (see - Section 7.3). - - Key derivation - This refers to the ability of the EAP method to derive exportable - keying material, such as the Master Session Key (MSK), and - Extended Master Session Key (EMSK). The MSK is used only for - further key derivation, not directly for protection of the EAP - conversation or subsequent data. Use of the EMSK is reserved. - - Key strength - If the effective key strength is N bits, the best currently known - methods to recover the key (with non-negligible probability) - require, on average, an effort comparable to 2^(N-1) operations of - a typical block cipher. - - Dictionary attack resistance - Where password authentication is used, passwords are commonly - selected from a small set (as compared to a set of N-bit keys), - which raises a concern about dictionary attacks. A method may be - said to provide protection against dictionary attacks if, when it - uses a password as a secret, the method does not allow an offline - attack that has a work factor based on the number of passwords in - an attacker's dictionary. - - - - - - -Aboba, et al. Standards Track [Page 45] - -RFC 3748 EAP June 2004 - - - Fast reconnect - The ability, in the case where a security association has been - previously established, to create a new or refreshed security - association more efficiently or in a smaller number of round- - trips. - - Cryptographic binding - The demonstration of the EAP peer to the EAP server that a single - entity has acted as the EAP peer for all methods executed within a - tunnel method. Binding MAY also imply that the EAP server - demonstrates to the peer that a single entity has acted as the EAP - server for all methods executed within a tunnel method. If - executed correctly, binding serves to mitigate man-in-the-middle - vulnerabilities. - - Session independence - The demonstration that passive attacks (such as capture of the EAP - conversation) or active attacks (including compromise of the MSK - or EMSK) does not enable compromise of subsequent or prior MSKs or - EMSKs. - - Fragmentation - This refers to whether an EAP method supports fragmentation and - reassembly. As noted in Section 3.1, EAP methods should support - fragmentation and reassembly if EAP packets can exceed the minimum - MTU of 1020 octets. - - Channel binding - The communication within an EAP method of integrity-protected - channel properties such as endpoint identifiers which can be - compared to values communicated via out of band mechanisms (such - as via a AAA or lower layer protocol). - - Note: This list of security claims is not exhaustive. Additional - properties, such as additional denial-of-service protection, may be - relevant as well. - -7.3. Identity Protection - - An Identity exchange is optional within the EAP conversation. - Therefore, it is possible to omit the Identity exchange entirely, or - to use a method-specific identity exchange once a protected channel - has been established. - - However, where roaming is supported as described in [RFC2607], it may - be necessary to locate the appropriate backend authentication server - before the authentication conversation can proceed. The realm - portion of the Network Access Identifier (NAI) [RFC2486] is typically - - - -Aboba, et al. Standards Track [Page 46] - -RFC 3748 EAP June 2004 - - - included within the EAP-Response/Identity in order to enable the - authentication exchange to be routed to the appropriate backend - authentication server. Therefore, while the peer-name portion of the - NAI may be omitted in the EAP-Response/Identity where proxies or - relays are present, the realm portion may be required. - - It is possible for the identity in the identity response to be - different from the identity authenticated by the EAP method. This - may be intentional in the case of identity privacy. An EAP method - SHOULD use the authenticated identity when making access control - decisions. - -7.4. Man-in-the-Middle Attacks - - Where EAP is tunneled within another protocol that omits peer - authentication, there exists a potential vulnerability to a man-in- - the-middle attack. For details, see [BINDING] and [MITM]. - - As noted in Section 2.1, EAP does not permit untunneled sequences of - authentication methods. Were a sequence of EAP authentication - methods to be permitted, the peer might not have proof that a single - entity has acted as the authenticator for all EAP methods within the - sequence. For example, an authenticator might terminate one EAP - method, then forward the next method in the sequence to another party - without the peer's knowledge or consent. Similarly, the - authenticator might not have proof that a single entity has acted as - the peer for all EAP methods within the sequence. - - Tunneling EAP within another protocol enables an attack by a rogue - EAP authenticator tunneling EAP to a legitimate server. Where the - tunneling protocol is used for key establishment but does not require - peer authentication, an attacker convincing a legitimate peer to - connect to it will be able to tunnel EAP packets to a legitimate - server, successfully authenticating and obtaining the key. This - allows the attacker to successfully establish itself as a man-in- - the-middle, gaining access to the network, as well as the ability to - decrypt data traffic between the legitimate peer and server. - - This attack may be mitigated by the following measures: - - [a] Requiring mutual authentication within EAP tunneling mechanisms. - - [b] Requiring cryptographic binding between the EAP tunneling - protocol and the tunneled EAP methods. Where cryptographic - binding is supported, a mechanism is also needed to protect - against downgrade attacks that would bypass it. For further - details on cryptographic binding, see [BINDING]. - - - - -Aboba, et al. Standards Track [Page 47] - -RFC 3748 EAP June 2004 - - - [c] Limiting the EAP methods authorized for use without protection, - based on peer and authenticator policy. - - [d] Avoiding the use of tunnels when a single, strong method is - available. - -7.5. Packet Modification Attacks - - While EAP methods may support per-packet data origin authentication, - integrity, and replay protection, support is not provided within the - EAP layer. - - Since the Identifier is only a single octet, it is easy to guess, - allowing an attacker to successfully inject or replay EAP packets. - An attacker may also modify EAP headers (Code, Identifier, Length, - Type) within EAP packets where the header is unprotected. This could - cause packets to be inappropriately discarded or misinterpreted. - - To protect EAP packets against modification, spoofing, or replay, - methods supporting protected ciphersuite negotiation, mutual - authentication, and key derivation, as well as integrity and replay - protection, are recommended. See Section 7.2.1 for definitions of - these security claims. - - Method-specific MICs may be used to provide protection. If a per- - packet MIC is employed within an EAP method, then peers, - authentication servers, and authenticators not operating in pass- - through mode MUST validate the MIC. MIC validation failures SHOULD - be logged. Whether a MIC validation failure is considered a fatal - error or not is determined by the EAP method specification. - - It is RECOMMENDED that methods providing integrity protection of EAP - packets include coverage of all the EAP header fields, including the - Code, Identifier, Length, Type, and Type-Data fields. - - Since EAP messages of Types Identity, Notification, and Nak do not - include their own MIC, it may be desirable for the EAP method MIC to - cover information contained within these messages, as well as the - header of each EAP message. - - To provide protection, EAP also may be encapsulated within a - protected channel created by protocols such as ISAKMP [RFC2408], as - is done in [IKEv2] or within TLS [RFC2246]. However, as noted in - Section 7.4, EAP tunneling may result in a man-in-the-middle - vulnerability. - - - - - - -Aboba, et al. Standards Track [Page 48] - -RFC 3748 EAP June 2004 - - - Existing EAP methods define message integrity checks (MICs) that - cover more than one EAP packet. For example, EAP-TLS [RFC2716] - defines a MIC over a TLS record that could be split into multiple - fragments; within the FINISHED message, the MIC is computed over - previous messages. Where the MIC covers more than one EAP packet, a - MIC validation failure is typically considered a fatal error. - - Within EAP-TLS [RFC2716], a MIC validation failure is treated as a - fatal error, since that is what is specified in TLS [RFC2246]. - However, it is also possible to develop EAP methods that support - per-packet MICs, and respond to verification failures by silently - discarding the offending packet. - - In this document, descriptions of EAP message handling assume that - per-packet MIC validation, where it occurs, is effectively performed - as though it occurs before sending any responses or changing the - state of the host which received the packet. - -7.6. Dictionary Attacks - - Password authentication algorithms such as EAP-MD5, MS-CHAPv1 - [RFC2433], and Kerberos V [RFC1510] are known to be vulnerable to - dictionary attacks. MS-CHAPv1 vulnerabilities are documented in - [PPTPv1]; MS-CHAPv2 vulnerabilities are documented in [PPTPv2]; - Kerberos vulnerabilities are described in [KRBATTACK], [KRBLIM], and - [KERB4WEAK]. - - In order to protect against dictionary attacks, authentication - methods resistant to dictionary attacks (as defined in Section 7.2.1) - are recommended. - - If an authentication algorithm is used that is known to be vulnerable - to dictionary attacks, then the conversation may be tunneled within a - protected channel in order to provide additional protection. - However, as noted in Section 7.4, EAP tunneling may result in a man- - in-the-middle vulnerability, and therefore dictionary attack - resistant methods are preferred. - -7.7. Connection to an Untrusted Network - - With EAP methods supporting one-way authentication, such as EAP-MD5, - the peer does not authenticate the authenticator, making the peer - vulnerable to attack by a rogue authenticator. Methods supporting - mutual authentication (as defined in Section 7.2.1) address this - vulnerability. - - In EAP there is no requirement that authentication be full duplex or - that the same protocol be used in both directions. It is perfectly - - - -Aboba, et al. Standards Track [Page 49] - -RFC 3748 EAP June 2004 - - - acceptable for different protocols to be used in each direction. - This will, of course, depend on the specific protocols negotiated. - However, in general, completing a single unitary mutual - authentication is preferable to two one-way authentications, one in - each direction. This is because separate authentications that are - not bound cryptographically so as to demonstrate they are part of the - same session are subject to man-in-the-middle attacks, as discussed - in Section 7.4. - -7.8. Negotiation Attacks - - In a negotiation attack, the attacker attempts to convince the peer - and authenticator to negotiate a less secure EAP method. EAP does - not provide protection for Nak Response packets, although it is - possible for a method to include coverage of Nak Responses within a - method-specific MIC. - - Within or associated with each authenticator, it is not anticipated - that a particular named peer will support a choice of methods. This - would make the peer vulnerable to attacks that negotiate the least - secure method from among a set. Instead, for each named peer, there - SHOULD be an indication of exactly one method used to authenticate - that peer name. If a peer needs to make use of different - authentication methods under different circumstances, then distinct - identities SHOULD be employed, each of which identifies exactly one - authentication method. - -7.9. Implementation Idiosyncrasies - - The interaction of EAP with lower layers such as PPP and IEEE 802 are - highly implementation dependent. - - For example, upon failure of authentication, some PPP implementations - do not terminate the link, instead limiting traffic in Network-Layer - Protocols to a filtered subset, which in turn allows the peer the - opportunity to update secrets or send mail to the network - administrator indicating a problem. Similarly, while an - authentication failure will result in denied access to the controlled - port in [IEEE-802.1X], limited traffic may be permitted on the - uncontrolled port. - - In EAP there is no provision for retries of failed authentication. - However, in PPP the LCP state machine can renegotiate the - authentication protocol at any time, thus allowing a new attempt. - Similarly, in IEEE 802.1X the Supplicant or Authenticator can re- - authenticate at any time. It is recommended that any counters used - for authentication failure not be reset until after successful - authentication, or subsequent termination of the failed link. - - - -Aboba, et al. Standards Track [Page 50] - -RFC 3748 EAP June 2004 - - -7.10. Key Derivation - - It is possible for the peer and EAP server to mutually authenticate - and derive keys. In order to provide keying material for use in a - subsequently negotiated ciphersuite, an EAP method supporting key - derivation MUST export a Master Session Key (MSK) of at least 64 - octets, and an Extended Master Session Key (EMSK) of at least 64 - octets. EAP Methods deriving keys MUST provide for mutual - authentication between the EAP peer and the EAP Server. - - The MSK and EMSK MUST NOT be used directly to protect data; however, - they are of sufficient size to enable derivation of a AAA-Key - subsequently used to derive Transient Session Keys (TSKs) for use - with the selected ciphersuite. Each ciphersuite is responsible for - specifying how to derive the TSKs from the AAA-Key. - - The AAA-Key is derived from the keying material exported by the EAP - method (MSK and EMSK). This derivation occurs on the AAA server. In - many existing protocols that use EAP, the AAA-Key and MSK are - equivalent, but more complicated mechanisms are possible (see - [KEYFRAME] for details). - - EAP methods SHOULD ensure the freshness of the MSK and EMSK, even in - cases where one party may not have a high quality random number - generator. A RECOMMENDED method is for each party to provide a nonce - of at least 128 bits, used in the derivation of the MSK and EMSK. - - EAP methods export the MSK and EMSK, but not Transient Session Keys - so as to allow EAP methods to be ciphersuite and media independent. - Keying material exported by EAP methods MUST be independent of the - ciphersuite negotiated to protect data. - - Depending on the lower layer, EAP methods may run before or after - ciphersuite negotiation, so that the selected ciphersuite may not be - known to the EAP method. By providing keying material usable with - any ciphersuite, EAP methods can used with a wide range of - ciphersuites and media. - - In order to preserve algorithm independence, EAP methods deriving - keys SHOULD support (and document) the protected negotiation of the - ciphersuite used to protect the EAP conversation between the peer and - server. This is distinct from the ciphersuite negotiated between the - peer and authenticator, used to protect data. - - The strength of Transient Session Keys (TSKs) used to protect data is - ultimately dependent on the strength of keys generated by the EAP - method. If an EAP method cannot produce keying material of - sufficient strength, then the TSKs may be subject to a brute force - - - -Aboba, et al. Standards Track [Page 51] - -RFC 3748 EAP June 2004 - - - attack. In order to enable deployments requiring strong keys, EAP - methods supporting key derivation SHOULD be capable of generating an - MSK and EMSK, each with an effective key strength of at least 128 - bits. - - Methods supporting key derivation MUST demonstrate cryptographic - separation between the MSK and EMSK branches of the EAP key - hierarchy. Without violating a fundamental cryptographic assumption - (such as the non-invertibility of a one-way function), an attacker - recovering the MSK or EMSK MUST NOT be able to recover the other - quantity with a level of effort less than brute force. - - Non-overlapping substrings of the MSK MUST be cryptographically - separate from each other, as defined in Section 7.2.1. That is, - knowledge of one substring MUST NOT help in recovering some other - substring without breaking some hard cryptographic assumption. This - is required because some existing ciphersuites form TSKs by simply - splitting the AAA-Key to pieces of appropriate length. Likewise, - non-overlapping substrings of the EMSK MUST be cryptographically - separate from each other, and from substrings of the MSK. - - The EMSK is reserved for future use and MUST remain on the EAP peer - and EAP server where it is derived; it MUST NOT be transported to, or - shared with, additional parties, or used to derive any other keys. - (This restriction will be relaxed in a future document that specifies - how the EMSK can be used.) - - Since EAP does not provide for explicit key lifetime negotiation, EAP - peers, authenticators, and authentication servers MUST be prepared - for situations in which one of the parties discards the key state, - which remains valid on another party. - - This specification does not provide detailed guidance on how EAP - methods derive the MSK and EMSK, how the AAA-Key is derived from the - MSK and/or EMSK, or how the TSKs are derived from the AAA-Key. - - The development and validation of key derivation algorithms is - difficult, and as a result, EAP methods SHOULD re-use well - established and analyzed mechanisms for key derivation (such as those - specified in IKE [RFC2409] or TLS [RFC2246]), rather than inventing - new ones. EAP methods SHOULD also utilize well established and - analyzed mechanisms for MSK and EMSK derivation. Further details on - EAP Key Derivation are provided within [KEYFRAME]. - - - - - - - - -Aboba, et al. Standards Track [Page 52] - -RFC 3748 EAP June 2004 - - -7.11. Weak Ciphersuites - - If after the initial EAP authentication, data packets are sent - without per-packet authentication, integrity, and replay protection, - an attacker with access to the media can inject packets, "flip bits" - within existing packets, replay packets, or even hijack the session - completely. Without per-packet confidentiality, it is possible to - snoop data packets. - - To protect against data modification, spoofing, or snooping, it is - recommended that EAP methods supporting mutual authentication and key - derivation (as defined by Section 7.2.1) be used, along with lower - layers providing per-packet confidentiality, authentication, - integrity, and replay protection. - - Additionally, if the lower layer performs ciphersuite negotiation, it - should be understood that EAP does not provide by itself integrity - protection of that negotiation. Therefore, in order to avoid - downgrading attacks which would lead to weaker ciphersuites being - used, clients implementing lower layer ciphersuite negotiation SHOULD - protect against negotiation downgrading. - - This can be done by enabling users to configure which ciphersuites - are acceptable as a matter of security policy, or the ciphersuite - negotiation MAY be authenticated using keying material derived from - the EAP authentication and a MIC algorithm agreed upon in advance by - lower-layer peers. - -7.12. Link Layer - - There are reliability and security issues with link layer indications - in PPP, IEEE 802 LANs, and IEEE 802.11 wireless LANs: - - [a] PPP. In PPP, link layer indications such as LCP-Terminate (a - link failure indication) and NCP (a link success indication) are - not authenticated or integrity protected. They can therefore be - spoofed by an attacker with access to the link. - - [b] IEEE 802. IEEE 802.1X EAPOL-Start and EAPOL-Logoff frames are - not authenticated or integrity protected. They can therefore be - spoofed by an attacker with access to the link. - - [c] IEEE 802.11. In IEEE 802.11, link layer indications include - Disassociate and Deauthenticate frames (link failure - indications), and the first message of the 4-way handshake (link - success indication). These messages are not authenticated or - integrity protected, and although they are not forwardable, they - are spoofable by an attacker within range. - - - -Aboba, et al. Standards Track [Page 53] - -RFC 3748 EAP June 2004 - - - In IEEE 802.11, IEEE 802.1X data frames may be sent as Class 3 - unicast data frames, and are therefore forwardable. This implies - that while EAPOL-Start and EAPOL-Logoff messages may be authenticated - and integrity protected, they can be spoofed by an authenticated - attacker far from the target when "pre-authentication" is enabled. - - In IEEE 802.11, a "link down" indication is an unreliable indication - of link failure, since wireless signal strength can come and go and - may be influenced by radio frequency interference generated by an - attacker. To avoid unnecessary resets, it is advisable to damp these - indications, rather than passing them directly to the EAP. Since EAP - supports retransmission, it is robust against transient connectivity - losses. - -7.13. Separation of Authenticator and Backend Authentication Server - - It is possible for the EAP peer and EAP server to mutually - authenticate and derive a AAA-Key for a ciphersuite used to protect - subsequent data traffic. This does not present an issue on the peer, - since the peer and EAP client reside on the same machine; all that is - required is for the client to derive the AAA-Key from the MSK and - EMSK exported by the EAP method, and to subsequently pass a Transient - Session Key (TSK) to the ciphersuite module. - - However, in the case where the authenticator and authentication - server reside on different machines, there are several implications - for security. - - [a] Authentication will occur between the peer and the authentication - server, not between the peer and the authenticator. This means - that it is not possible for the peer to validate the identity of - the authenticator that it is speaking to, using EAP alone. - - [b] As discussed in [RFC3579], the authenticator is dependent on the - AAA protocol in order to know the outcome of an authentication - conversation, and does not look at the encapsulated EAP packet - (if one is present) to determine the outcome. In practice, this - implies that the AAA protocol spoken between the authenticator - and authentication server MUST support per-packet authentication, - integrity, and replay protection. - - [c] After completion of the EAP conversation, where lower layer - security services such as per-packet confidentiality, - authentication, integrity, and replay protection will be enabled, - a secure association protocol SHOULD be run between the peer and - authenticator in order to provide mutual authentication between - - - - - -Aboba, et al. Standards Track [Page 54] - -RFC 3748 EAP June 2004 - - - the peer and authenticator, guarantee liveness of transient - session keys, provide protected ciphersuite and capabilities - negotiation for subsequent data, and synchronize key usage. - - [d] A AAA-Key derived from the MSK and/or EMSK negotiated between the - peer and authentication server MAY be transmitted to the - authenticator. Therefore, a mechanism needs to be provided to - transmit the AAA-Key from the authentication server to the - authenticator that needs it. The specification of the AAA-key - derivation, transport, and wrapping mechanisms is outside the - scope of this document. Further details on AAA-Key Derivation - are provided within [KEYFRAME]. - -7.14. Cleartext Passwords - - This specification does not define a mechanism for cleartext password - authentication. The omission is intentional. Use of cleartext - passwords would allow the password to be captured by an attacker with - access to a link over which EAP packets are transmitted. - - Since protocols encapsulating EAP, such as RADIUS [RFC3579], may not - provide confidentiality, EAP packets may be subsequently encapsulated - for transport over the Internet where they may be captured by an - attacker. - - As a result, cleartext passwords cannot be securely used within EAP, - except where encapsulated within a protected tunnel with server - authentication. Some of the same risks apply to EAP methods without - dictionary attack resistance, as defined in Section 7.2.1. For - details, see Section 7.6. - -7.15. Channel Binding - - It is possible for a compromised or poorly implemented EAP - authenticator to communicate incorrect information to the EAP peer - and/or server. This may enable an authenticator to impersonate - another authenticator or communicate incorrect information via out- - of-band mechanisms (such as via a AAA or lower layer protocol). - - Where EAP is used in pass-through mode, the EAP peer typically does - not verify the identity of the pass-through authenticator, it only - verifies that the pass-through authenticator is trusted by the EAP - server. This creates a potential security vulnerability. - - Section 4.3.7 of [RFC3579] describes how an EAP pass-through - authenticator acting as a AAA client can be detected if it attempts - to impersonate another authenticator (such by sending incorrect NAS- - Identifier [RFC2865], NAS-IP-Address [RFC2865] or NAS-IPv6-Address - - - -Aboba, et al. Standards Track [Page 55] - -RFC 3748 EAP June 2004 - - - [RFC3162] attributes via the AAA protocol). However, it is possible - for a pass-through authenticator acting as a AAA client to provide - correct information to the AAA server while communicating misleading - information to the EAP peer via a lower layer protocol. - - For example, it is possible for a compromised authenticator to - utilize another authenticator's Called-Station-Id or NAS-Identifier - in communicating with the EAP peer via a lower layer protocol, or for - a pass-through authenticator acting as a AAA client to provide an - incorrect peer Calling-Station-Id [RFC2865][RFC3580] to the AAA - server via the AAA protocol. - - In order to address this vulnerability, EAP methods may support a - protected exchange of channel properties such as endpoint - identifiers, including (but not limited to): Called-Station-Id - [RFC2865][RFC3580], Calling-Station-Id [RFC2865][RFC3580], NAS- - Identifier [RFC2865], NAS-IP-Address [RFC2865], and NAS-IPv6-Address - [RFC3162]. - - Using such a protected exchange, it is possible to match the channel - properties provided by the authenticator via out-of-band mechanisms - against those exchanged within the EAP method. Where discrepancies - are found, these SHOULD be logged; additional actions MAY also be - taken, such as denying access. - -7.16. Protected Result Indications - - Within EAP, Success and Failure packets are neither acknowledged nor - integrity protected. Result indications improve resilience to loss - of Success and Failure packets when EAP is run over lower layers - which do not support retransmission or synchronization of the - authentication state. In media such as IEEE 802.11, which provides - for retransmission, as well as synchronization of authentication - state via the 4-way handshake defined in [IEEE-802.11i], additional - resilience is typically of marginal benefit. - - Depending on the method and circumstances, result indications can be - spoofable by an attacker. A method is said to provide protected - result indications if it supports result indications, as well as the - "integrity protection" and "replay protection" claims. A method - supporting protected result indications MUST indicate which result - indications are protected, and which are not. - - Protected result indications are not required to protect against - rogue authenticators. Within a mutually authenticating method, - requiring that the server authenticate to the peer before the peer - will accept a Success packet prevents an attacker from acting as a - rogue authenticator. - - - -Aboba, et al. Standards Track [Page 56] - -RFC 3748 EAP June 2004 - - - However, it is possible for an attacker to forge a Success packet - after the server has authenticated to the peer, but before the peer - has authenticated to the server. If the peer were to accept the - forged Success packet and attempt to access the network when it had - not yet successfully authenticated to the server, a denial of service - attack could be mounted against the peer. After such an attack, if - the lower layer supports failure indications, the authenticator can - synchronize state with the peer by providing a lower layer failure - indication. See Section 7.12 for details. - - If a server were to authenticate the peer and send a Success packet - prior to determining whether the peer has authenticated the - authenticator, an idle timeout can occur if the authenticator is not - authenticated by the peer. Where supported by the lower layer, an - authenticator sensing the absence of the peer can free resources. - - In a method supporting result indications, a peer that has - authenticated the server does not consider the authentication - successful until it receives an indication that the server - successfully authenticated it. Similarly, a server that has - successfully authenticated the peer does not consider the - authentication successful until it receives an indication that the - peer has authenticated the server. - - In order to avoid synchronization problems, prior to sending a - success result indication, it is desirable for the sender to verify - that sufficient authorization exists for granting access, though, as - discussed below, this is not always possible. - - While result indications may enable synchronization of the - authentication result between the peer and server, this does not - guarantee that the peer and authenticator will be synchronized in - terms of their authorization or that timeouts will not occur. For - example, the EAP server may not be aware of an authorization decision - made by a AAA proxy; the AAA server may check authorization only - after authentication has completed successfully, to discover that - authorization cannot be granted, or the AAA server may grant access - but the authenticator may be unable to provide it due to a temporary - lack of resources. In these situations, synchronization may only be - achieved via lower layer result indications. - - Success indications may be explicit or implicit. For example, where - a method supports error messages, an implicit success indication may - be defined as the reception of a specific message without a preceding - error message. Failures are typically indicated explicitly. As - described in Section 4.2, a peer silently discards a Failure packet - received at a point where the method does not explicitly permit this - - - - -Aboba, et al. Standards Track [Page 57] - -RFC 3748 EAP June 2004 - - - to be sent. For example, a method providing its own error messages - might require the peer to receive an error message prior to accepting - a Failure packet. - - Per-packet authentication, integrity, and replay protection of result - indications protects against spoofing. Since protected result - indications require use of a key for per-packet authentication and - integrity protection, methods supporting protected result indications - MUST also support the "key derivation", "mutual authentication", - "integrity protection", and "replay protection" claims. - - Protected result indications address some denial-of-service - vulnerabilities due to spoofing of Success and Failure packets, - though not all. EAP methods can typically provide protected result - indications only in some circumstances. For example, errors can - occur prior to key derivation, and so it may not be possible to - protect all failure indications. It is also possible that result - indications may not be supported in both directions or that - synchronization may not be achieved in all modes of operation. - - For example, within EAP-TLS [RFC2716], in the client authentication - handshake, the server authenticates the peer, but does not receive a - protected indication of whether the peer has authenticated it. In - contrast, the peer authenticates the server and is aware of whether - the server has authenticated it. In the session resumption - handshake, the peer authenticates the server, but does not receive a - protected indication of whether the server has authenticated it. In - this mode, the server authenticates the peer and is aware of whether - the peer has authenticated it. - -8. Acknowledgements - - This protocol derives much of its inspiration from Dave Carrel's AHA - document, as well as the PPP CHAP protocol [RFC1994]. Valuable - feedback was provided by Yoshihiro Ohba of Toshiba America Research, - Jari Arkko of Ericsson, Sachin Seth of Microsoft, Glen Zorn of Cisco - Systems, Jesse Walker of Intel, Bill Arbaugh, Nick Petroni and Bryan - Payne of the University of Maryland, Steve Bellovin of AT&T Research, - Paul Funk of Funk Software, Pasi Eronen of Nokia, Joseph Salowey of - Cisco, Paul Congdon of HP, and members of the EAP working group. - - The use of Security Claims sections for EAP methods, as required by - Section 7.2 and specified for each EAP method described in this - document, was inspired by Glen Zorn through [EAP-EVAL]. - - - - - - - -Aboba, et al. Standards Track [Page 58] - -RFC 3748 EAP June 2004 - - -9. References - -9.1. Normative References - - [RFC1661] Simpson, W., "The Point-to-Point Protocol (PPP)", - STD 51, RFC 1661, July 1994. - - [RFC1994] Simpson, W., "PPP Challenge Handshake - Authentication Protocol (CHAP)", RFC 1994, August - 1996. - - [RFC2119] Bradner, S., "Key words for use in RFCs to - Indicate Requirement Levels", BCP 14, RFC 2119, - March 1997. - - [RFC2243] Metz, C., "OTP Extended Responses", RFC 2243, - November 1997. - - [RFC2279] Yergeau, F., "UTF-8, a transformation format of - ISO 10646", RFC 2279, January 1998. - - [RFC2289] Haller, N., Metz, C., Nesser, P. and M. Straw, "A - One-Time Password System", RFC 2289, February - 1998. - - [RFC2434] Narten, T. and H. Alvestrand, "Guidelines for - Writing an IANA Considerations Section in RFCs", - BCP 26, RFC 2434, October 1998. - - [RFC2988] Paxson, V. and M. Allman, "Computing TCP's - Retransmission Timer", RFC 2988, November 2000. - - [IEEE-802] Institute of Electrical and Electronics Engineers, - "Local and Metropolitan Area Networks: Overview - and Architecture", IEEE Standard 802, 1990. - - [IEEE-802.1X] Institute of Electrical and Electronics Engineers, - "Local and Metropolitan Area Networks: Port-Based - Network Access Control", IEEE Standard 802.1X, - September 2001. - - - - - - - - - - - -Aboba, et al. Standards Track [Page 59] - -RFC 3748 EAP June 2004 - - -9.2. Informative References - - [RFC793] Postel, J., "Transmission Control Protocol", STD - 7, RFC 793, September 1981. - - [RFC1510] Kohl, J. and B. Neuman, "The Kerberos Network - Authentication Service (V5)", RFC 1510, September - 1993. - - [RFC1750] Eastlake, D., Crocker, S. and J. Schiller, - "Randomness Recommendations for Security", RFC - 1750, December 1994. - - [RFC2246] Dierks, T., Allen, C., Treese, W., Karlton, P., - Freier, A. and P. Kocher, "The TLS Protocol - Version 1.0", RFC 2246, January 1999. - - [RFC2284] Blunk, L. and J. Vollbrecht, "PPP Extensible - Authentication Protocol (EAP)", RFC 2284, March - 1998. - - [RFC2486] Aboba, B. and M. Beadles, "The Network Access - Identifier", RFC 2486, January 1999. - - [RFC2408] Maughan, D., Schneider, M. and M. Schertler, - "Internet Security Association and Key Management - Protocol (ISAKMP)", RFC 2408, November 1998. - - [RFC2409] Harkins, D. and D. Carrel, "The Internet Key - Exchange (IKE)", RFC 2409, November 1998. - - [RFC2433] Zorn, G. and S. Cobb, "Microsoft PPP CHAP - Extensions", RFC 2433, October 1998. - - [RFC2607] Aboba, B. and J. Vollbrecht, "Proxy Chaining and - Policy Implementation in Roaming", RFC 2607, June - 1999. - - [RFC2661] Townsley, W., Valencia, A., Rubens, A., Pall, G., - Zorn, G. and B. Palter, "Layer Two Tunneling - Protocol "L2TP"", RFC 2661, August 1999. - - [RFC2716] Aboba, B. and D. Simon, "PPP EAP TLS - Authentication Protocol", RFC 2716, October 1999. - - [RFC2865] Rigney, C., Willens, S., Rubens, A. and W. - Simpson, "Remote Authentication Dial In User - Service (RADIUS)", RFC 2865, June 2000. - - - -Aboba, et al. Standards Track [Page 60] - -RFC 3748 EAP June 2004 - - - [RFC2960] Stewart, R., Xie, Q., Morneault, K., Sharp, C., - Schwarzbauer, H., Taylor, T., Rytina, I., Kalla, - M., Zhang, L. and V. Paxson, "Stream Control - Transmission Protocol", RFC 2960, October 2000. - - [RFC3162] Aboba, B., Zorn, G. and D. Mitton, "RADIUS and - IPv6", RFC 3162, August 2001. - - [RFC3454] Hoffman, P. and M. Blanchet, "Preparation of - Internationalized Strings ("stringprep")", RFC - 3454, December 2002. - - [RFC3579] Aboba, B. and P. Calhoun, "RADIUS (Remote - Authentication Dial In User Service) Support For - Extensible Authentication Protocol (EAP)", RFC - 3579, September 2003. - - [RFC3580] Congdon, P., Aboba, B., Smith, A., Zorn, G. and J. - Roese, "IEEE 802.1X Remote Authentication Dial In - User Service (RADIUS) Usage Guidelines", RFC 3580, - September 2003. - - [RFC3692] Narten, T., "Assigning Experimental and Testing - Numbers Considered Useful", BCP 82, RFC 3692, - January 2004. - - [DECEPTION] Slatalla, M. and J. Quittner, "Masters of - Deception", Harper-Collins, New York, 1995. - - [KRBATTACK] Wu, T., "A Real-World Analysis of Kerberos - Password Security", Proceedings of the 1999 ISOC - Network and Distributed System Security Symposium, - http://www.isoc.org/isoc/conferences/ndss/99/ - proceedings/papers/wu.pdf. - - [KRBLIM] Bellovin, S. and M. Merrit, "Limitations of the - Kerberos authentication system", Proceedings of - the 1991 Winter USENIX Conference, pp. 253-267, - 1991. - - [KERB4WEAK] Dole, B., Lodin, S. and E. Spafford, "Misplaced - trust: Kerberos 4 session keys", Proceedings of - the Internet Society Network and Distributed - System Security Symposium, pp. 60-70, March 1997. - - - - - - - -Aboba, et al. Standards Track [Page 61] - -RFC 3748 EAP June 2004 - - - [PIC] Aboba, B., Krawczyk, H. and Y. Sheffer, "PIC, A - Pre-IKE Credential Provisioning Protocol", Work in - Progress, October 2002. - - [IKEv2] Kaufman, C., "Internet Key Exchange (IKEv2) - Protocol", Work in Progress, January 2004. - - [PPTPv1] Schneier, B. and Mudge, "Cryptanalysis of - Microsoft's Point-to- Point Tunneling Protocol", - Proceedings of the 5th ACM Conference on - Communications and Computer Security, ACM Press, - November 1998. - - [IEEE-802.11] Institute of Electrical and Electronics Engineers, - "Wireless LAN Medium Access Control (MAC) and - Physical Layer (PHY) Specifications", IEEE - Standard 802.11, 1999. - - [SILVERMAN] Silverman, Robert D., "A Cost-Based Security - Analysis of Symmetric and Asymmetric Key Lengths", - RSA Laboratories Bulletin 13, April 2000 (Revised - November 2001), - http://www.rsasecurity.com/rsalabs/bulletins/ - bulletin13.html. - - [KEYFRAME] Aboba, B., "EAP Key Management Framework", Work in - Progress, October 2003. - - [SASLPREP] Zeilenga, K., "SASLprep: Stringprep profile for - user names and passwords", Work in Progress, March - 2004. - - [IEEE-802.11i] Institute of Electrical and Electronics Engineers, - "Unapproved Draft Supplement to Standard for - Telecommunications and Information Exchange - Between Systems - LAN/MAN Specific Requirements - - Part 11: Wireless LAN Medium Access Control (MAC) - and Physical Layer (PHY) Specifications: - Specification for Enhanced Security", IEEE Draft - 802.11i (work in progress), 2003. - - [DIAM-EAP] Eronen, P., Hiller, T. and G. Zorn, "Diameter - Extensible Authentication Protocol (EAP) - Application", Work in Progress, February 2004. - - [EAP-EVAL] Zorn, G., "Specifying Security Claims for EAP - Authentication Types", Work in Progress, October - 2002. - - - -Aboba, et al. Standards Track [Page 62] - -RFC 3748 EAP June 2004 - - - [BINDING] Puthenkulam, J., "The Compound Authentication - Binding Problem", Work in Progress, October 2003. - - [MITM] Asokan, N., Niemi, V. and K. Nyberg, "Man-in-the- - Middle in Tunneled Authentication Protocols", IACR - ePrint Archive Report 2002/163, October 2002, - <http://eprint.iacr.org/2002/163>. - - [IEEE-802.11i-req] Stanley, D., "EAP Method Requirements for Wireless - LANs", Work in Progress, February 2004. - - [PPTPv2] Schneier, B. and Mudge, "Cryptanalysis of - Microsoft's PPTP Authentication Extensions (MS- - CHAPv2)", CQRE 99, Springer-Verlag, 1999, pp. - 192-203. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Aboba, et al. Standards Track [Page 63] - -RFC 3748 EAP June 2004 - - -Appendix A. Changes from RFC 2284 - - This section lists the major changes between [RFC2284] and this - document. Minor changes, including style, grammar, spelling, and - editorial changes are not mentioned here. - - o The Terminology section (Section 1.2) has been expanded, defining - more concepts and giving more exact definitions. - - o The concepts of Mutual Authentication, Key Derivation, and Result - Indications are introduced and discussed throughout the document - where appropriate. - - o In Section 2, it is explicitly specified that more than one - exchange of Request and Response packets may occur as part of the - EAP authentication exchange. How this may be used and how it may - not be used is specified in detail in Section 2.1. - - o Also in Section 2, some requirements have been made explicit for - the authenticator when acting in pass-through mode. - - o An EAP multiplexing model (Section 2.2) has been added to - illustrate a typical implementation of EAP. There is no - requirement that an implementation conform to this model, as long - as the on-the-wire behavior is consistent with it. - - o As EAP is now in use with a variety of lower layers, not just PPP - for which it was first designed, Section 3 on lower layer behavior - has been added. - - o In the description of the EAP Request and Response interaction - (Section 4.1), both the behavior on receiving duplicate requests, - and when packets should be silently discarded has been more - exactly specified. The implementation notes in this section have - been substantially expanded. - - o In Section 4.2, it has been clarified that Success and Failure - packets must not contain additional data, and the implementation - note has been expanded. A subsection giving requirements on - processing of success and failure packets has been added. - - o Section 5 on EAP Request/Response Types lists two new Type values: - the Expanded Type (Section 5.7), which is used to expand the Type - value number space, and the Experimental Type. In the Expanded - Type number space, the new Expanded Nak (Section 5.3.2) Type has - been added. Clarifications have been made in the description of - most of the existing Types. Security claims summaries have been - added for authentication methods. - - - -Aboba, et al. Standards Track [Page 64] - -RFC 3748 EAP June 2004 - - - o In Sections 5, 5.1, and 5.2, a requirement has been added such - that fields with displayable messages should contain UTF-8 encoded - ISO 10646 characters. - - o It is now required in Section 5.1 that if the Type-Data field of - an Identity Request contains a NUL-character, only the part before - the null is displayed. RFC 2284 prohibits the null termination of - the Type-Data field of Identity messages. This rule has been - relaxed for Identity Request messages and the Identity Request - Type-Data field may now be null terminated. - - o In Section 5.5, support for OTP Extended Responses [RFC2243] has - been added to EAP OTP. - - o An IANA Considerations section (Section 6) has been added, giving - registration policies for the numbering spaces defined for EAP. - - o The Security Considerations (Section 7) have been greatly - expanded, giving a much more comprehensive coverage of possible - threats and other security considerations. - - o In Section 7.5, text has been added on method-specific behavior, - providing guidance on how EAP method-specific integrity checks - should be processed. Where possible, it is desirable for a - method-specific MIC to be computed over the entire EAP packet, - including the EAP layer header (Code, Identifier, Length) and EAP - method layer header (Type, Type-Data). - - o In Section 7.14 the security risks involved in use of cleartext - passwords with EAP are described. - - o In Section 7.15 text has been added relating to detection of rogue - NAS behavior. - - - - - - - - - - - - - - - - - - -Aboba, et al. Standards Track [Page 65] - -RFC 3748 EAP June 2004 - - -Authors' Addresses - - Bernard Aboba - Microsoft Corporation - One Microsoft Way - Redmond, WA 98052 - USA - - Phone: +1 425 706 6605 - Fax: +1 425 936 6605 - EMail: bernarda@microsoft.com - - Larry J. Blunk - Merit Network, Inc - 4251 Plymouth Rd., Suite 2000 - Ann Arbor, MI 48105-2785 - USA - - Phone: +1 734-647-9563 - Fax: +1 734-647-3185 - EMail: ljb@merit.edu - - John R. Vollbrecht - Vollbrecht Consulting LLC - 9682 Alice Hill Drive - Dexter, MI 48130 - USA - - EMail: jrv@umich.edu - - James Carlson - Sun Microsystems, Inc - 1 Network Drive - Burlington, MA 01803-2757 - USA - - Phone: +1 781 442 2084 - Fax: +1 781 442 1677 - EMail: james.d.carlson@sun.com - - Henrik Levkowetz - ipUnplugged AB - Arenavagen 33 - Stockholm S-121 28 - SWEDEN - - Phone: +46 708 32 16 08 - EMail: henrik@levkowetz.com - - - -Aboba, et al. Standards Track [Page 66] - -RFC 3748 EAP June 2004 - - -Full Copyright Statement - - Copyright (C) The Internet Society (2004). This document is subject - to the rights, licenses and restrictions contained in BCP 78, and - except as set forth therein, the authors retain all their rights. - - This document and the information contained herein are provided on an - "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS - OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET - ENGINEERING TASK FORCE DISCLAIM 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. - -Intellectual Property - - The IETF takes no position regarding the validity or scope of any - Intellectual Property Rights or other rights that might be claimed to - pertain to the implementation or use of the technology described in - this document or the extent to which any license under such rights - might or might not be available; nor does it represent that it has - made any independent effort to identify any such rights. Information - on the procedures with respect to rights in RFC documents can be - found in BCP 78 and BCP 79. - - Copies of IPR disclosures made to the IETF Secretariat and any - assurances of licenses to be made available, or the result of an - attempt made to obtain a general license or permission for the use of - such proprietary rights by implementers or users of this - specification can be obtained from the IETF on-line IPR repository at - http://www.ietf.org/ipr. - - The IETF invites any interested party to bring to its attention any - copyrights, patents or patent applications, or other proprietary - rights that may cover technology that may be required to implement - this standard. Please address the information to the IETF at ietf- - ipr@ietf.org. - -Acknowledgement - - Funding for the RFC Editor function is currently provided by the - Internet Society. - - - - - - - - - -Aboba, et al. Standards Track [Page 67] - diff --git a/src/charon/doc/standards/rfc4186.txt b/src/charon/doc/standards/rfc4186.txt deleted file mode 100644 index e7435a01c..000000000 --- a/src/charon/doc/standards/rfc4186.txt +++ /dev/null @@ -1,5155 +0,0 @@ - - - - - - -Network Working Group H. Haverinen, Ed. -Request for Comments: 4186 Nokia -Category: Informational J. Salowey, Ed. - Cisco Systems - January 2006 - - - Extensible Authentication Protocol Method for - Global System for Mobile Communications (GSM) - Subscriber Identity Modules (EAP-SIM) - -Status of This Memo - - This memo provides information for the Internet community. It does - not specify an Internet standard of any kind. Distribution of this - memo is unlimited. - -Copyright Notice - - Copyright (C) The Internet Society (2006). - -IESG Note - - The EAP-SIM protocol was developed by 3GPP. The documentation of - EAP-SIM is provided as information to the Internet community. While - the EAP WG has verified that EAP-SIM is compatible with EAP, as - defined in RFC 3748, no other review has been done, including - validation of the security claims. The IETF has also not reviewed - the security of the cryptographic algorithms. - -Abstract - - This document specifies an Extensible Authentication Protocol (EAP) - mechanism for authentication and session key distribution using the - Global System for Mobile Communications (GSM) Subscriber Identity - Module (SIM). GSM is a second generation mobile network standard. - The EAP-SIM mechanism specifies enhancements to GSM authentication - and key agreement whereby multiple authentication triplets can be - combined to create authentication responses and session keys of - greater strength than the individual GSM triplets. The mechanism - also includes network authentication, user anonymity support, result - indications, and a fast re-authentication procedure. - - - - - - - - - -Haverinen & Salowey Informational [Page 1] - -RFC 4186 EAP-SIM Authentication January 2006 - - -Table of Contents - - 1. Introduction ....................................................4 - 2. Terms ...........................................................5 - 3. Overview ........................................................8 - 4. Operation ......................................................10 - 4.1. Version Negotiation .......................................10 - 4.2. Identity Management .......................................11 - 4.2.1. Format, Generation and Usage of Peer Identities ....11 - 4.2.2. Communicating the Peer Identity to the Server ......17 - 4.2.3. Choice of Identity for the EAP-Response/Identity ...19 - 4.2.4. Server Operation in the Beginning of - EAP-SIM Exchange ...................................19 - 4.2.5. Processing of EAP-Request/SIM/Start by the Peer ....20 - 4.2.6. Attacks Against Identity Privacy ...................21 - 4.2.7. Processing of AT_IDENTITY by the Server ............22 - 4.3. Message Sequence Examples (Informative) ...................23 - 4.3.1. Full Authentication ................................24 - 4.3.2. Fast Re-authentication .............................25 - 4.3.3. Fall Back to Full Authentication ...................26 - 4.3.4. Requesting the Permanent Identity 1 ................27 - 4.3.5. Requesting the Permanent Identity 2 ................28 - 4.3.6. Three EAP-SIM/Start Roundtrips .....................28 - 5. Fast Re-Authentication .........................................30 - 5.1. General ...................................................30 - 5.2. Comparison to UMTS AKA ....................................31 - 5.3. Fast Re-authentication Identity ...........................31 - 5.4. Fast Re-authentication Procedure ..........................33 - 5.5. Fast Re-authentication Procedure when Counter Is - Too Small .................................................36 - 6. EAP-SIM Notifications ..........................................37 - 6.1. General ...................................................37 - 6.2. Result Indications ........................................39 - 6.3. Error Cases ...............................................40 - 6.3.1. Peer Operation .....................................40 - 6.3.2. Server Operation ...................................41 - 6.3.3. EAP-Failure ........................................42 - 6.3.4. EAP-Success ........................................42 - 7. Key Generation .................................................43 - 8. Message Format and Protocol Extensibility ......................45 - 8.1. Message Format ............................................45 - 8.2. Protocol Extensibility ....................................47 - 9. Messages .......................................................48 - 9.1. EAP-Request/SIM/Start .....................................48 - 9.2. EAP-Response/SIM/Start ....................................49 - 9.3. EAP-Request/SIM/Challenge .................................49 - 9.4. EAP-Response/SIM/Challenge ................................50 - 9.5. EAP-Request/SIM/Re-authentication .........................51 - - - -Haverinen & Salowey Informational [Page 2] - -RFC 4186 EAP-SIM Authentication January 2006 - - - 9.6. EAP-Response/SIM/Re-authentication ........................51 - 9.7. EAP-Response/SIM/Client-Error .............................52 - 9.8. EAP-Request/SIM/Notification ..............................52 - 9.9. EAP-Response/SIM/Notification .............................53 - 10. Attributes ....................................................53 - 10.1. Table of Attributes ......................................53 - 10.2. AT_VERSION_LIST ..........................................54 - 10.3. AT_SELECTED_VERSION ......................................55 - 10.4. AT_NONCE_MT ..............................................55 - 10.5. AT_PERMANENT_ID_REQ ......................................56 - 10.6. AT_ANY_ID_REQ ............................................56 - 10.7. AT_FULLAUTH_ID_REQ .......................................57 - 10.8. AT_IDENTITY ..............................................57 - 10.9. AT_RAND ..................................................58 - 10.10. AT_NEXT_PSEUDONYM .......................................59 - 10.11. AT_NEXT_REAUTH_ID .......................................59 - 10.12. AT_IV, AT_ENCR_DATA, and AT_PADDING .....................60 - 10.13. AT_RESULT_IND ...........................................62 - 10.14. AT_MAC ..................................................62 - 10.15. AT_COUNTER ..............................................63 - 10.16. AT_COUNTER_TOO_SMALL ....................................63 - 10.17. AT_NONCE_S ..............................................64 - 10.18. AT_NOTIFICATION .........................................64 - 10.19. AT_CLIENT_ERROR_CODE ....................................65 - 11. IANA Considerations ...........................................66 - 12. Security Considerations .......................................66 - 12.1. A3 and A8 Algorithms .....................................66 - 12.2. Identity Protection ......................................66 - 12.3. Mutual Authentication and Triplet Exposure ...............67 - 12.4. Flooding the Authentication Centre .......................69 - 12.5. Key Derivation ...........................................69 - 12.6. Cryptographic Separation of Keys and Session - Independence .............................................70 - 12.7. Dictionary Attacks .......................................71 - 12.8. Credentials Re-use .......................................71 - 12.9. Integrity and Replay Protection, and Confidentiality .....72 - 12.10. Negotiation Attacks .....................................73 - 12.11. Protected Result Indications ............................73 - 12.12. Man-in-the-Middle Attacks ...............................74 - 12.13. Generating Random Numbers ...............................74 - 13. Security Claims ...............................................74 - 14. Acknowledgements and Contributions ............................75 - 14.1. Contributors .............................................75 - 14.2. Acknowledgements .........................................75 - 14.2.1. Contributors' Addresses ...........................77 - 15. References ....................................................78 - 15.1. Normative References .....................................78 - 15.2. Informative References ...................................79 - - - -Haverinen & Salowey Informational [Page 3] - -RFC 4186 EAP-SIM Authentication January 2006 - - - Appendix A. Test Vectors .........................................81 - A.1. EAP-Request/Identity .....................................81 - A.2. EAP-Response/Identity ....................................81 - A.3. EAP-Request/SIM/Start ....................................82 - A.4. EAP-Response/SIM/Start ...................................82 - A.5. EAP-Request/SIM/Challenge ................................83 - A.6. EAP-Response/SIM/Challenge ...............................86 - A.7. EAP-Success ..............................................86 - A.8. Fast Re-authentication ...................................86 - A.9. EAP-Request/SIM/Re-authentication ........................87 - A.10. EAP-Response/SIM/Re-authentication ......................89 - Appendix B. Pseudo-Random Number Generator .......................90 - -1. Introduction - - This document specifies an Extensible Authentication Protocol (EAP) - [RFC3748] mechanism for authentication and session key distribution - using the Global System for Mobile Communications (GSM) Subscriber - Identity Module (SIM). - - GSM is a second generation mobile network standard. Second - generation mobile networks and third generation mobile networks use - different authentication and key agreement mechanisms. EAP-AKA - [EAP-AKA] specifies an EAP method that is based on the Authentication - and Key Agreement (AKA) mechanism used in 3rd generation mobile - networks. - - GSM authentication is based on a challenge-response mechanism. The - A3/A8 authentication and key derivation algorithms that run on the - SIM can be given a 128-bit random number (RAND) as a challenge. The - SIM runs operator-specific algorithms, which take the RAND and a - secret key Ki (stored on the SIM) as input, and produce a 32-bit - response (SRES) and a 64-bit long key Kc as output. The Kc key is - originally intended to be used as an encryption key over the air - interface, but in this protocol, it is used for deriving keying - material and is not directly used. Hence, the secrecy of Kc is - critical to the security of this protocol. For more information - about GSM authentication, see [GSM-03.20]. See Section 12.1 for more - discussion about the GSM algorithms used in EAP-SIM. - - The lack of mutual authentication is a weakness in GSM - authentication. The derived 64-bit cipher key (Kc) is not strong - enough for data networks in which stronger and longer keys are - required. Hence, in EAP-SIM, several RAND challenges are used for - generating several 64-bit Kc keys, which are combined to constitute - stronger keying material. In EAP-SIM, the client issues a random - number NONCE_MT to the network in order to contribute to key - derivation, and to prevent replays of EAP-SIM requests from previous - - - -Haverinen & Salowey Informational [Page 4] - -RFC 4186 EAP-SIM Authentication January 2006 - - - exchanges. The NONCE_MT can be conceived as the client's challenge - to the network. EAP-SIM also extends the combined RAND challenges - and other messages with a message authentication code in order to - provide message integrity protection along with mutual - authentication. - - EAP-SIM specifies optional support for protecting the privacy of - subscriber identity using the same concept as the GSM, which uses - pseudonyms/temporary identifiers. It also specifies an optional fast - re-authentication procedure. - - The security of EAP-SIM builds on underlying GSM mechanisms. The - security properties of EAP-SIM are documented in Section 11 of this - document. Implementers and users of EAP-SIM are advised to carefully - study the security considerations in Section 11 in order to determine - whether the security properties are sufficient for the environment in - question, especially as the secrecy of Kc keys is essential to the - security of EAP-SIM. In brief, EAP-SIM is in no sense weaker than - the GSM mechanisms. In some cases EAP-SIM provides better security - properties than the underlying GSM mechanisms, particularly if the - SIM credentials are only used for EAP-SIM and are not re-used from - GSM/GPRS. Many of the security features of EAP-SIM rely upon the - secrecy of the Kc values in the SIM triplets, so protecting these - values is key to the security of the EAP-SIM protocol. - - The 3rd Generation Partnership Project (3GPP) has specified an - enhanced Authentication and Key Agreement (AKA) architecture for the - Universal Mobile Telecommunications System (UMTS). The 3rd - generation AKA mechanism includes mutual authentication, replay - protection, and derivation of longer session keys. EAP-AKA [EAP-AKA] - specifies an EAP method that is based on the 3rd generation AKA. - EAP-AKA, which is a more secure protocol, may be used instead of - EAP-SIM, if 3rd generation identity modules and 3G network - infrastructures are available. - -2. Terms - - 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]. - - The terms and abbreviations "authenticator", "backend authentication - server", "EAP server", "peer", "Silently Discard", "Master Session - Key (MSK)", and "Extended Master Session Key (EMSK)" in this document - are to be interpreted as described in [RFC3748]. - - - - - - -Haverinen & Salowey Informational [Page 5] - -RFC 4186 EAP-SIM Authentication January 2006 - - - This document frequently uses the following terms and abbreviations: - - AAA protocol - - Authentication, Authorization, and Accounting protocol - - AuC - - Authentication Centre. The GSM network element that provides - the authentication triplets for authenticating - the subscriber. - - Authentication vector - - GSM triplets can be alternatively called authentication - vectors. - - EAP - - Extensible Authentication Protocol - - Fast re-authentication - - An EAP-SIM authentication exchange that is based on keys - derived upon a preceding full authentication exchange. - The GSM authentication and key exchange algorithms are not - used in the fast re-authentication procedure. - - Fast Re-authentication Identity - - A fast re-authentication identity of the peer, including an NAI - realm portion in environments where a realm is used. Used on - fast re-authentication only. - - Fast Re-authentication Username - - The username portion of fast re-authentication identity, - i.e., not including any realm portions. - - Full authentication - - An EAP-SIM authentication exchange based on the GSM - authentication and key agreement algorithms. - - GSM - - Global System for Mobile communications. - - - - -Haverinen & Salowey Informational [Page 6] - -RFC 4186 EAP-SIM Authentication January 2006 - - - GSM Triplet - - The tuple formed by the three GSM authentication values RAND, - Kc, and SRES. - - IMSI - - International Mobile Subscriber Identifier, used in GSM to - identify subscribers. - - MAC - - Message Authentication Code - - NAI - - Network Access Identifier - - Nonce - - A value that is used at most once or that is never repeated - within the same cryptographic context. In general, a nonce can - be predictable (e.g., a counter) or unpredictable (e.g., a - random value). Since some cryptographic properties may depend - on the randomness of the nonce, attention should be paid to - whether a nonce is required to be random or not. In this - document, the term nonce is only used to denote random nonces, - and it is not used to denote counters. - - Permanent Identity - - The permanent identity of the peer, including an NAI realm - portion in environments where a realm is used. The permanent - identity is usually based on the IMSI. Used on full - authentication only. - - Permanent Username - - The username portion of permanent identity, i.e., not including - any realm portions. - - Pseudonym Identity - - A pseudonym identity of the peer, including an NAI realm - portion in environments where a realm is used. Used on - full authentication only. - - - - - -Haverinen & Salowey Informational [Page 7] - -RFC 4186 EAP-SIM Authentication January 2006 - - - Pseudonym Username - - The username portion of pseudonym identity, i.e., not including - any realm portions. - - SIM - - Subscriber Identity Module. The SIM is traditionally a smart - card distributed by a GSM operator. - -3. Overview - - Figure 1 shows an overview of the EAP-SIM full authentication - procedure, wherein optional protected success indications are not - used. The authenticator typically communicates with an EAP server - that is located on a backend authentication server using an AAA - protocol. The authenticator shown in the figure is often simply - relaying EAP messages to and from the EAP server, but these backend - AAA communications are not shown. - - Peer Authenticator - | EAP-Request/Identity | - |<---------------------------------------------------------| - | | - | EAP-Response/Identity | - |--------------------------------------------------------->| - | | - | EAP-Request/SIM/Start (AT_VERSION_LIST) | - |<---------------------------------------------------------| - | | - | EAP-Response/SIM/Start (AT_NONCE_MT, AT_SELECTED_VERSION)| - |--------------------------------------------------------->| - | | - | EAP-Request/SIM/Challenge (AT_RAND, AT_MAC) | - |<---------------------------------------------------------| - +-------------------------------------+ | - | Peer runs GSM algorithms, verifies | | - | AT_MAC and derives session keys | | - +-------------------------------------+ | - | EAP-Response/SIM/Challenge (AT_MAC) | - |--------------------------------------------------------->| - | | - | EAP-Success | - |<---------------------------------------------------------| - | | - - Figure 1: EAP-SIM full authentication procedure - - - - -Haverinen & Salowey Informational [Page 8] - -RFC 4186 EAP-SIM Authentication January 2006 - - - The first EAP Request issued by the authenticator is - EAP-Request/Identity. On full authentication, the peer's response - includes either the user's International Mobile Subscriber Identity - (IMSI) or a temporary identity (pseudonym) if identity privacy is in - effect, as specified in Section 4.2. - - Following the peer's EAP-Response/Identity packet, the peer receives - EAP Requests of Type 18 (SIM) from the EAP server and sends the - corresponding EAP Responses. The EAP packets that are of the Type - SIM also have a Subtype field. On full authentication, the first - EAP-Request/SIM packet is of the Subtype 10 (Start). EAP-SIM packets - encapsulate parameters in attributes, encoded in a Type, Length, - Value format. The packet format and the use of attributes are - specified in Section 8. - - The EAP-Request/SIM/Start packet contains the list of EAP-SIM - versions supported by the EAP server in the AT_VERSION_LIST - attribute. This packet may also include attributes for requesting - the subscriber identity, as specified in Section 4.2. - - The peer responds to a EAP-Request/SIM/Start with the - EAP-Response/SIM/Start packet, which includes the AT_NONCE_MT - attribute that contains a random number NONCE_MT, chosen by the peer, - and the AT_SELECTED_VERSION attribute that contains the version - number selected by the peer. The version negotiation is protected by - including the version list and the selected version in the - calculation of keying material (Section 7). - - After receiving the EAP Response/SIM/Start, the EAP server obtains n - GSM triplets for use in authenticating the subscriber, where n = 2 or - n = 3. From the triplets, the EAP server derives the keying - material, as specified in Section 7. The triplets may be obtained by - contacting an Authentication Centre (AuC) on the GSM network; per GSM - specifications, between 1 and 5 triplets may be obtained at a time. - Triplets may be stored in the EAP server for use at a later time, but - triplets MUST NOT be re-used, except in some error cases that are - specified in Section 10.9. - - The next EAP Request the EAP Server issues is of the type SIM and - subtype Challenge (11). It contains the RAND challenges and a - message authentication code attribute AT_MAC to cover the challenges. - The AT_MAC attribute is a general message authentication code - attribute that is used in many EAP-SIM messages. - - On receipt of the EAP-Request/SIM/Challenge message, the peer runs - the GSM authentication algorithm and calculates a copy of the message - authentication code. The peer then verifies that the calculated MAC - equals the received MAC. If the MAC's do not match, then the peer - - - -Haverinen & Salowey Informational [Page 9] - -RFC 4186 EAP-SIM Authentication January 2006 - - - sends the EAP-Response/SIM/Client-Error packet and the authentication - exchange terminates. - - Since the RANDs given to a peer are accompanied by the message - authentication code AT_MAC, and since the peer's NONCE_MT value - contributes to AT_MAC, the peer is able to verify that the EAP-SIM - message is fresh (i.e., not a replay) and that the sender possesses - valid GSM triplets for the subscriber. - - If all checks out, the peer responds with the - EAP-Response/SIM/Challenge, containing the AT_MAC attribute that - covers the peer's SRES response values (Section 9.4). The EAP server - verifies that the MAC is correct. Because protected success - indications are not used in this example, the EAP server sends the - EAP-Success packet, indicating that the authentication was - successful. (Protected success indications are discussed in - Section 6.2.) The EAP server may also include derived keying - material in the message it sends to the authenticator. The peer has - derived the same keying material, so the authenticator does not - forward the keying material to the peer along with EAP-Success. - - EAP-SIM also includes a separate fast re-authentication procedure - that does not make use of the A3/A8 algorithms or the GSM - infrastructure. Fast re-authentication is based on keys derived on - full authentication. If the peer has maintained state information - for fast re-authentication and wants to use fast re-authentication, - then the peer indicates this by using a specific fast - re-authentication identity instead of the permanent identity or a - pseudonym identity. The fast re-authentication procedure is - described in Section 5. - -4. Operation - -4.1. Version Negotiation - - EAP-SIM includes version negotiation so as to allow future - developments in the protocol. The version negotiation is performed - on full authentication and it uses two attributes, AT_VERSION_LIST, - which the server always includes in EAP-Request/SIM/Start, and - AT_SELECTED_VERSION, which the peer includes in - EAP-Response/SIM/Start on full authentication. - - AT_VERSION_LIST includes the EAP-SIM versions supported by the - server. If AT_VERSION_LIST does not include a version that is - implemented by the peer and allowed in the peer's security policy, - then the peer MUST send the EAP-Response/SIM/Client-Error packet - (Section 9.7) to the server with the error code "unsupported - version". If a suitable version is included, then the peer includes - - - -Haverinen & Salowey Informational [Page 10] - -RFC 4186 EAP-SIM Authentication January 2006 - - - the AT_SELECTED_VERSION attribute, containing the selected version in - the EAP-Response/SIM/Start packet. The peer MUST only indicate a - version that is included in the AT_VERSION_LIST. If several versions - are acceptable, then the peer SHOULD choose the version that occurs - first in the version list. - - The version number list of AT_VERSION_LIST and the selected version - of AT_SELECTED_VERSION are included in the key derivation procedure - (Section 7). If an attacker modifies either one of these attributes, - then the peer and the server derive different keying material. - Because K_aut keys are different, the server and peer calculate - different AT_MAC values. Hence, the peer detects that AT_MAC, - included in EAP-Request/SIM/Challenge, is incorrect and sends the - EAP-Response/SIM/Client-Error packet. The authentication procedure - terminates. - -4.2. Identity Management - -4.2.1. Format, Generation and Usage of Peer Identities - -4.2.1.1. General - - In the beginning of EAP authentication, the Authenticator or the EAP - server usually issues the EAP-Request/Identity packet to the peer. - The peer responds with the EAP-Response/Identity, which contains the - user's identity. The formats of these packets are specified in - [RFC3748]. - - GSM subscribers are identified with the International Mobile - Subscriber Identity (IMSI) [GSM-03.03]. The IMSI is a string of not - more than 15 digits. It is composed of a three digit Mobile Country - Code (MCC), a two or three digit Mobile Network Code (MNC), and a - Mobile Subscriber Identification Number (MSIN) of no more than 10 - digits. MCC and MNC uniquely identify the GSM operator and help - identify the AuC from which the authentication vectors need to be - retrieved for this subscriber. - - Internet AAA protocols identify users with the Network Access - Identifier (NAI) [RFC4282]. When used in a roaming environment, the - NAI is composed of a username and a realm, separated with "@" - (username@realm). The username portion identifies the subscriber - within the realm. - - This section specifies the peer identity format used in EAP-SIM. In - this document, the term "identity" or "peer identity" refers to the - whole identity string that is used to identify the peer. The peer - - - - - -Haverinen & Salowey Informational [Page 11] - -RFC 4186 EAP-SIM Authentication January 2006 - - - identity may include a realm portion. "Username" refers to the - portion of the peer identity that identifies the user, i.e., the - username does not include the realm portion. - -4.2.1.2. Identity Privacy Support - - EAP-SIM includes optional identity privacy (anonymity) support that - can be used to hide the cleartext permanent identity and thereby make - the subscriber's EAP exchanges untraceable to eavesdroppers. Because - the permanent identity never changes, revealing it would help - observers to track the user. The permanent identity is usually based - on the IMSI, which may further help the tracking, because the same - identifier may be used in other contexts as well. Identity privacy - is based on temporary identities, or pseudonyms, which are equivalent - to but separate from the Temporary Mobile Subscriber Identities - (TMSI) that are used on cellular networks. Please see Section 12.2 - for security considerations regarding identity privacy. - -4.2.1.3. Username Types in EAP-SIM identities - - There are three types of usernames in EAP-SIM peer identities: - - (1) Permanent usernames. For example, - 1123456789098765@myoperator.com might be a valid permanent identity. - In this example, 1123456789098765 is the permanent username. - - (2) Pseudonym usernames. For example, 3s7ah6n9q@myoperator.com might - be a valid pseudonym identity. In this example, 3s7ah6n9q is the - pseudonym username. - - (3) Fast re-authentication usernames. For example, - 53953754@myoperator.com might be a valid fast re-authentication - identity. In this case, 53953754 is the fast re-authentication - username. Unlike permanent usernames and pseudonym usernames, fast - re-authentication usernames are one-time identifiers, which are not - re-used across EAP exchanges. - - The first two types of identities are used only on full - authentication and the last one only on fast re-authentication. When - the optional identity privacy support is not used, the non-pseudonym - permanent identity is used on full authentication. The fast - re-authentication exchange is specified in Section 5. - -4.2.1.4. Username Decoration - - In some environments, the peer may need to decorate the identity by - prepending or appending the username with a string, in order to - indicate supplementary AAA routing information in addition to the NAI - - - -Haverinen & Salowey Informational [Page 12] - -RFC 4186 EAP-SIM Authentication January 2006 - - - realm. (The usage of an NAI realm portion is not considered - decoration.) Username decoration is out of the scope of this - document. However, it should be noted that username decoration might - prevent the server from recognizing a valid username. Hence, - although the peer MAY use username decoration in the identities that - the peer includes in EAP-Response/Identity, and although the EAP - server MAY accept a decorated peer username in this message, the peer - or the EAP server MUST NOT decorate any other peer identities that - are used in various EAP-SIM attributes. Only the identity used in - the EAP-Response/Identity may be decorated. - -4.2.1.5. NAI Realm Portion - - The peer MAY include a realm portion in the peer identity, as per the - NAI format. The use of a realm portion is not mandatory. - - If a realm is used, the realm MAY be chosen by the subscriber's home - operator and it MAY be a configurable parameter in the EAP-SIM peer - implementation. In this case, the peer is typically configured with - the NAI realm of the home operator. Operators MAY reserve a specific - realm name for EAP-SIM users. This convention makes it easy to - recognize that the NAI identifies a GSM subscriber. Such a reserved - NAI realm may be a useful hint as to the first authentication method - to use during method negotiation. When the peer is using a pseudonym - username instead of the permanent username, the peer selects the - realm name portion similarly as it select the realm portion when - using the permanent username. - - If no configured realm name is available, the peer MAY derive the - realm name from the MCC and MNC portions of the IMSI. A RECOMMENDED - way to derive the realm from the IMSI using the realm 3gppnetwork.org - is specified in [3GPP-TS-23.003]. - - Some old implementations derive the realm name from the IMSI by - concatenating "mnc", the MNC digits of IMSI, ".mcc", the MCC digits - of IMSI, and ".owlan.org". For example, if the IMSI is - 123456789098765, and the MNC is three digits long, then the derived - realm name is "mnc456.mcc123.owlan.org". As there are no DNS servers - running at owlan.org, these realm names can only be used with - manually configured AAA routing. New implementations SHOULD use the - mechanism specified in [3GPP-TS-23.003] instead of owlan.org. - - The IMSI is a string of digits without any explicit structure, so the - peer may not be able to determine the length of the MNC portion. If - the peer is not able to determine whether the MNC is two or three - digits long, the peer MAY use a 3-digit MNC. If the correct length - of the MNC is two, then the MNC used in the realm name includes the - first digit of the MSIN. Hence, when configuring AAA networks for - - - -Haverinen & Salowey Informational [Page 13] - -RFC 4186 EAP-SIM Authentication January 2006 - - - operators that have 2-digit MNCs, the network SHOULD also be prepared - for realm names with incorrect, 3-digit MNCs. - -4.2.1.6. Format of the Permanent Username - - The non-pseudonym permanent username SHOULD be derived from the IMSI. - In this case, the permanent username MUST be of the format "1" | - IMSI, where the character "|" denotes concatenation. In other words, - the first character of the username is the digit one (ASCII value 31 - hexadecimal), followed by the IMSI. The IMSI is encoded as an ASCII - string that consists of not more than 15 decimal digits (ASCII values - between 30 and 39 hexadecimal), one character per IMSI digit, in the - order specified in [GSM-03.03]. For example, a permanent username - derived from the IMSI 295023820005424 would be encoded as the ASCII - string "1295023820005424" (byte values in hexadecimal notation: 31 32 - 39 35 30 32 33 38 32 30 30 30 35 34 32 34). - - The EAP server MAY use the leading "1" as a hint to try EAP-SIM as - the first authentication method during method negotiation, rather - than, for example EAP/AKA. The EAP-SIM server MAY propose EAP-SIM, - even if the leading character was not "1". - - Alternatively, an implementation MAY choose a permanent username that - is not based on the IMSI. In this case, the selection of the - username, its format, and its processing is out of the scope of this - document. In this case, the peer implementation MUST NOT prepend any - leading characters to the username. - -4.2.1.7. Generating Pseudonyms and Fast Re-authentication Identities by - the Server - - Pseudonym usernames and fast re-authentication identities are - generated by the EAP server. The EAP server produces pseudonym - usernames and fast re-authentication identities in an - implementation-dependent manner. Only the EAP server needs to be - able to map the pseudonym username to the permanent identity, or to - recognize a fast re-authentication identity. - - EAP-SIM includes no provisions to ensure that the same EAP server - that generated a pseudonym username will be used on the - authentication exchange when the pseudonym username is used. It is - recommended that the EAP servers implement some centralized mechanism - to allow all EAP servers of the home operator to map pseudonyms - generated by other severs to the permanent identity. If no such - mechanism is available, then the EAP server failing to understand a - pseudonym issued by another server can request the that peer send the - permanent identity. - - - - -Haverinen & Salowey Informational [Page 14] - -RFC 4186 EAP-SIM Authentication January 2006 - - - When issuing a fast re-authentication identity, the EAP server may - include a realm name in the identity to make the fast - re-authentication request be forwarded to the same EAP server. - - When generating fast re-authentication identities, the server SHOULD - choose a fresh, new fast re-authentication identity that is different - from the previous ones that were used after the same full - authentication exchange. A full authentication exchange and the - associated fast re-authentication exchanges are referred to here as - the same "full authentication context". The fast re-authentication - identity SHOULD include a random component. This random component - works as a full authentication context identifier. A - context-specific fast re-authentication identity can help the server - to detect whether its fast re-authentication state information - matches that of its peer (in other words, whether the state - information is from the same full authentication exchange). The - random component also makes the fast re-authentication identities - unpredictable, so an attacker cannot initiate a fast - re-authentication exchange to get the server's EAP-Request/SIM/ - Re-authentication packet. - - Transmitting pseudonyms and fast re-authentication identities from - the server to the peer is discussed in Section 4.2.1.8. The - pseudonym is transmitted as a username, without an NAI realm, and the - fast re-authentication identity is transmitted as a complete NAI, - including a realm portion if a realm is required. The realm is - included in the fast re-authentication identity to allow the server - to include a server-specific realm. - - Regardless of the construction method, the pseudonym username MUST - conform to the grammar specified for the username portion of an NAI. - The fast re-authentication identity also MUST conform to the NAI - grammar. The EAP servers that the subscribers of an operator can use - MUST ensure that the pseudonym usernames and the username portions - used in fast re-authentication identities they generate are unique. - - In any case, it is necessary that permanent usernames, pseudonym - usernames, and fast re-authentication usernames are separate and - recognizable from each other. It is also desirable that EAP-SIM and - EAP-AKA [EAP-AKA] usernames be distinguishable from each other as an - aid for the server on which method to offer. - - In general, it is the task of the EAP server and the policies of its - administrator to ensure sufficient separation of the usernames. - Pseudonym usernames and fast re-authentication usernames are both - produced and used by the EAP server. The EAP server MUST compose - pseudonym usernames and fast re-authentication usernames so that it - can determine if an NAI username is an EAP-SIM pseudonym username or - - - -Haverinen & Salowey Informational [Page 15] - -RFC 4186 EAP-SIM Authentication January 2006 - - - an EAP-SIM fast re-authentication username. For instance, when the - usernames have been derived from the IMSI, the server could use - different leading characters in the pseudonym usernames and fast - re-authentication usernames (e.g., the pseudonym could begin with a - leading "3" character). When mapping a fast re-authentication - identity to a permanent identity, the server SHOULD only examine the - username portion of the fast re-authentication identity and ignore - the realm portion of the identity. - - Because the peer may fail to save a pseudonym username sent in an - EAP-Request/SIM/Challenge, for example due to malfunction, the EAP - server SHOULD maintain at least the most recently used pseudonym - username in addition to the most recently issued pseudonym username. - If the authentication exchange is not completed successfully, then - the server SHOULD NOT overwrite the pseudonym username that was - issued during the most recent successful authentication exchange. - -4.2.1.8. Transmitting Pseudonyms and Fast Re-authentication Identities - to the Peer - - The server transmits pseudonym usernames and fast re-authentication - identities to the peer in cipher, using the AT_ENCR_DATA attribute. - - The EAP-Request/SIM/Challenge message MAY include an encrypted - pseudonym username and/or an encrypted fast re-authentication - identity in the value field of the AT_ENCR_DATA attribute. Because - identity privacy support and fast re-authentication are optional - implementations, the peer MAY ignore the AT_ENCR_DATA attribute and - always use the permanent identity. On fast re-authentication - (discussed in Section 5), the server MAY include a new, encrypted - fast re-authentication identity in the - EAP-Request/SIM/Re-authentication message. - - On receipt of the EAP-Request/SIM/Challenge, the peer MAY decrypt the - encrypted data in AT_ENCR_DATA. If the authentication exchange is - successful, and the encrypted data includes a pseudonym username, - then the peer may use the obtained pseudonym username on the next - full authentication. If a fast re-authentication identity is - included, then the peer MAY save it together with other fast - re-authentication state information, as discussed in Section 5, for - the next fast re-authentication. If the authentication exchange does - not complete successfully, the peer MUST ignore the received - pseudonym username and the fast re-authentication identity. - - If the peer does not receive a new pseudonym username in the - EAP-Request/SIM/Challenge message, the peer MAY use an old pseudonym - username instead of the permanent username on the next full - authentication. The username portions of fast re-authentication - - - -Haverinen & Salowey Informational [Page 16] - -RFC 4186 EAP-SIM Authentication January 2006 - - - identities are one-time usernames, which the peer MUST NOT re-use. - When the peer uses a fast re-authentication identity in an EAP - exchange, the peer MUST discard the fast re-authentication identity - and not re-use it in another EAP authentication exchange, even if the - authentication exchange was not completed. - -4.2.1.9. Usage of the Pseudonym by the Peer - - When the optional identity privacy support is used on full - authentication, the peer MAY use a pseudonym username received as - part of a previous full authentication sequence as the username - portion of the NAI. The peer MUST NOT modify the pseudonym username - received in AT_NEXT_PSEUDONYM. However, as discussed above, the peer - MAY need to decorate the username in some environments by appending - or prepending the username with a string that indicates supplementary - AAA routing information. - - When using a pseudonym username in an environment where a realm - portion is used, the peer concatenates the received pseudonym - username with the "@" character and an NAI realm portion. The - selection of the NAI realm is discussed above. The peer can select - the realm portion similarly, regardless of whether it uses the - permanent username or a pseudonym username. - -4.2.1.10. Usage of the Fast Re-authentication Identity by the Peer - - On fast re-authentication, the peer uses the fast re-authentication - identity that was received as part of the previous authentication - sequence. A new re-authentication identity may be delivered as part - of both full authentication and fast re-authentication. The peer - MUST NOT modify the username part of the fast re-authentication - identity received in AT_NEXT_REAUTH_ID, except in cases when username - decoration is required. Even in these cases, the "root" fast - re-authentication username must not be modified, but it may be - appended or prepended with another string. - -4.2.2. Communicating the Peer Identity to the Server - -4.2.2.1. General - - The peer identity MAY be communicated to the server with the - EAP-Response/Identity message. This message MAY contain the - permanent identity, a pseudonym identity, or a fast re-authentication - identity. If the peer uses the permanent identity or a pseudonym - identity, which the server is able to map to the permanent identity, - then the authentication proceeds as discussed in the overview of - Section 3. If the peer uses a fast re-authentication identity, and - if the fast re-authentication identity matches with a valid fast - - - -Haverinen & Salowey Informational [Page 17] - -RFC 4186 EAP-SIM Authentication January 2006 - - - re-authentication identity maintained by the server, and if the - server agrees to use fast re-authentication, then a fast - re-authentication exchange is performed, as described in Section 5. - - The peer identity can also be transmitted from the peer to the server - using EAP-SIM messages instead of the EAP-Response/Identity. In this - case, the server includes an identity-requesting attribute - (AT_ANY_ID_REQ, AT_FULLAUTH_ID_REQ or AT_PERMANENT_ID_REQ) in the - EAP-Request/SIM/Start message, and the peer includes the AT_IDENTITY - attribute, which contains the peer's identity, in the - EAP-Response/SIM/Start message. The AT_ANY_ID_REQ attribute is a - general identity-requesting attribute, which the server uses if it - does not specify which kind of an identity the peer should return in - AT_IDENTITY. The server uses the AT_FULLAUTH_ID_REQ attribute to - request either the permanent identity or a pseudonym identity. The - server uses the AT_PERMANENT_ID_REQ attribute to request that the - peer send its permanent identity. - - The identity format in the AT_IDENTITY attribute is the same as in - the EAP-Response/Identity packet (except that identity decoration is - not allowed). The AT_IDENTITY attribute contains a permanent - identity, a pseudonym identity, or a fast re-authentication identity. - - Please note that the EAP-SIM peer and the EAP-SIM server only process - the AT_IDENTITY attribute; entities that only pass through EAP - packets do not process this attribute. Hence, the authenticator and - other intermediate AAA elements (such as possible AAA proxy servers) - will continue to refer to the peer with the original identity from - the EAP-Response/Identity packet unless the identity authenticated in - the AT_IDENTITY attribute is communicated to them in another way - within the AAA protocol. - -4.2.2.2. Relying on EAP-Response/Identity Discouraged - - The EAP-Response/Identity packet is not method-specific, so in many - implementations it may be handled by an EAP Framework. This - introduces an additional layer of processing between the EAP peer and - EAP server. The extra layer of processing may cache identity - responses or add decorations to the identity. A modification of the - identity response will cause the EAP peer and EAP server to use - different identities in the key derivation, which will cause the - protocol to fail. - - For this reason, it is RECOMMENDED that the EAP peer and server use - the method-specific identity attributes in EAP-SIM, and the server is - strongly discouraged from relying upon the EAP-Response/Identity. - - - - - -Haverinen & Salowey Informational [Page 18] - -RFC 4186 EAP-SIM Authentication January 2006 - - - In particular, if the EAP server receives a decorated identity in - EAP-Response/Identity, then the EAP server MUST use the - identity-requesting attributes to request that the peer send an - unmodified and undecorated copy of the identity in AT_IDENTITY. - -4.2.3. Choice of Identity for the EAP-Response/Identity - - If EAP-SIM peer is started upon receiving an EAP-Request/Identity - message, then the peer MAY use an EAP-SIM identity in the EAP- - Response/Identity packet. In this case, the peer performs the - following steps. - - If the peer has maintained fast re-authentication state information - and wants to use fast re-authentication, then the peer transmits the - fast re-authentication identity in EAP-Response/Identity. - - Else, if the peer has a pseudonym username available, then the peer - transmits the pseudonym identity in EAP-Response/Identity. - - In other cases, the peer transmits the permanent identity in - EAP-Response/Identity. - -4.2.4. Server Operation in the Beginning of EAP-SIM Exchange - - As discussed in Section 4.2.2.2, the server SHOULD NOT rely on an - identity string received in EAP-Response/Identity. Therefore, the - RECOMMENDED way to start an EAP-SIM exchange is to ignore any - received identity strings. The server SHOULD begin the EAP-SIM - exchange by issuing the EAP-Request/SIM/Start packet with an - identity-requesting attribute to indicate that the server wants the - peer to include an identity in the AT_IDENTITY attribute of the EAP- - Response/SIM/Start message. Three methods to request an identity - from the peer are discussed below. - - If the server chooses not to ignore the contents of EAP- - Response/Identity, then the server may have already received an EAP- - SIM identity in this packet. However, if the EAP server has not - received any EAP-SIM peer identity (permanent identity, pseudonym - identity, or fast re-authentication identity) from the peer when - sending the first EAP-SIM request, or if the EAP server has received - an EAP-Response/Identity packet but the contents do not appear to be - a valid permanent identity, pseudonym identity or a re-authentication - identity, then the server MUST request an identity from the peer - using one of the methods below. - - The server sends the EAP-Request/SIM/Start message with the - AT_PERMANENT_ID_REQ attribute to indicate that the server wants the - peer to include the permanent identity in the AT_IDENTITY attribute - - - -Haverinen & Salowey Informational [Page 19] - -RFC 4186 EAP-SIM Authentication January 2006 - - - of the EAP-Response/SIM/Start message. This is done in the following - cases: - - o The server does not support fast re-authentication or identity - privacy. - - o The server decided to process a received identity, and the server - recognizes the received identity as a pseudonym identity but the - server is not able to map the pseudonym identity to a permanent - identity. - - The server issues the EAP-Request/SIM/Start packet with the - AT_FULLAUTH_ID_REQ attribute to indicate that the server wants the - peer to include a full authentication identity (pseudonym identity or - permanent identity) in the AT_IDENTITY attribute of the - EAP-Response/SIM/Start message. This is done in the following cases: - - o The server does not support fast re-authentication and the server - supports identity privacy. - - o The server decided to process a received identity, and the server - recognizes the received identity as a re-authentication identity - but the server is not able to map the re-authentication identity - to a permanent identity. - - The server issues the EAP-Request/SIM/Start packet with the - AT_ANY_ID_REQ attribute to indicate that the server wants the peer to - include an identity in the AT_IDENTITY attribute of the - EAP-Response/SIM/Start message, and the server does not indicate any - preferred type for the identity. This is done in other cases, such - as when the server ignores a received EAP-Response/Identity, the - server does not have any identity, or the server does not recognize - the format of a received identity. - -4.2.5. Processing of EAP-Request/SIM/Start by the Peer - - Upon receipt of an EAP-Request/SIM/Start message, the peer MUST - perform the following steps. - - If the EAP-Request/SIM/Start does not include an identity request - attribute, then the peer responds with EAP-Response/SIM/Start without - AT_IDENTITY. The peer includes the AT_SELECTED_VERSION and - AT_NONCE_MT attributes, because the exchange is a full authentication - exchange. - - If the EAP-Request/SIM/Start includes AT_PERMANENT_ID_REQ, and if the - peer does not have a pseudonym available, then the peer MUST respond - with EAP-Response/SIM/Start and include the permanent identity in - - - -Haverinen & Salowey Informational [Page 20] - -RFC 4186 EAP-SIM Authentication January 2006 - - - AT_IDENTITY. If the peer has a pseudonym available, then the peer - MAY refuse to send the permanent identity; hence, in this case the - peer MUST either respond with EAP-Response/SIM/Start and include the - permanent identity in AT_IDENTITY or respond with EAP-Response/SIM/ - Client-Error packet with the code "unable to process packet". - - If the EAP-Request/SIM/Start includes AT_FULL_AUTH_ID_REQ, and if the - peer has a pseudonym available, then the peer SHOULD respond with - EAP-Response/SIM/Start and include the pseudonym identity in - AT_IDENTITY. If the peer does not have a pseudonym when it receives - this message, then the peer MUST respond with EAP-Response/SIM/Start - and include the permanent identity in AT_IDENTITY. The Peer MUST NOT - use a re-authentication identity in the AT_IDENTITY attribute. - - If the EAP-Request/SIM/Start includes AT_ANY_ID_REQ, and if the peer - has maintained fast re-authentication state information and the peer - wants to use fast re-authentication, then the peer responds with - EAP-Response/SIM/Start and includes the fast re-authentication - identity in AT_IDENTITY. Else, if the peer has a pseudonym identity - available, then the peer responds with EAP-Response/SIM/Start and - includes the pseudonym identity in AT_IDENTITY. Else, the peer - responds with EAP-Response/SIM/Start and includes the permanent - identity in AT_IDENTITY. - - An EAP-SIM exchange may include several EAP/SIM/Start rounds. The - server may issue a second EAP-Request/SIM/Start if it was not able to - recognize the identity that the peer used in the previous AT_IDENTITY - attribute. At most, three EAP/SIM/Start rounds can be used, so the - peer MUST NOT respond to more than three EAP-Request/SIM/Start - messages within an EAP exchange. The peer MUST verify that the - sequence of EAP-Request/SIM/Start packets that the peer receives - comply with the sequencing rules defined in this document. That is, - AT_ANY_ID_REQ can only be used in the first EAP-Request/SIM/Start; in - other words, AT_ANY_ID_REQ MUST NOT be used in the second or third - EAP-Request/SIM/Start. AT_FULLAUTH_ID_REQ MUST NOT be used if the - previous EAP-Request/SIM/Start included AT_PERMANENT_ID_REQ. The - peer operation, in cases when it receives an unexpected attribute or - an unexpected message, is specified in Section 6.3.1. - -4.2.6. Attacks Against Identity Privacy - - The section above specifies two possible ways the peer can operate - upon receipt of AT_PERMANENT_ID_REQ. This is because a received - AT_PERMANENT_ID_REQ does not necessarily originate from the valid - network, but an active attacker may transmit an EAP-Request/SIM/ - Start packet with an AT_PERMANENT_ID_REQ attribute to the peer, in an - effort to find out the true identity of the user. If the peer does - not want to reveal its permanent identity, then the peer sends the - - - -Haverinen & Salowey Informational [Page 21] - -RFC 4186 EAP-SIM Authentication January 2006 - - - EAP-Response/SIM/Client-Error packet with the error code "unable to - process packet", and the authentication exchange terminates. - - Basically, there are two different policies that the peer can employ - with regard to AT_PERMANENT_ID_REQ. A "conservative" peer assumes - that the network is able to maintain pseudonyms robustly. Therefore, - if a conservative peer has a pseudonym username, the peer responds - with EAP-Response/SIM/Client-Error to the EAP packet with - AT_PERMANENT_ID_REQ, because the peer believes that the valid network - is able to map the pseudonym identity to the peer's permanent - identity. (Alternatively, the conservative peer may accept - AT_PERMANENT_ID_REQ in certain circumstances, for example, if the - pseudonym was received a long time ago.) The benefit of this policy - is that it protects the peer against active attacks on anonymity. On - the other hand, a "liberal" peer always accepts the - AT_PERMANENT_ID_REQ and responds with the permanent identity. The - benefit of this policy is that it works even if the valid network - sometimes loses pseudonyms and is not able to map them to the - permanent identity. - -4.2.7. Processing of AT_IDENTITY by the Server - - When the server receives an EAP-Response/SIM/Start message with the - AT_IDENTITY (in response to the server's identity requesting - attribute), the server MUST operate as follows. - - If the server used AT_PERMANENT_ID_REQ, and if the AT_IDENTITY does - not contain a valid permanent identity, then the server sends - EAP-Request/SIM/Notification with AT_NOTIFICATION code "General - failure" (16384), and the EAP exchange terminates. If the server - recognizes the permanent identity and is able to continue, then the - server proceeds with full authentication by sending EAP-Request/SIM/ - Challenge. - - If the server used AT_FULLAUTH_ID_REQ, and if AT_IDENTITY contains a - valid permanent identity or a pseudonym identity that the server can - map to a valid permanent identity, then the server proceeds with full - authentication by sending EAP-Request/SIM/Challenge. If AT_IDENTITY - contains a pseudonym identity that the server is not able to map to a - valid permanent identity, or an identity that the server is not able - to recognize or classify, then the server sends EAP-Request/SIM/Start - with AT_PERMANENT_ID_REQ. - - If the server used AT_ANY_ID_REQ, and if the AT_IDENTITY contains a - valid permanent identity or a pseudonym identity that the server can - map to a valid permanent identity, then the server proceeds with full - authentication by sending EAP-Request/SIM/Challenge. - - - - -Haverinen & Salowey Informational [Page 22] - -RFC 4186 EAP-SIM Authentication January 2006 - - - If the server used AT_ANY_ID_REQ, and if AT_IDENTITY contains a valid - fast re-authentication identity and the server agrees on using - re-authentication, then the server proceeds with fast - re-authentication by sending EAP-Request/SIM/Re-authentication - (Section 5). - - If the server used AT_ANY_ID_REQ, and if the peer sent an - EAP-Response/SIM/Start with only AT_IDENTITY (indicating - re-authentication), but the server is not able to map the identity to - a permanent identity, then the server sends EAP-Request/SIM/Start - with AT_FULLAUTH_ID_REQ. - - If the server used AT_ANY_ID_REQ, and if AT_IDENTITY contains a valid - fast re-authentication identity that the server is able to map to a - permanent identity, and if the server does not want to use fast - re-authentication, then the server sends EAP-Request/SIM/Start - without any identity requesting attributes. - - If the server used AT_ANY_ID_REQ, and AT_IDENTITY contains an - identity that the server recognizes as a pseudonym identity but the - server is not able to map the pseudonym identity to a permanent - identity, then the server sends EAP-Request/SIM/Start with - AT_PERMANENT_ID_REQ. - - If the server used AT_ANY_ID_REQ, and AT_IDENTITY contains an - identity that the server is not able to recognize or classify, then - the server sends EAP-Request/SIM/Start with AT_FULLAUTH_ID_REQ. - -4.3. Message Sequence Examples (Informative) - - This section contains non-normative message sequence examples to - illustrate how the peer identity can be communicated to the server. - - - - - - - - - - - - - - - - - - - -Haverinen & Salowey Informational [Page 23] - -RFC 4186 EAP-SIM Authentication January 2006 - - -4.3.1. Full Authentication - - This case for full authentication is illustrated below in Figure 2. - In this case, AT_IDENTITY contains either the permanent identity or a - pseudonym identity. The same sequence is also used in case the - server uses the AT_FULLAUTH_ID_REQ in EAP-Request/SIM/Start. - - Peer Authenticator - | | - | +------------------------------+ - | | Server does not have a | - | | Subscriber identity available| - | | When starting EAP-SIM | - | +------------------------------+ - | | - | EAP-Request/SIM/Start | - | (AT_ANY_ID_REQ, AT_VERSION_LIST) | - |<------------------------------------------------------| - | | - | | - | EAP-Response/SIM/Start | - | (AT_IDENTITY, AT_NONCE_MT, | - | AT_SELECTED_VERSION) | - |------------------------------------------------------>| - | | - - Figure 2: Requesting any identity, full authentication - - If the peer uses its full authentication identity and the AT_IDENTITY - attribute contains a valid permanent identity or a valid pseudonym - identity that the EAP server is able to map to the permanent - identity, then the full authentication sequence proceeds as usual - with the EAP Server issuing the EAP-Request/SIM/Challenge message. - - - - - - - - - - - - - - - - - - -Haverinen & Salowey Informational [Page 24] - -RFC 4186 EAP-SIM Authentication January 2006 - - -4.3.2. Fast Re-authentication - - The case when the server uses the AT_ANY_ID_REQ and the peer wants to - perform fast re-authentication is illustrated below in Figure 3. - - Peer Authenticator - | | - | +------------------------------+ - | | Server does not have a | - | | Subscriber identity available| - | | When starting EAP-SIM | - | +------------------------------+ - | | - | EAP-Request/SIM/Start | - | (AT_ANY_ID_REQ, AT_VERSION_LIST) | - |<------------------------------------------------------| - | | - | | - | EAP-Response/SIM/Start | - | (AT_IDENTITY containing a fast re-auth. identity) | - |------------------------------------------------------>| - | | - - Figure 3: Requesting any identity, fast re-authentication - - On fast re-authentication, if the AT_IDENTITY attribute contains a - valid fast re-authentication identity and the server agrees on using - fast re-authentication, then the server proceeds with the fast - re-authentication sequence and issues the EAP-Request/SIM/ - Re-authentication packet, as specified in Section 5. - - - - - - - - - - - - - - - - - - - - - -Haverinen & Salowey Informational [Page 25] - -RFC 4186 EAP-SIM Authentication January 2006 - - -4.3.3. Fall Back to Full Authentication - - Figure 4 illustrates cases in which the server does not recognize the - fast re-authentication identity the peer used in AT_IDENTITY, and - issues a second EAP-Request/SIM/Start message. - - Peer Authenticator - | | - | +------------------------------+ - | | Server does not have a | - | | Subscriber identity available| - | | When starting EAP-SIM | - | +------------------------------+ - | | - | EAP-Request/SIM/Start | - | (AT_ANY_ID_REQ, AT_VERSION_LIST) | - |<------------------------------------------------------| - | | - | | - | EAP-Response/SIM/Start | - | (AT_IDENTITY containing a fast re-auth. identity) | - |------------------------------------------------------>| - | | - | +------------------------------+ - | | Server does not recognize | - | | The fast re-auth. | - | | Identity | - | +------------------------------+ - | | - | EAP-Request/SIM/Start | - | (AT_FULLAUTH_ID_REQ, AT_VERSION_LIST) | - |<------------------------------------------------------| - | | - | | - | EAP-Response/SIM/Start | - | (AT_IDENTITY with a full-auth. identity, AT_NONCE_MT, | - | AT_SELECTED_VERSION) | - |------------------------------------------------------>| - | | - - Figure 4: Fall back to full authentication - - - - - - - - - - -Haverinen & Salowey Informational [Page 26] - -RFC 4186 EAP-SIM Authentication January 2006 - - -4.3.4. Requesting the Permanent Identity 1 - - Figure 5 illustrates the case in which the EAP server fails to map - the pseudonym identity included in the EAP-Response/Identity packet - to a valid permanent identity. - - Peer Authenticator - | | - | EAP-Request/Identity | - |<------------------------------------------------------| - | | - | EAP-Response/Identity | - | (Includes a pseudonym) | - |------------------------------------------------------>| - | | - | +------------------------------+ - | | Server fails to map the | - | | Pseudonym to a permanent id. | - | +------------------------------+ - | EAP-Request/SIM/Start | - | (AT_PERMANENT_ID_REQ, AT_VERSION_LIST) | - |<------------------------------------------------------| - | | - | EAP-Response/SIM/Start | - | (AT_IDENTITY with permanent identity, AT_NONCE_MT, | - | AT_SELECTED_VERSION) | - |------------------------------------------------------>| - | | - - Figure 5: Requesting the permanent identity - - If the server recognizes the permanent identity, then the - authentication sequence proceeds as usual with the EAP Server issuing - the EAP-Request/SIM/Challenge message. - - - - - - - - - - - - - - - - - -Haverinen & Salowey Informational [Page 27] - -RFC 4186 EAP-SIM Authentication January 2006 - - -4.3.5. Requesting the Permanent Identity 2 - - Figure 6 illustrates the case in which the EAP server fails to map - the pseudonym included in the AT_IDENTITY attribute to a valid - permanent identity. - - Peer Authenticator - | | - | +------------------------------+ - | | Server does not have a | - | | Subscriber identity available| - | | When starting EAP-SIM | - | +------------------------------+ - | EAP-Request/SIM/Start | - | (AT_ANY_ID_REQ, AT_VERSION_LIST) | - |<------------------------------------------------------| - | | - |EAP-Response/SIM/Start | - |(AT_IDENTITY with a pseudonym identity, AT_NONCE_MT, | - | AT_SELECTED_VERSION) | - |------------------------------------------------------>| - | +-------------------------------+ - | | Server fails to map the | - | | Pseudonym in AT_IDENTITY | - | | to a valid permanent identity | - | +-------------------------------+ - | | - | EAP-Request/SIM/Start | - | (AT_PERMANENT_ID_REQ, AT_VERSION_LIST) | - |<------------------------------------------------------| - | | - | EAP-Response/SIM/Start | - | (AT_IDENTITY with permanent identity, | - | AT_NONCE_MT, AT_SELECTED_VERSION) | - |------------------------------------------------------>| - | | - - Figure 6: Requesting a permanent identity (two EAP-SIM Start rounds) - -4.3.6. Three EAP-SIM/Start Roundtrips - - In the worst case, there are three EAP/SIM/Start round trips before - the server obtains an acceptable identity. This case is illustrated - in Figure 7. - - - - - - - -Haverinen & Salowey Informational [Page 28] - -RFC 4186 EAP-SIM Authentication January 2006 - - - Peer Authenticator - | | - | +------------------------------+ - | | Server does not have a | - | | Subscriber identity available| - | | When starting EAP-SIM | - | +------------------------------+ - | EAP-Request/SIM/Start | - | (Includes AT_ANY_ID_REQ, AT_VERSION_LIST) | - |<------------------------------------------------------| - | | - | EAP-Response/SIM/Start | - | (AT_IDENTITY with fast re-auth. identity) | - |------------------------------------------------------>| - | | - | +------------------------------+ - | | Server does not accept | - | | The fast re-auth. | - | | Identity | - | +------------------------------+ - | EAP-Request/SIM/Start | - | (AT_FULLAUTH_ID_REQ, AT_VERSION_LIST) | - |<------------------------------------------------------| - | | - : : - : : - : : - : : - |EAP-Response/SIM/Start | - |(AT_IDENTITY with a pseudonym identity, AT_NONCE_MT, | - | AT_SELECTED_VERSION) | - |------------------------------------------------------>| - | | - | +-------------------------------+ - | | Server fails to map the | - | | Pseudonym in AT_IDENTITY | - | | to a valid permanent identity | - | +-------------------------------+ - | EAP-Request/SIM/Start | - | (AT_PERMANENT_ID_REQ, AT_VERSION_LIST) | - |<------------------------------------------------------| - | | - | EAP-Response/SIM/Start | - | (AT_IDENTITY with permanent identity, AT_NONCE_MT, | - | AT_SELECTED_VERSION) | - |------------------------------------------------------>| - | | - Figure 7: Three EAP-SIM Start rounds - - - -Haverinen & Salowey Informational [Page 29] - -RFC 4186 EAP-SIM Authentication January 2006 - - - After the last EAP-Response/SIM/Start message, the full - authentication sequence proceeds as usual. If the EAP Server - recognizes the permanent identity and is able to proceed, the server - issues the EAP-Request/SIM/Challenge message. - -5. Fast Re-Authentication - -5.1. General - - In some environments, EAP authentication may be performed frequently. - Because the EAP-SIM full authentication procedure makes use of the - GSM SIM A3/A8 algorithms, and therefore requires 2 or 3 fresh - triplets from the Authentication Centre, the full authentication - procedure is not very well suited for frequent use. Therefore, - EAP-SIM includes a more inexpensive fast re-authentication procedure - that does not make use of the SIM A3/A8 algorithms and does not need - new triplets from the Authentication Centre. Re-authentication can - be performed in fewer roundtrips than the full authentication. - - Fast re-authentication is optional to implement for both the EAP-SIM - server and peer. On each EAP authentication, either one of the - entities may also fall back on full authentication if it does not - want to use fast re-authentication. - - Fast re-authentication is based on the keys derived on the preceding - full authentication. The same K_aut and K_encr keys that were used - in full authentication are used to protect EAP-SIM packets and - attributes, and the original Master Key from full authentication is - used to generate a fresh Master Session Key, as specified in Section - 7. - - The fast re-authentication exchange makes use of an unsigned 16-bit - counter, included in the AT_COUNTER attribute. The counter has three - goals: 1) it can be used to limit the number of successive - reauthentication exchanges without full authentication 2) it - contributes to the keying material, and 3) it protects the peer and - the server from replays. On full authentication, both the server and - the peer initialize the counter to one. The counter value of at - least one is used on the first fast re-authentication. On subsequent - fast re-authentications, the counter MUST be greater than on any of - the previous re-authentications. For example, on the second fast - re-authentication, the counter value is two or greater. The - AT_COUNTER attribute is encrypted. - - Both the peer and the EAP server maintain a copy of the counter. The - EAP server sends its counter value to the peer in the fast - re-authentication request. The peer MUST verify that its counter - value is less than or equal to the value sent by the EAP server. - - - -Haverinen & Salowey Informational [Page 30] - -RFC 4186 EAP-SIM Authentication January 2006 - - - The server includes an encrypted server random nonce (AT_NONCE_S) in - the fast re-authentication request. The AT_MAC attribute in the - peer's response is calculated over NONCE_S to provide a - challenge/response authentication scheme. The NONCE_S also - contributes to the new Master Session Key. - - Both the peer and the server SHOULD have an upper limit for the - number of subsequent fast re-authentications allowed before a full - authentication needs to be performed. Because a 16-bit counter is - used in fast re-authentication, the theoretical maximum number of - re-authentications is reached when the counter value reaches FFFF - hexadecimal. - - In order to use fast re-authentication, the peer and the EAP server - need to store the following values: Master Key, latest counter value - and the next fast re-authentication identity. K_aut, K_encr may - either be stored or derived again from MK. The server may also need - to store the permanent identity of the user. - -5.2. Comparison to UMTS AKA - - When analyzing the fast re-authentication exchange, it may be helpful - to compare it with the UMTS Authentication and Key Agreement (AKA) - exchange, which it resembles closely. The counter corresponds to the - UMTS AKA sequence number, NONCE_S corresponds to RAND, AT_MAC in - EAP-Request/SIM/Re-authentication corresponds to AUTN, the AT_MAC in - EAP-Response/SIM/Re-authentication corresponds to RES, - AT_COUNTER_TOO_SMALL corresponds to AUTS, and encrypting the counter - corresponds to the usage of the Anonymity Key. Also, the key - generation on fast re-authentication, with regard to random or fresh - material, is similar to UMTS AKA -- the server generates the NONCE_S - and counter values, and the peer only verifies that the counter value - is fresh. - - It should also be noted that encrypting the AT_NONCE_S, AT_COUNTER, - or AT_COUNTER_TOO_SMALL attributes is not important to the security - of the fast re-authentication exchange. - -5.3. Fast Re-authentication Identity - - The fast re-authentication procedure makes use of separate - re-authentication user identities. Pseudonyms and the permanent - identity are reserved for full authentication only. If a - re-authentication identity is lost and the network does not recognize - it, the EAP server can fall back on full authentication. - - - - - - -Haverinen & Salowey Informational [Page 31] - -RFC 4186 EAP-SIM Authentication January 2006 - - - If the EAP server supports fast re-authentication, it MAY include the - skippable AT_NEXT_REAUTH_ID attribute in the encrypted data of - EAP-Request/SIM/Challenge message (Section 9.3). This attribute - contains a new fast re-authentication identity for the next fast - re-authentication. The attribute also works as a capability flag - that, indicating that the server supports fast re-authentication, and - that the server wants to continue using fast re-authentication within - the current context. The peer MAY ignore this attribute, in which - case it MUST use full authentication next time. If the peer wants to - use re-authentication, it uses this fast re-authentication identity - on next authentication. Even if the peer has a fast - re-authentication identity, the peer MAY discard the fast - re-authentication identity and use a pseudonym or the permanent - identity instead, in which case full authentication MUST be - performed. If the EAP server does not include the AT_NEXT_REAUTH_ID - in the encrypted data of EAP-Request/SIM/Challenge or - EAP-Request/SIM/ Re-authentication, then the peer MUST discard its - current fast re-authentication state information and perform a full - authentication next time. - - In environments where a realm portion is needed in the peer identity, - the fast re-authentication identity received in AT_NEXT_REAUTH_ID - MUST contain both a username portion and a realm portion, as per the - NAI format. The EAP Server can choose an appropriate realm part in - order to have the AAA infrastructure route subsequent fast - re-authentication related requests to the same AAA server. For - example, the realm part MAY include a portion that is specific to the - AAA server. Hence, it is sufficient to store the context required - for fast re-authentication in the AAA server that performed the full - authentication. - - The peer MAY use the fast re-authentication identity in the - EAP-Response/Identity packet or, in response to the server's - AT_ANY_ID_REQ attribute, the peer MAY use the fast re-authentication - identity in the AT_IDENTITY attribute of the EAP-Response/SIM/Start - packet. - - The peer MUST NOT modify the username portion of the fast - re-authentication identity, but the peer MAY modify the realm portion - or replace it with another realm portion. The peer might need to - modify the realm in order to influence the AAA routing, for example, - to make sure that the correct server is reached. It should be noted - that sharing the same fast re-authentication key among several - servers may have security risks, so changing the realm portion of the - NAI in order to change the EAP server is not desirable. - - - - - - -Haverinen & Salowey Informational [Page 32] - -RFC 4186 EAP-SIM Authentication January 2006 - - - Even if the peer uses a fast re-authentication identity, the server - may want to fall back on full authentication, for example because the - server does not recognize the fast re-authentication identity or does - not want to use fast re-authentication. In this case, the server - starts the full authentication procedure by issuing an - EAP-Request/SIM/Start packet. This packet always starts a full - authentication sequence if it does not include the AT_ANY_ID_REQ - attribute. If the server was not able to recover the peer's identity - from the fast re-authentication identity, the server includes either - the AT_FULLAUTH_ID_REQ or the AT_PERMANENT_ID_REQ attribute in this - EAP request. - -5.4. Fast Re-authentication Procedure - - Figure 8 illustrates the fast re-authentication procedure. In this - example, the optional protected success indication is not used. - Encrypted attributes are denoted with '*'. The peer uses its - re-authentication identity in the EAP-Response/Identity packet. As - discussed above, an alternative way to communicate the - re-authentication identity to the server is for the peer to use the - AT_IDENTITY attribute in the EAP-Response/SIM/Start message. This - latter case is not illustrated in the figure below, and it is only - possible when the server requests that the peer send its identity by - including the AT_ANY_ID_REQ attribute in the EAP-Request/SIM/Start - packet. - - If the server recognizes the identity as a valid fast - re-authentication identity, and if the server agrees to use fast - re-authentication, then the server sends the EAP-Request/SIM/ - Re-authentication packet to the peer. This packet MUST include the - encrypted AT_COUNTER attribute, with a fresh counter value, the - encrypted AT_NONCE_S attribute that contains a random number chosen - by the server, the AT_ENCR_DATA and the AT_IV attributes used for - encryption, and the AT_MAC attribute that contains a message - authentication code over the packet. The packet MAY also include an - encrypted AT_NEXT_REAUTH_ID attribute that contains the next fast - re-authentication identity. - - Fast re-authentication identities are one-time identities. If the - peer does not receive a new fast re-authentication identity, it MUST - use either the permanent identity or a pseudonym identity on the next - authentication to initiate full authentication. - - The peer verifies that AT_MAC is correct, and that the counter value - is fresh (greater than any previously used value). The peer MAY save - the next fast re-authentication identity from the encrypted - AT_NEXT_REAUTH_ID for next time. If all checks are successful, the - peer responds with the EAP-Response/SIM/Re-authentication packet, - - - -Haverinen & Salowey Informational [Page 33] - -RFC 4186 EAP-SIM Authentication January 2006 - - - including the AT_COUNTER attribute with the same counter value and - AT_MAC attribute. - - The server verifies the AT_MAC attribute and also verifies that the - counter value is the same that it used in the EAP-Request/SIM/ - Re-authentication packet. If these checks are successful, the - re-authentication has succeeded and the server sends the EAP-Success - packet to the peer. - - If protected success indications (Section 6.2) were used, the - EAP-Success packet would be preceded by an EAP-SIM notification - round. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Haverinen & Salowey Informational [Page 34] - -RFC 4186 EAP-SIM Authentication January 2006 - - - Peer Authenticator - | | - | EAP-Request/Identity | - |<------------------------------------------------------| - | | - | EAP-Response/Identity | - | (Includes a fast re-authentication identity) | - |------------------------------------------------------>| - | | - | +--------------------------------+ - | | Server recognizes the identity | - | | and agrees to use fast | - | | re-authentication | - | +--------------------------------+ - | | - : : - : : - : : - : : - | EAP-Request/SIM/Re-authentication | - | (AT_IV, AT_ENCR_DATA, *AT_COUNTER, | - | *AT_NONCE_S, *AT_NEXT_REAUTH_ID, AT_MAC) | - |<------------------------------------------------------| - | | - +-----------------------------------------------+ | - | Peer verifies AT_MAC and the freshness of | | - | the counter. Peer MAY store the new fast re- | | - | authentication identity for next re-auth. | | - +-----------------------------------------------+ | - | | - | EAP-Response/SIM/Re-authentication | - | (AT_IV, AT_ENCR_DATA, *AT_COUNTER with same value, | - | AT_MAC) | - |------------------------------------------------------>| - | +--------------------------------+ - | | Server verifies AT_MAC and | - | | the counter | - | +--------------------------------+ - | | - | EAP-Success | - |<------------------------------------------------------| - | | - - Figure 8: Fast Re-authentication - - - - - - - -Haverinen & Salowey Informational [Page 35] - -RFC 4186 EAP-SIM Authentication January 2006 - - -5.5. Fast Re-authentication Procedure when Counter Is Too Small - - If the peer does not accept the counter value of EAP-Request/SIM/ - Re-authentication, it indicates the counter synchronization problem - by including the encrypted AT_COUNTER_TOO_SMALL in EAP-Response/SIM/ - Re-authentication. The server responds with EAP-Request/SIM/Start to - initiate a normal full authentication procedure. This is illustrated - in Figure 9. Encrypted attributes are denoted with '*'. - - Peer Authenticator - | EAP-Request/SIM/Start | - | (AT_ANY_ID_REQ, AT_VERSION_LIST) | - |<------------------------------------------------------| - | | - | EAP-Response/SIM/Start | - | (AT_IDENTITY) | - | (Includes a fast re-authentication identity) | - |------------------------------------------------------>| - | | - | EAP-Request/SIM/Re-authentication | - | (AT_IV, AT_ENCR_DATA, *AT_COUNTER, | - | *AT_NONCE_S, *AT_NEXT_REAUTH_ID, AT_MAC) | - |<------------------------------------------------------| - +-----------------------------------------------+ | - | AT_MAC is valid but the counter is not fresh. | | - +-----------------------------------------------+ | - | | - | EAP-Response/SIM/Re-authentication | - | (AT_IV, AT_ENCR_DATA, *AT_COUNTER_TOO_SMALL, | - | *AT_COUNTER, AT_MAC) | - |------------------------------------------------------>| - | +----------------------------------------------+ - | | Server verifies AT_MAC but detects | - | | That peer has included AT_COUNTER_TOO_SMALL | - | +----------------------------------------------+ - | | - | EAP-Request/SIM/Start | - | (AT_VERSION_LIST) | - |<------------------------------------------------------| - +---------------------------------------------------------------+ - | Normal full authentication follows. | - +---------------------------------------------------------------+ - | | - - Figure 9: Fast Re-authentication, counter is not fresh - - - - - - -Haverinen & Salowey Informational [Page 36] - -RFC 4186 EAP-SIM Authentication January 2006 - - - In the figure above, the first three messages are similar to the - basic fast re-authentication case. When the peer detects that the - counter value is not fresh, it includes the AT_COUNTER_TOO_SMALL - attribute in EAP-Response/SIM/Re-authentication. This attribute - doesn't contain any data, but it is a request for the server to - initiate full authentication. In this case, the peer MUST ignore the - contents of the server's AT_NEXT_REAUTH_ID attribute. - - On receipt of AT_COUNTER_TOO_SMALL, the server verifies AT_MAC and - verifies that AT_COUNTER contains the same counter value as in the - EAP-Request/SIM/Re-authentication packet. If not, the server - terminates the authentication exchange by sending the - EAP-Request/SIM/Notification with AT_NOTIFICATION code "General - failure" (16384). If all checks on the packet are successful, the - server transmits a new EAP-Request/SIM/Start packet and the full - authentication procedure is performed as usual. Since the server - already knows the subscriber identity, it MUST NOT include - AT_ANY_ID_REQ, AT_FULLAUTH_ID_REQ, or AT_PERMANENT_ID_REQ in the - EAP-Request/SIM/Start. - - It should be noted that in this case, peer identity is only - transmitted in the AT_IDENTITY attribute at the beginning of the - whole EAP exchange. The fast re-authentication identity used in this - AT_IDENTITY attribute will be used in key derivation (see Section 7). - -6. EAP-SIM Notifications - -6.1. General - - EAP-SIM does not prohibit the use of the EAP Notifications as - specified in [RFC3748]. EAP Notifications can be used at any time in - the EAP-SIM exchange. It should be noted that EAP-SIM does not - protect EAP Notifications. EAP-SIM also specifies method-specific - EAP-SIM notifications that are protected in some cases. - - The EAP server can use EAP-SIM notifications to convey notifications - and result indications (Section 6.2) to the peer. - - The server MUST use notifications in cases discussed in - Section 6.3.2. When the EAP server issues an - EAP-Request/SIM/Notification packet to the peer, the peer MUST - process the notification packet. The peer MAY show a notification - message to the user and the peer MUST respond to the EAP server with - an EAP-Response/SIM/Notification packet, even if the peer did not - recognize the notification code. - - - - - - -Haverinen & Salowey Informational [Page 37] - -RFC 4186 EAP-SIM Authentication January 2006 - - - An EAP-SIM full authentication exchange or a fast re-authentication - exchange MUST NOT include more than one EAP-SIM notification round. - - The notification code is a 16-bit number. The most significant bit - is called the Success bit (S bit). The S bit specifies whether the - notification implies failure. The code values with the S bit set to - zero (code values 0...32767) are used on unsuccessful cases. The - receipt of a notification code from this range implies a failed EAP - exchange, so the peer can use the notification as a failure - indication. After receiving the EAP-Response/SIM/Notification for - these notification codes, the server MUST send the EAP-Failure - packet. - - The receipt of a notification code with the S bit set to one (values - 32768...65536) does not imply failure. Notification code "Success" - (32768) has been reserved as a general notification code to indicate - successful authentication. - - The second most significant bit of the notification code is called - the Phase bit (P bit). It specifies at which phase of the EAP-SIM - exchange the notification can be used. If the P bit is set to zero, - the notification can only be used after a successful - EAP/SIM/Challenge round in full authentication or a successful - EAP/SIM/Re-authentication round in reauthentication. A - re-authentication round is considered successful only if the peer has - successfully verified AT_MAC and AT_COUNTER attributes, and does not - include the AT_COUNTER_TOO_SMALL attribute in - EAP-Response/SIM/Re-authentication. - - If the P bit is set to one, the notification can only by used before - the EAP/SIM/Challenge round in full authentication, or before the - EAP/SIM/Re-authentication round in reauthentication. These - notifications can only be used to indicate various failure cases. In - other words, if the P bit is set to one, then the S bit MUST be set - to zero. - - Section 9.8 and Section 9.9 specify what other attributes must be - included in the notification packets. - - Some of the notification codes are authorization related and, hence, - are not usually considered part of the responsibility of an EAP - method. However, they are included as part of EAP-SIM because there - are currently no other ways to convey this information to the user in - a localizable way, and the information is potentially useful for the - user. An EAP-SIM server implementation may decide never to send - these EAP-SIM notifications. - - - - - -Haverinen & Salowey Informational [Page 38] - -RFC 4186 EAP-SIM Authentication January 2006 - - -6.2. Result Indications - - As discussed in Section 6.3, the server and the peer use explicit - error messages in all error cases. If the server detects an error - after successful authentication, the server uses an EAP-SIM - notification to indicate failure to the peer. In this case, the - result indication is integrity and replay protected. - - By sending an EAP-Response/SIM/Challenge packet or an - EAP-Response/SIM/Re-authentication packet (without - AT_COUNTER_TOO_SMALL), the peer indicates that it has successfully - authenticated the server and that the peer's local policy accepts the - EAP exchange. In other words, these packets are implicit success - indications from the peer to the server. - - EAP-SIM also supports optional protected success indications from the - server to the peer. If the EAP server wants to use protected success - indications, it includes the AT_RESULT_IND attribute in the - EAP-Request/SIM/Challenge or the EAP-Request/SIM/Re-authentication - packet. This attribute indicates that the EAP server would like to - use result indications in both successful and unsuccessful cases. If - the peer also wants this, the peer includes AT_RESULT_IND in - EAP-Response/SIM/Challenge or EAP-Response/SIM/Re-authentication. - The peer MUST NOT include AT_RESULT_IND if it did not receive - AT_RESULT_IND from the server. If both the peer and the server used - AT_RESULT_IND, then the EAP exchange is not complete yet, but an - EAP-SIM notification round will follow. The following EAP-SIM - notification may indicate either failure or success. - - Success indications with the AT_NOTIFICATION code "Success" (32768) - can only be used if both the server and the peer indicate they want - to use them with AT_RESULT_IND. If the server did not include - AT_RESULT_IND in the EAP-Request/SIM/Challenge or - EAP-Request/SIM/Re-authentication packet, or if the peer did not - include AT_RESULT_IND in the corresponding response packet, then the - server MUST NOT use protected success indications. - - Because the server uses the AT_NOTIFICATION code "Success" (32768) to - indicate that the EAP exchange has completed successfully, the EAP - exchange cannot fail when the server processes the EAP-SIM response - to this notification. Hence, the server MUST ignore the contents of - the EAP-SIM response it receives from the - EAP-Request/SIM/Notification with this code. Regardless of the - contents of the EAP-SIM response, the server MUST send EAP-Success as - the next packet. - - - - - - -Haverinen & Salowey Informational [Page 39] - -RFC 4186 EAP-SIM Authentication January 2006 - - -6.3. Error Cases - - This section specifies the operation of the peer and the server in - error cases. The subsections below require the EAP-SIM peer and - server to send an error packet (EAP-Response/SIM/Client-Error from - the peer or EAP-Request/SIM/Notification from the server) in error - cases. However, implementations SHOULD NOT rely upon the correct - error reporting behavior of the peer, authenticator, or the server. - It is possible for error and other messages to be lost in transit or - for a malicious participant to attempt to consume resources by not - issuing error messages. Both the peer and the EAP server SHOULD have - a mechanism to clean up state, even if an error message or - EAP-Success is not received after a timeout period. - -6.3.1. Peer Operation - - In general, if an EAP-SIM peer detects an error in a received EAP-SIM - packet, the EAP-SIM implementation responds with the - EAP-Response/SIM/Client-Error packet. In response to the - EAP-Response/SIM/Client-Error, the EAP server MUST issue the - EAP-Failure packet and the authentication exchange terminates. - - By default, the peer uses the client error code 0, "unable to process - packet". This error code is used in the following cases: - - o EAP exchange is not acceptable according to the peer's local - policy. - - o the peer is not able to parse the EAP request, i.e., the EAP - request is malformed. - - o the peer encountered a malformed attribute. - - o wrong attribute types or duplicate attributes have been included - in the EAP request. - - o a mandatory attribute is missing. - - o unrecognized, non-skippable attribute. - - o unrecognized or unexpected EAP-SIM Subtype in the EAP request. - - o A RAND challenge repeated in AT_RAND. - - o invalid AT_MAC. The peer SHOULD log this event. - - o invalid pad bytes in AT_PADDING. - - - - -Haverinen & Salowey Informational [Page 40] - -RFC 4186 EAP-SIM Authentication January 2006 - - - o the peer does not want to process AT_PERMANENT_ID_REQ. - - Separate error codes have been defined for the following error cases - in Section 10.19: - - As specified in Section 4.1, when processing the AT_VERSION_LIST - attribute, which lists the EAP-SIM versions supported by the server, - if the attribute does not include a version that is implemented by - the peer and allowed in the peer's security policy, then the peer - MUST send the EAP-Response/SIM/Client-Error packet with the error - code "unsupported version". - - If the number of RAND challenges is smaller than what is required by - peer's local policy when processing the AT_RAND attribute, the peer - MUST send the EAP-Response/SIM/Client-Error packet with the error - code "insufficient number of challenges". - - If the peer believes that the RAND challenges included in AT_RAND are - not fresh e.g., because it is capable of remembering some previously - used RANDs, the peer MUST send the EAP-Response/SIM/Client-Error - packet with the error code "RANDs are not fresh". - -6.3.2. Server Operation - - If an EAP-SIM server detects an error in a received EAP-SIM response, - the server MUST issue the EAP-Request/SIM/Notification packet with an - AT_NOTIFICATION code that implies failure. By default, the server - uses one of the general failure codes ("General failure after - authentication" (0), or "General failure" (16384)). The choice - between these two codes depends on the phase of the EAP-SIM exchange, - see Section 6. When the server issues an EAP- - Request/SIM/Notification that implies failure, the error cases - include the following: - - o the server is not able to parse the peer's EAP response - - o the server encounters a malformed attribute, a non-recognized - non-skippable attribute, or a duplicate attribute - - o a mandatory attribute is missing or an invalid attribute was - included - - o unrecognized or unexpected EAP-SIM Subtype in the EAP Response - - o invalid AT_MAC. The server SHOULD log this event. - - o invalid AT_COUNTER - - - - -Haverinen & Salowey Informational [Page 41] - -RFC 4186 EAP-SIM Authentication January 2006 - - -6.3.3. EAP-Failure - - The EAP-SIM server sends EAP-Failure in two cases: - - 1) In response to an EAP-Response/SIM/Client-Error packet the server - has received from the peer, or - - 2) Following an EAP-SIM notification round, when the AT_NOTIFICATION - code implies failure. - - The EAP-SIM server MUST NOT send EAP-Failure in cases other than - these two. However, it should be noted that even though the EAP-SIM - server would not send an EAP-Failure, an authorization decision that - happens outside EAP-SIM, such as in the AAA server or in an - intermediate AAA proxy, may result in a failed exchange. - - The peer MUST accept the EAP-Failure packet in case 1) and case 2), - above. The peer SHOULD silently discard the EAP-Failure packet in - other cases. - -6.3.4. EAP-Success - - On full authentication, the server can only send EAP-Success after - the EAP/SIM/Challenge round. The peer MUST silently discard any - EAP-Success packets if they are received before the peer has - successfully authenticated the server and sent the - EAP-Response/SIM/Challenge packet. - - If the peer did not indicate that it wants to use protected success - indications with AT_RESULT_IND (as discussed in Section 6.2) on full - authentication, then the peer MUST accept EAP-Success after a - successful EAP/SIM/Challenge round. - - If the peer indicated that it wants to use protected success - indications with AT_RESULT_IND (as discussed in Section 6.2), then - the peer MUST NOT accept EAP-Success after a successful - EAP/SIM/Challenge round. In this case, the peer MUST only accept - EAP-Success after receiving an EAP-SIM Notification with the - AT_NOTIFICATION code "Success" (32768). - - On fast re-authentication, EAP-Success can only be sent after the - EAP/SIM/Re-authentication round. The peer MUST silently discard any - EAP-Success packets if they are received before the peer has - successfully authenticated the server and sent the - EAP-Response/SIM/Re-authentication packet. - - If the peer did not indicate that it wants to use protected success - indications with AT_RESULT_IND (as discussed in Section 6.2) on fast - - - -Haverinen & Salowey Informational [Page 42] - -RFC 4186 EAP-SIM Authentication January 2006 - - - re-authentication, then the peer MUST accept EAP-Success after a - successful EAP/SIM/Re-authentication round. - - If the peer indicated that it wants to use protected success - indications with AT_RESULT_IND (as discussed in Section 6.2), then - the peer MUST NOT accept EAP-Success after a successful EAP/SIM/Re- - authentication round. In this case, the peer MUST only accept - EAP-Success after receiving an EAP-SIM Notification with the - AT_NOTIFICATION code "Success" (32768). - - If the peer receives an EAP-SIM notification (Section 6) that - indicates failure, then the peer MUST no longer accept the - EAP-Success packet, even if the server authentication was - successfully completed. - -7. Key Generation - - This section specifies how keying material is generated. - - On EAP-SIM full authentication, a Master Key (MK) is derived from the - underlying GSM authentication values (Kc keys), the NONCE_MT, and - other relevant context as follows. - - MK = SHA1(Identity|n*Kc| NONCE_MT| Version List| Selected Version) - - In the formula above, the "|" character denotes concatenation. - "Identity" denotes the peer identity string without any terminating - null characters. It is the identity from the last AT_IDENTITY - attribute sent by the peer in this exchange, or, if AT_IDENTITY was - not used, it is the identity from the EAP-Response/Identity packet. - The identity string is included as-is, without any changes. As - discussed in Section 4.2.2.2, relying on EAP-Response/Identity for - conveying the EAP-SIM peer identity is discouraged, and the server - SHOULD use the EAP-SIM method-specific identity attributes. - - The notation n*Kc in the formula above denotes the n Kc values - concatenated. The Kc keys are used in the same order as the RAND - challenges in AT_RAND attribute. NONCE_MT denotes the NONCE_MT value - (not the AT_NONCE_MT attribute, but only the nonce value). The - Version List includes the 2-byte-supported version numbers from - AT_VERSION_LIST, in the same order as in the attribute. The Selected - Version is the 2-byte selected version from AT_SELECTED_VERSION. - Network byte order is used, just as in the attributes. The hash - function SHA-1 is specified in [SHA-1]. If several EAP/SIM/Start - roundtrips are used in an EAP-SIM exchange, then the NONCE_MT, - Version List and Selected version from the last EAP/SIM/Start round - are used, and the previous EAP/SIM/Start rounds are ignored. - - - - -Haverinen & Salowey Informational [Page 43] - -RFC 4186 EAP-SIM Authentication January 2006 - - - The Master Key is fed into a Pseudo-Random number Function (PRF) - which generates separate Transient EAP Keys (TEKs) for protecting - EAP-SIM packets, as well as a Master Session Key (MSK) for link layer - security, and an Extended Master Session Key (EMSK) for other - purposes. On fast re-authentication, the same TEKs MUST be used for - protecting EAP packets, but a new MSK and a new EMSK MUST be derived - from the original MK and from new values exchanged in the fast - re-authentication. - - EAP-SIM requires two TEKs for its own purposes; the authentication - key K_aut is to be used with the AT_MAC attribute, and the encryption - key K_encr is to be used with the AT_ENCR_DATA attribute. The same - K_aut and K_encr keys are used in full authentication and subsequent - fast re-authentications. - - Key derivation is based on the random number generation specified in - NIST Federal Information Processing Standards (FIPS) Publication - 186-2 [PRF]. The pseudo-random number generator is specified in the - change notice 1 (2001 October 5) of [PRF] (Algorithm 1). As - specified in the change notice (page 74), when Algorithm 1 is used as - a general-purpose pseudo-random number generator, the "mod q" term in - step 3.3 is omitted. The function G used in the algorithm is - constructed via the Secure Hash Standard, as specified in Appendix - 3.3 of the standard. It should be noted that the function G is very - similar to SHA-1, but the message padding is different. Please refer - to [PRF] for full details. For convenience, the random number - algorithm with the correct modification is cited in Appendix B. - - 160-bit XKEY and XVAL values are used, so b = 160. On each full - authentication, the Master Key is used as the initial secret seed-key - XKEY. The optional user input values (XSEED_j) in step 3.1 are set - to zero. - - On full authentication, the resulting 320-bit random numbers (x_0, - x_1, ..., x_m-1) are concatenated and partitioned into suitable-sized - chunks and used as keys in the following order: K_encr (128 bits), - K_aut (128 bits), Master Session Key (64 bytes), Extended Master - Session Key (64 bytes). - - On fast re-authentication, the same pseudo-random number generator - can be used to generate a new Master Session Key and a new Extended - Master Session Key. The seed value XKEY' is calculated as follows: - - XKEY' = SHA1(Identity|counter|NONCE_S| MK) - - In the formula above, the Identity denotes the fast re-authentication - identity, without any terminating null characters, from the - AT_IDENTITY attribute of the EAP-Response/SIM/Start packet, or, if - - - -Haverinen & Salowey Informational [Page 44] - -RFC 4186 EAP-SIM Authentication January 2006 - - - EAP-Response/SIM/Start was not used on fast re-authentication, it - denotes the identity string from the EAP-Response/Identity packet. - The counter denotes the counter value from the AT_COUNTER attribute - used in the EAP-Response/SIM/Re-authentication packet. The counter - is used in network byte order. NONCE_S denotes the 16-byte NONCE_S - value from the AT_NONCE_S attribute used in the - EAP-Request/SIM/Re-authentication packet. The MK is the Master Key - derived on the preceding full authentication. - - On fast re-authentication, the pseudo-random number generator is run - with the new seed value XKEY', and the resulting 320-bit random - numbers (x_0, x_1, ..., x_m-1) are concatenated and partitioned into - two 64-byte chunks and used as the new 64-byte Master Session Key and - the new 64-byte Extended Master Session Key. Note that because - K_encr and K_aut are not derived on fast re-authentication, the - Master Session Key and the Extended Master Session key are obtained - from the beginning of the key stream (x_0, x_1, ...). - - The first 32 bytes of the MSK can be used as the Pairwise Master Key - (PMK) for IEEE 802.11i. - - When the RADIUS attributes specified in [RFC2548] are used to - transport keying material, then the first 32 bytes of the MSK - correspond to MS-MPPE-RECV-KEY and the second 32 bytes to - MS-MPPE-SEND-KEY. In this case, only 64 bytes of keying material - (the MSK) are used. - - When generating the initial Master Key, the hash function is used as - a mixing function to combine several session keys (Kc's) generated by - the GSM authentication procedure and the random number NONCE_MT into - a single session key. There are several reasons for this. The - current GSM session keys are, at most, 64 bits, so two or more of - them are needed to generate a longer key. By using a one-way - function to combine the keys, we are assured that, even if an - attacker managed to learn one of the EAP-SIM session keys, it - wouldn't help him in learning the original GSM Kc's. In addition, - since we include the random number NONCE_MT in the calculation, the - peer is able to verify that the EAP-SIM packets it receives from the - network are fresh and not replays (also see Section 11). - -8. Message Format and Protocol Extensibility - -8.1. Message Format - - As specified in [RFC3748], EAP packets begin with the Code, - Identifiers, Length, and Type fields, which are followed by EAP- - method-specific Type-Data. The Code field in the EAP header is set - to 1 for EAP requests, and to 2 for EAP Responses. The usage of the - - - -Haverinen & Salowey Informational [Page 45] - -RFC 4186 EAP-SIM Authentication January 2006 - - - Length and Identifier fields in the EAP header are also specified in - [RFC3748]. In EAP-SIM, the Type field is set to 18. - - In EAP-SIM, the Type-Data begins with an EAP-SIM header that consists - of a 1-octet Subtype field and a 2-octet reserved field. The Subtype - values used in EAP-SIM are defined in the IANA considerations section - of the EAP-AKA specification [EAP-AKA]. The formats of the EAP - header and the EAP-SIM header are shown below. - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Code | Identifier | Length | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Type | Subtype | Reserved | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - The rest of the Type-Data that immediately follows the EAP-SIM header - consists of attributes that are encoded in Type, Length, Value - format. The figure below shows the generic format of an attribute. - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Type | Length | Value... - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - - Attribute Type - - Indicates the particular type of attribute. The attribute type - values are listed in the IANA considerations section of the - EAP-AKA specification [EAP-AKA]. - - Length - - Indicates the length of this attribute in multiples of four - bytes. The maximum length of an attribute is 1024 bytes. The - length includes the Attribute Type and Length bytes. - - Value - - The particular data associated with this attribute. This field - is always included and it may be two or more bytes in length. - The type and length fields determine the format and length - of the value field. - - - - - -Haverinen & Salowey Informational [Page 46] - -RFC 4186 EAP-SIM Authentication January 2006 - - - Attributes numbered within the range 0 through 127 are called - non-skippable attributes. When an EAP-SIM peer encounters a - non-skippable attribute that the peer does not recognize, the peer - MUST send the EAP-Response/SIM/Client-Error packet, which terminates - the authentication exchange. If an EAP-SIM server encounters a - non-skippable attribute that the server does not recognize, then the - server sends the EAP-Request/SIM/Notification packet with an - AT_NOTIFICATION code, which implies general failure ("General failure - after authentication" (0), or "General failure" (16384), depending on - the phase of the exchange), which terminates the authentication - exchange. - - Attributes within the range of 128 through 255 are called skippable - attributes. When a skippable attribute is encountered and is not - recognized, it is ignored. The rest of the attributes and message - data MUST still be processed. The Length field of the attribute is - used to skip the attribute value in searching for the next attribute. - - Unless otherwise specified, the order of the attributes in an EAP-SIM - message is insignificant and an EAP-SIM implementation should not - assume a certain order to be used. - - Attributes can be encapsulated within other attributes. In other - words, the value field of an attribute type can be specified to - contain other attributes. - -8.2. Protocol Extensibility - - EAP-SIM can be extended by specifying new attribute types. If - skippable attributes are used, it is possible to extend the protocol - without breaking old implementations. - - However, any new attributes added to the EAP-Request/SIM/Start or - EAP-Response/SIM/Start packets would not be integrity-protected. - Therefore, these messages MUST NOT be extended in the current version - of EAP-SIM. If the list of supported EAP-SIM versions in the - AT_VERSION_LIST does not include versions other than 1, then the - server MUST NOT include attributes other than those specified in this - document in the EAP-Request/SIM/Start message. Note that future - versions of this protocol might specify new attributes for - EAP-Request/SIM/Start and still support version 1 of the protocol. - In this case, the server might send an EAP-Request/SIM/Start message - that includes new attributes and indicates support for protocol - version 1 and other versions in the AT_VERSION_LIST attribute. If - the peer selects version 1, then the peer MUST ignore any other - attributes included in EAP-Request/SIM/Start, other than those - specified in this document. If the selected EAP-SIM version in - peer's AT_SELECTED_VERSION is 1, then the peer MUST NOT include other - - - -Haverinen & Salowey Informational [Page 47] - -RFC 4186 EAP-SIM Authentication January 2006 - - - attributes aside from those specified in this document in the - EAP-Response/SIM/Start message. - - When specifying new attributes, it should be noted that EAP-SIM does - not support message fragmentation. Hence, the sizes of the new - extensions MUST be limited so that the maximum transfer unit (MTU) of - the underlying lower layer is not exceeded. According to [RFC3748], - lower layers must provide an EAP MTU of 1020 bytes or greater, so any - extensions to EAP-SIM SHOULD NOT exceed the EAP MTU of 1020 bytes. - - Because EAP-SIM supports version negotiation, new versions of the - protocol can also be specified by using a new version number. - -9. Messages - - This section specifies the messages used in EAP-SIM. It specifies - when a message may be transmitted or accepted, which attributes are - allowed in a message, which attributes are required in a message, and - other message-specific details. The general message format is - specified in Section 8.1. - -9.1. EAP-Request/SIM/Start - - In full authentication the first SIM-specific EAP Request is - EAP-Request/SIM/Start. The EAP/SIM/Start roundtrip is used for two - purposes. In full authentication this packet is used to request the - peer to send the AT_NONCE_MT attribute to the server. In addition, - as specified in Section 4.2, the Start round trip may be used by the - server for obtaining the peer identity. As discussed in Section 4.2, - several Start rounds may be required to obtain a valid peer identity. - - The server MUST always include the AT_VERSION_LIST attribute. - - The server MAY include one of the following identity-requesting - attributes: AT_PERMANENT_ID_REQ, AT_FULLAUTH_ID_REQ, or - AT_ANY_ID_REQ. These three attributes are mutually exclusive, so the - server MUST NOT include more than one of the attributes. - - If the server has received a response from the peer, it MUST NOT - issue a new EAP-Request/SIM/Start packet if it has previously issued - an EAP-Request/SIM/Start message either without any identity - requesting attributes or with the AT_PERMANENT_ID_REQ attribute. - - If the server has received a response from the peer, it MUST NOT - issue a new EAP-Request/SIM/Start packet with the AT_ANY_ID_REQ or - AT_FULLAUTH_ID_REQ attributes if it has previously issued an - EAP-Request/SIM/Start message with the AT_FULLAUTH_ID_REQ attribute. - - - - -Haverinen & Salowey Informational [Page 48] - -RFC 4186 EAP-SIM Authentication January 2006 - - - If the server has received a response from the peer, it MUST NOT - issue a new EAP-Request/SIM/Start packet with the AT_ANY_ID_REQ - attribute if the server has previously issued an - EAP-Request/SIM/Start message with the AT_ANY_ID_REQ attribute. - - This message MUST NOT include AT_MAC, AT_IV, or AT_ENCR_DATA. - -9.2. EAP-Response/SIM/Start - - The peer sends EAP-Response/SIM/Start in response to a valid - EAP-Request/SIM/Start from the server. - - If and only if the server's EAP-Request/SIM/Start includes one of the - identity-requesting attributes, then the peer MUST include the - AT_IDENTITY attribute. The usage of AT_IDENTITY is defined in - Section 4.2. - - The AT_NONCE_MT attribute MUST NOT be included if the AT_IDENTITY - with a fast re-authentication identity is present for fast - re-authentication. AT_NONCE_MT MUST be included in all other cases - (full authentication). - - The AT_SELECTED_VERSION attribute MUST NOT be included if the - AT_IDENTITY attribute with a fast re-authentication identity is - present for fast re-authentication. In all other cases, - AT_SELECTED_VERSION MUST be included (full authentication). This - attribute is used in version negotiation, as specified in - Section 4.1. - - This message MUST NOT include AT_MAC, AT_IV, or AT_ENCR_DATA. - -9.3. EAP-Request/SIM/Challenge - - The server sends the EAP-Request/SIM/Challenge after receiving a - valid EAP-Response/SIM/Start that contains AT_NONCE_MT and - AT_SELECTED_VERSION, and after successfully obtaining the subscriber - identity. - - The AT_RAND attribute MUST be included. - - The AT_RESULT_IND attribute MAY be included. The usage of this - attribute is discussed in Section 6.2. - - The AT_MAC attribute MUST be included. For - EAP-Request/SIM/Challenge, the MAC code is calculated over the - following data: - - EAP packet| NONCE_MT - - - -Haverinen & Salowey Informational [Page 49] - -RFC 4186 EAP-SIM Authentication January 2006 - - - The EAP packet is represented as specified in Section 8.1. It is - followed by the 16-byte NONCE_MT value from the peer's AT_NONCE_MT - attribute. - - The EAP-Request/SIM/Challenge packet MAY include encrypted attributes - for identity privacy and for communicating the next fast - re-authentication identity. In this case, the AT_IV and AT_ENCR_DATA - attributes are included (Section 10.12). - - The plaintext of the AT_ENCR_DATA value field consists of nested - attributes. The nested attributes MAY include AT_PADDING (as - specified in Section 10.12). If the server supports identity privacy - and wants to communicate a pseudonym to the peer for the next full - authentication, then the nested encrypted attributes include the - AT_NEXT_PSEUDONYM attribute. If the server supports - re-authentication and wants to communicate a fast re-authentication - identity to the peer, then the nested encrypted attributes include - the AT_NEXT_REAUTH_ID attribute. - - When processing this message, the peer MUST process AT_RAND before - processing other attributes. Only if AT_RAND is verified to be - valid, the peer derives keys and verifies AT_MAC. The operation in - case an error occurs is specified in Section 6.3.1. - -9.4. EAP-Response/SIM/Challenge - - The peer sends EAP-Response/SIM/Challenge in response to a valid - EAP-Request/SIM/Challenge. - - Sending this packet indicates that the peer has successfully - authenticated the server and that the EAP exchange will be accepted - by the peer's local policy. Hence, if these conditions are not met, - then the peer MUST NOT send EAP-Response/SIM/Challenge, but the peer - MUST send EAP-Response/SIM/Client-Error. - - The AT_MAC attribute MUST be included. For EAP- - Response/SIM/Challenge, the MAC code is calculated over the following - data: - - EAP packet| n*SRES - - The EAP packet is represented as specified in Section 8.1. The EAP - packet bytes are immediately followed by the two or three SRES values - concatenated, denoted above with the notation n*SRES. The SRES - values are used in the same order as the corresponding RAND - challenges in the server's AT_RAND attribute. - - - - - -Haverinen & Salowey Informational [Page 50] - -RFC 4186 EAP-SIM Authentication January 2006 - - - The AT_RESULT_IND attribute MAY be included if it was included in - EAP-Request/SIM/Challenge. The usage of this attribute is discussed - in Section 6.2. - - Later versions of this protocol MAY make use of the AT_ENCR_DATA and - AT_IV attributes in this message to include encrypted (skippable) - attributes. The EAP server MUST process EAP-Response/SIM/Challenge - messages that include these attributes even if the server did not - implement these optional attributes. - -9.5. EAP-Request/SIM/Re-authentication - - The server sends the EAP-Request/SIM/Re-authentication message if it - wants to use fast re-authentication, and if it has received a valid - fast re-authentication identity in EAP-Response/Identity or - EAP-Response/SIM/Start. - - AT_MAC MUST be included. No message-specific data is included in the - MAC calculation. See Section 10.14. - - The AT_RESULT_IND attribute MAY be included. The usage of this - attribute is discussed in Section 6.2. - - The AT_IV and AT_ENCR_DATA attributes MUST be included. The - plaintext consists of the following nested encrypted attributes, - which MUST be included: AT_COUNTER and AT_NONCE_S. In addition, the - nested encrypted attributes MAY include the following attributes: - AT_NEXT_REAUTH_ID and AT_PADDING. - -9.6. EAP-Response/SIM/Re-authentication - - The client sends the EAP-Response/SIM/Re-authentication packet in - response to a valid EAP-Request/SIM/Re-authentication. - - The AT_MAC attribute MUST be included. For - EAP-Response/SIM/Re-authentication, the MAC code is calculated over - the following data: - - EAP packet| NONCE_S - - The EAP packet is represented as specified in Section 8.1. It is - followed by the 16-byte NONCE_S value from the server's AT_NONCE_S - attribute. - - The AT_IV and AT_ENCR_DATA attributes MUST be included. The nested - encrypted attributes MUST include the AT_COUNTER attribute. The - AT_COUNTER_TOO_SMALL attribute MAY be included in the nested - - - - -Haverinen & Salowey Informational [Page 51] - -RFC 4186 EAP-SIM Authentication January 2006 - - - encrypted attributes, and it is included in cases specified in - Section 5. The AT_PADDING attribute MAY be included. - - The AT_RESULT_IND attribute MAY be included if it was included in - EAP-Request/SIM/Re-authentication. The usage of this attribute is - discussed in Section 6.2. - - Sending this packet without AT_COUNTER_TOO_SMALL indicates that the - peer has successfully authenticated the server and that the EAP - exchange will be accepted by the peer's local policy. Hence, if - these conditions are not met, then the peer MUST NOT send - EAP-Response/SIM/Re-authentication, but the peer MUST send - EAP-Response/SIM/Client-Error. - -9.7. EAP-Response/SIM/Client-Error - - The peer sends EAP-Response/SIM/Client-Error in error cases, as - specified in Section 6.3.1. - - The AT_CLIENT_ERROR_CODE attribute MUST be included. - - The AT_MAC, AT_IV, or AT_ENCR_DATA attributes MUST NOT be used with - this packet. - -9.8. EAP-Request/SIM/Notification - - The usage of this message is specified in Section 6. The - AT_NOTIFICATION attribute MUST be included. - - The AT_MAC attribute MUST be included if the P bit of the - notification code in AT_NOTIFICATION is set to zero, and MUST NOT be - included in cases when the P bit is set to one. The P bit is - discussed in Section 6. - - No message-specific data is included in the MAC calculation. See - Section 10.14. - - If EAP-Request/SIM/Notification is used on a fast re-authentication - exchange, and if the P bit in AT_NOTIFICATION is set to zero, then - AT_COUNTER is used for replay protection. In this case, the - AT_ENCR_DATA and AT_IV attributes MUST be included, and the - encapsulated plaintext attributes MUST include the AT_COUNTER - attribute. The counter value included in AT_COUNTER MUST be the same - as in the EAP-Request/SIM/Re-authentication packet on the same fast - re-authentication exchange. - - - - - - -Haverinen & Salowey Informational [Page 52] - -RFC 4186 EAP-SIM Authentication January 2006 - - -9.9. EAP-Response/SIM/Notification - - The usage of this message is specified in Section 6. This packet is - an acknowledgement of EAP-Request/SIM/Notification. - - The AT_MAC attribute MUST be included in cases when the P bit of the - notification code in AT_NOTIFICATION of EAP-Request/SIM/Notification - is set to zero, and MUST NOT be included in cases when the P bit is - set to one. The P bit is discussed in Section 6. - - No message-specific data is included in the MAC calculation, see - Section 10.14. - - If EAP-Request/SIM/Notification is used on a fast re-authentication - exchange, and if the P bit in AT_NOTIFICATION is set to zero, then - AT_COUNTER is used for replay protection. In this case, the - AT_ENCR_DATA and AT_IV attributes MUST be included, and the - encapsulated plaintext attributes MUST include the AT_COUNTER - attribute. The counter value included in AT_COUNTER MUST be the same - as in the EAP-Request/SIM/Re-authentication packet on the same fast - re-authentication exchange. - -10. Attributes - - This section specifies the format of message attributes. The - attribute type numbers are specified in the IANA considerations - section of the EAP-AKA specification [EAP-AKA]. - -10.1. Table of Attributes - - The following table provides a guide to which attributes may be found - in which kinds of messages, and in what quantity. Messages are - denoted with numbers in parentheses as follows: (1) - EAP-Request/SIM/Start, (2) EAP-Response/SIM/Start, (3) - EAP-Request/SIM/Challenge, (4) EAP-Response/SIM/Challenge, (5) - EAP-Request/SIM/Notification, (6) EAP-Response/SIM/Notification, (7) - EAP-Response/SIM/Client-Error, (8) EAP-Request/SIM/Re-authentication, - and (9) EAP-Response/SIM/Re-authentication. The column denoted with - "Encr" indicates whether the attribute is a nested attribute that - MUST be included within AT_ENCR_DATA, and the column denoted with - "Skip" indicates whether the attribute is a skippable attribute. - - "0" indicates that the attribute MUST NOT be included in the message, - "1" indicates that the attribute MUST be included in the message, - "0-1" indicates that the attribute is sometimes included in the - message, and "0*" indicates that the attribute is not included in the - message in cases specified in this document, but MAY be included in - future versions of the protocol. - - - -Haverinen & Salowey Informational [Page 53] - -RFC 4186 EAP-SIM Authentication January 2006 - - - Attribute (1) (2) (3) (4) (5) (6) (7) (8) (9) Encr Skip - AT_VERSION_LIST 1 0 0 0 0 0 0 0 0 N N - AT_SELECTED_VERSION 0 0-1 0 0 0 0 0 0 0 N N - AT_NONCE_MT 0 0-1 0 0 0 0 0 0 0 N N - AT_PERMANENT_ID_REQ 0-1 0 0 0 0 0 0 0 0 N N - AT_ANY_ID_REQ 0-1 0 0 0 0 0 0 0 0 N N - AT_FULLAUTH_ID_REQ 0-1 0 0 0 0 0 0 0 0 N N - AT_IDENTITY 0 0-1 0 0 0 0 0 0 0 N N - AT_RAND 0 0 1 0 0 0 0 0 0 N N - AT_NEXT_PSEUDONYM 0 0 0-1 0 0 0 0 0 0 Y Y - AT_NEXT_REAUTH_ID 0 0 0-1 0 0 0 0 0-1 0 Y Y - AT_IV 0 0 0-1 0* 0-1 0-1 0 1 1 N Y - AT_ENCR_DATA 0 0 0-1 0* 0-1 0-1 0 1 1 N Y - AT_PADDING 0 0 0-1 0* 0-1 0-1 0 0-1 0-1 Y N - AT_RESULT_IND 0 0 0-1 0-1 0 0 0 0-1 0-1 N Y - AT_MAC 0 0 1 1 0-1 0-1 0 1 1 N N - AT_COUNTER 0 0 0 0 0-1 0-1 0 1 1 Y N - AT_COUNTER_TOO_SMALL 0 0 0 0 0 0 0 0 0-1 Y N - AT_NONCE_S 0 0 0 0 0 0 0 1 0 Y N - AT_NOTIFICATION 0 0 0 0 1 0 0 0 0 N N - AT_CLIENT_ERROR_CODE 0 0 0 0 0 0 1 0 0 N N - - It should be noted that attributes AT_PERMANENT_ID_REQ, - AT_ANY_ID_REQ, and AT_FULLAUTH_ID_REQ are mutually exclusive; only - one of them can be included at the same time. If one of the - attributes AT_IV and AT_ENCR_DATA is included, then both of the - attributes MUST be included. - -10.2. AT_VERSION_LIST - - The format of the AT_VERSION_LIST attribute is shown below. - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | AT_VERSION_L..| Length | Actual Version List Length | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Supported Version 1 | Supported Version 2 | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - . . - . . - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Supported Version N | Padding | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - This attribute is used in version negotiation, as specified in - Section 4.1. The attribute contains the version numbers supported by - the EAP-SIM server. The server MUST only include versions that it - - - -Haverinen & Salowey Informational [Page 54] - -RFC 4186 EAP-SIM Authentication January 2006 - - - implements and that are allowed in its security policy. The server - SHOULD list the versions in the order of preference, with the most - preferred versions listed first. At least one version number MUST be - included. The version number for the protocol described in this - document is one (0001 hexadecimal). - - The value field of this attribute begins with 2-byte Actual Version - List Length, which specifies the length of the Version List in bytes, - not including the Actual Version List Length attribute length. This - field is followed by the list of the versions supported by the - server, which each have a length of 2 bytes. For example, if there - is only one supported version, then the Actual Version List Length is - 2. Because the length of the attribute must be a multiple of 4 - bytes, the sender pads the value field with zero bytes when - necessary. - -10.3. AT_SELECTED_VERSION - - The format of the AT_SELECTED_VERSION attribute is shown below. - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | AT_SELECTED...| Length = 1 | Selected Version | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - This attribute is used in version negotiation, as specified in - Section 4.1. The value field of this attribute contains a two-byte - version number, which indicates the EAP-SIM version that the peer - wants to use. - -10.4. AT_NONCE_MT - - The format of the AT_NONCE_MT attribute is shown below. - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - |AT_NONCE_MT | Length = 5 | Reserved | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | | - | NONCE_MT | - | | - | | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - - - - - -Haverinen & Salowey Informational [Page 55] - -RFC 4186 EAP-SIM Authentication January 2006 - - - The value field of the NONCE_MT attribute contains two reserved bytes - followed by a random number freshly generated by the peer (16 bytes - long) for this EAP-SIM authentication exchange. The random number is - used as a seed value for the new keying material. The reserved bytes - are set to zero upon sending and ignored upon reception. - - The peer MUST NOT re-use the NONCE_MT value from a previous EAP-SIM - authentication exchange. If an EAP-SIM exchange includes several - EAP/SIM/Start rounds, then the peer SHOULD use the same NONCE_MT - value in all EAP-Response/SIM/Start packets. The peer SHOULD use a - good source of randomness to generate NONCE_MT. Please see [RFC4086] - for more information about generating random numbers for security - applications. - -10.5. AT_PERMANENT_ID_REQ - - The format of the AT_PERMANENT_ID_REQ attribute is shown below. - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - |AT_PERM..._REQ | Length = 1 | Reserved | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - The use of the AT_PERMANENT_ID_REQ is defined in Section 4.2. The - value field contains only two reserved bytes, which are set to zero - on sending and ignored on reception. - -10.6. AT_ANY_ID_REQ - - The format of the AT_ANY_ID_REQ attribute is shown below. - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - |AT_ANY_ID_REQ | Length = 1 | Reserved | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - The use of the AT_ANY_ID_REQ is defined in Section 4.2. The value - field contains only two reserved bytes, which are set to zero on - sending and ignored on reception. - - - - - - - - - - -Haverinen & Salowey Informational [Page 56] - -RFC 4186 EAP-SIM Authentication January 2006 - - -10.7. AT_FULLAUTH_ID_REQ - - The format of the AT_FULLAUTH_ID_REQ attribute is shown below. - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - |AT_FULLAUTH_...| Length = 1 | Reserved | - +---------------+---------------+-------------------------------+ - - The use of the AT_FULLAUTH_ID_REQ is defined in Section 4.2. The - value field contains only two reserved bytes, which are set to zero - on sending and ignored on reception. - -10.8. AT_IDENTITY - - The format of the AT_IDENTITY attribute is shown below. - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | AT_IDENTITY | Length | Actual Identity Length | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | | - . Identity (optional) . - . . - | | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - The use of the AT_IDENTITY is defined in Section 4.2. The value - field of this attribute begins with a 2-byte actual identity length, - which specifies the length of the identity in bytes. This field is - followed by the subscriber identity of the indicated actual length. - The identity is the permanent identity, a pseudonym identity, or a - fast re-authentication identity. The identity format is specified in - Section 4.2.1. The same identity format is used in the AT_IDENTITY - attribute and the EAP-Response/Identity packet, with the exception - that the peer MUST NOT decorate the identity it includes in - AT_IDENTITY. The identity does not include any terminating null - characters. Because the length of the attribute must be a multiple - of 4 bytes, the sender pads the identity with zero bytes when - necessary. - - - - - - - - - -Haverinen & Salowey Informational [Page 57] - -RFC 4186 EAP-SIM Authentication January 2006 - - -10.9. AT_RAND - - The format of the AT_RAND attribute is shown below. - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | AT_RAND | Length | Reserved | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | | - . n*RAND . - . . - | | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - The value field of this attribute contains two reserved bytes - followed by n GSM RANDs, each 16 bytes long. The value of n can be - determined by the attribute length. The reserved bytes are set to - zero upon sending and ignored upon reception. - - The number of RAND challenges (n) MUST be two or three. The peer - MUST verify that the number of RAND challenges is sufficient - according to the peer's policy. The server MUST use different RAND - values. In other words, a RAND value can only be included once in - AT_RAND. When processing the AT_RAND attribute, the peer MUST check - that the RANDs are different. - - The EAP server MUST obtain fresh RANDs for each EAP-SIM full - authentication exchange. More specifically, the server MUST consider - RANDs it included in AT_RAND to be consumed if the server receives an - EAP-Response/SIM/Challenge packet with a valid AT_MAC, or an - EAP-Response/SIM/Client-Error with the code "insufficient number of - challenges" or "RANDs are not fresh". However, in other cases (if - the server does not receive a response to its - EAP-Request/SIM/Challenge packet, or if the server receives a - response other than the cases listed above), the server does not need - to consider the RANDs to be consumed, and the server MAY re-use the - RANDs in the AT_RAND attribute of the next full authentication - attempt. - - - - - - - - - - - - -Haverinen & Salowey Informational [Page 58] - -RFC 4186 EAP-SIM Authentication January 2006 - - -10.10. AT_NEXT_PSEUDONYM - - The format of the AT_NEXT_PSEUDONYM attribute is shown below. - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | AT_NEXT_PSEU..| Length | Actual Pseudonym Length | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | | - . Next Pseudonym . - . . - | | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - The value field of this attribute begins with the 2-byte actual - pseudonym length, which specifies the length of the following - pseudonym in bytes. This field is followed by a pseudonym username - that the peer can use in the next authentication. The username MUST - NOT include any realm portion. The username does not include any - terminating null characters. Because the length of the attribute - must be a multiple of 4 bytes, the sender pads the pseudonym with - zero bytes when necessary. The username encoding MUST follow the - UTF-8 transformation format [RFC3629]. This attribute MUST always be - encrypted by encapsulating it within the AT_ENCR_DATA attribute. - -10.11. AT_NEXT_REAUTH_ID - - The format of the AT_NEXT_REAUTH_ID attribute is shown below. - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | AT_NEXT_REAU..| Length | Actual Re-Auth Identity Length| - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | | - . Next Fast Re-authentication Username . - . . - | | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - The value field of this attribute begins with the 2-byte actual - re-authentication identity length which specifies the length of the - following fast re-authentication identity in bytes. This field is - followed by a fast re-authentication identity that the peer can use - in the next fast re-authentication, as described in Section 5. In - environments where a realm portion is required, the fast - re-authentication identity includes both a username portion and a - - - -Haverinen & Salowey Informational [Page 59] - -RFC 4186 EAP-SIM Authentication January 2006 - - - realm name portion. The fast re-authentication identity does not - include any terminating null characters. Because the length of the - attribute must be a multiple of 4 bytes, the sender pads the fast - re-authentication identity with zero bytes when necessary. The - identity encoding MUST follow the UTF-8 transformation format - [RFC3629]. This attribute MUST always be encrypted by encapsulating - it within the AT_ENCR_DATA attribute. - -10.12. AT_IV, AT_ENCR_DATA, and AT_PADDING - - AT_IV and AT_ENCR_DATA attributes can be used to transmit encrypted - information between the EAP-SIM peer and server. - - The value field of AT_IV contains two reserved bytes followed by a - 16-byte initialization vector required by the AT_ENCR_DATA attribute. - The reserved bytes are set to zero when sending and ignored on - reception. The AT_IV attribute MUST be included if and only if the - AT_ENCR_DATA is included. Section 6.3 specifies the operation if a - packet that does not meet this condition is encountered. - - The sender of the AT_IV attribute chooses the initialization vector - at random. The sender MUST NOT re-use the initialization vector - value from previous EAP-SIM packets. The sender SHOULD use a good - source of randomness to generate the initialization vector. Please - see [RFC4086] for more information about generating random numbers - for security applications. The format of AT_IV is shown below. - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | AT_IV | Length = 5 | Reserved | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | | - | Initialization Vector | - | | - | | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - The value field of the AT_ENCR_DATA attribute consists of two - reserved bytes followed by cipher text bytes encrypted using the - Advanced Encryption Standard (AES) [AES] with a 128-bit key in the - Cipher Block Chaining (CBC) mode of operation using the - initialization vector from the AT_IV attribute. The reserved bytes - are set to zero when sending and ignored on reception. Please see - [CBC] for a description of the CBC mode. The format of the - AT_ENCR_DATA attribute is shown below. - - - - - -Haverinen & Salowey Informational [Page 60] - -RFC 4186 EAP-SIM Authentication January 2006 - - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | AT_ENCR_DATA | Length | Reserved | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | | - . Encrypted Data . - . . - | | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - The derivation of the encryption key (K_encr) is specified in Section - 7. - - The plaintext consists of nested EAP-SIM attributes. - - The encryption algorithm requires the length of the plaintext to be a - multiple of 16 bytes. The sender may need to include the AT_PADDING - attribute as the last attribute within AT_ENCR_DATA. The AT_PADDING - attribute is not included if the total length of other nested - attributes within the AT_ENCR_DATA attribute is a multiple of 16 - bytes. As usual, the Length of the Padding attribute includes the - Attribute Type and Attribute Length fields. The length of the - Padding attribute is 4, 8, or 12 bytes. It is chosen so that the - length of the value field of the AT_ENCR_DATA attribute becomes a - multiple of 16 bytes. The actual pad bytes in the value field are - set to zero (00 hexadecimal) on sending. The recipient of the - message MUST verify that the pad bytes are set to zero. If this - verification fails on the peer, then it MUST send the - EAP-Response/SIM/Client-Error packet with the error code "unable to - process packet" to terminate the authentication exchange. If this - verification fails on the server, then the server sends the peer the - EAP-Request/SIM/Notification packet with an AT_NOTIFICATION code that - implies failure to terminate the authentication exchange. The format - of the AT_PADDING attribute is shown below. - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | AT_PADDING | Length | Padding... | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | - | | - | | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - - - - - - -Haverinen & Salowey Informational [Page 61] - -RFC 4186 EAP-SIM Authentication January 2006 - - -10.13. AT_RESULT_IND - - The format of the AT_RESULT_IND attribute is shown below. - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | AT_RESULT_...| Length = 1 | Reserved | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - The value field of this attribute consists of two reserved bytes, - which are set to zero upon sending and ignored upon reception. This - attribute is always sent unencrypted, so it MUST NOT be encapsulated - within the AT_ENCR_DATA attribute. - -10.14. AT_MAC - - The AT_MAC attribute is used for EAP-SIM message authentication. - Section 8 specifies in which messages AT_MAC MUST be included. - - The value field of the AT_MAC attribute contains two reserved bytes - followed by a keyed message authentication code (MAC). The MAC is - calculated over the whole EAP packet and concatenated with optional - message-specific data, with the exception that the value field of the - MAC attribute is set to zero when calculating the MAC. The EAP - packet includes the EAP header that begins with the Code field, the - EAP-SIM header that begins with the Subtype field, and all the - attributes, as specified in Section 8.1. The reserved bytes in - AT_MAC are set to zero when sending and ignored on reception. The - contents of the message-specific data that may be included in the MAC - calculation are specified separately for each EAP-SIM message in - Section 9. - - The format of the AT_MAC attribute is shown below. - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | AT_MAC | Length = 5 | Reserved | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | | - | MAC | - | | - | | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - - - - - -Haverinen & Salowey Informational [Page 62] - -RFC 4186 EAP-SIM Authentication January 2006 - - - The MAC algorithm is an HMAC-SHA1-128 [RFC2104] keyed hash value. - (The HMAC-SHA1-128 value is obtained from the 20-byte HMAC-SHA1 value - by truncating the output to the first 16 bytes. Hence, the length of - the MAC is 16 bytes. The derivation of the authentication key - (K_aut) used in the calculation of the MAC is specified in Section 7. - - When the AT_MAC attribute is included in an EAP-SIM message, the - recipient MUST process the AT_MAC attribute before looking at any - other attributes, except when processing EAP-Request/SIM/Challenge. - The processing of EAP-Request/SIM/Challenge is specified in Section - 9.3. If the message authentication code is invalid, then the - recipient MUST ignore all other attributes in the message and operate - as specified in Section 6.3. - -10.15. AT_COUNTER - - The format of the AT_COUNTER attribute is shown below. - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | AT_COUNTER | Length = 1 | Counter | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - The value field of the AT_COUNTER attribute consists of a 16-bit - unsigned integer counter value, represented in network byte order. - This attribute MUST always be encrypted by encapsulating it within - the AT_ENCR_DATA attribute. - -10.16. AT_COUNTER_TOO_SMALL - - The format of the AT_COUNTER_TOO_SMALL attribute is shown below. - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | AT_COUNTER...| Length = 1 | Reserved | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - The value field of this attribute consists of two reserved bytes, - which are set to zero upon sending and ignored upon reception. This - attribute MUST always be encrypted by encapsulating it within the - AT_ENCR_DATA attribute. - - - - - - - - -Haverinen & Salowey Informational [Page 63] - -RFC 4186 EAP-SIM Authentication January 2006 - - -10.17. AT_NONCE_S - - The format of the AT_NONCE_S attribute is shown below. - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | AT_NONCE_S | Length = 5 | Reserved | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | | - | | - | NONCE_S | - | | - | | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - The value field of the AT_NONCE_S attribute contains two reserved - bytes followed by a random number freshly generated by the server (16 - bytes) for this EAP-SIM fast re-authentication. The random number is - used as a challenge for the peer and also as a seed value for the new - keying material. The reserved bytes are set to zero upon sending and - ignored upon reception. This attribute MUST always be encrypted by - encapsulating it within the AT_ENCR_DATA attribute. - - The server MUST NOT re-use the NONCE_S value from any previous - EAP-SIM fast re-authentication exchange. The server SHOULD use a - good source of randomness to generate NONCE_S. Please see [RFC4086] - for more information about generating random numbers for security - applications. - -10.18. AT_NOTIFICATION - - The format of the AT_NOTIFICATION attribute is shown below. - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - |AT_NOTIFICATION| Length = 1 |S|P| Notification Code | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - The value field of this attribute contains a two-byte notification - code. The first and second bit (S and P) of the notification code - are interpreted as described in Section 6. - - The notification code values listed below have been reserved. The - descriptions below illustrate the semantics of the notifications. - - - - - -Haverinen & Salowey Informational [Page 64] - -RFC 4186 EAP-SIM Authentication January 2006 - - - The peer implementation MAY use different wordings when presenting - the notifications to the user. The "requested service" depends on - the environment where EAP-SIM is applied. - - 0 - General failure after authentication. (Implies failure, used - after successful authentication.) - - 16384 - General failure. (Implies failure, used before - authentication.) - - 32768 - Success. User has been successfully authenticated. (Does - not imply failure, used after successful authentication). The usage - of this code is discussed in Section 6.2. - - 1026 - User has been temporarily denied access to the requested - service. (Implies failure, used after successful authentication.) - - 1031 - User has not subscribed to the requested service. (Implies - failure, used after successful authentication.) - -10.19. AT_CLIENT_ERROR_CODE - - The format of the AT_CLIENT_ERROR_CODE attribute is shown below. - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - |AT_CLIENT_ERR..| Length = 1 | Client Error Code | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - The value field of this attribute contains a two-byte client error - code. The following error code values have been reserved. - - - 0 "unable to process packet": a general error code - - 1 "unsupported version": the peer does not support any of - the versions listed in AT_VERSION_LIST - - 2 "insufficient number of challenges": the peer's policy - requires more triplets than the server included in AT_RAND - - 3 "RANDs are not fresh": the peer believes that the RAND - challenges included in AT_RAND were not fresh - - - - - - - -Haverinen & Salowey Informational [Page 65] - -RFC 4186 EAP-SIM Authentication January 2006 - - -11. IANA Considerations - - IANA has assigned the EAP type number 18 for this protocol. - - EAP-SIM shares most of the protocol design, such as attributes and - message Subtypes, with EAP-AKA [EAP-AKA]. EAP-SIM protocol numbers - should be administered in the same IANA registry as EAP-AKA. The - initial values are listed in [EAP-AKA] for both protocols, so this - document does not require any new registries or parameter allocation. - As a common registry is used for EAP-SIM and EAP-AKA, the protocol - number allocation policy for both protocols is specified in - [EAP-AKA]. - -12. Security Considerations - - The EAP specification [RFC3748] describes the security - vulnerabilities of EAP, which does not include its own security - mechanisms. This section discusses the claimed security properties - of EAP-SIM, as well as vulnerabilities and security recommendations. - -12.1. A3 and A8 Algorithms - - The GSM A3 and A8 algorithms are used in EAP-SIM. [GSM-03.20] - specifies the general GSM authentication procedure and the external - interface (inputs and outputs) of the A3 and A8 algorithms. The - operation of these functions falls completely within the domain of an - individual operator, and therefore, the functions are specified by - each operator rather than being fully standardised. The GSM-MILENAGE - algorithm, specified publicly in [3GPP-TS-55.205], is an example - algorithm set for A3 and A8 algorithms. - - The security of the A3 and A8 algorithms is important to the security - of EAP-SIM. Some A3/A8 algorithms have been compromised; see [GSM- - Cloning] for discussion about the security of COMP-128 version 1. - Note that several revised versions of the COMP-128 A3/A8 algorithm - have been devised after the publication of these weaknesses and that - the publicly specified GSM-MILENAGE algorithm is not vulnerable to - any known attacks. - -12.2. Identity Protection - - EAP-SIM includes optional identity privacy support that protects the - privacy of the subscriber identity against passive eavesdropping. - This document only specifies a mechanism to deliver pseudonyms from - the server to the peer as part of an EAP-SIM exchange. Hence, a peer - that has not yet performed any EAP-SIM exchanges does not typically - have a pseudonym available. If the peer does not have a pseudonym - available, then the privacy mechanism cannot be used, but the - - - -Haverinen & Salowey Informational [Page 66] - -RFC 4186 EAP-SIM Authentication January 2006 - - - permanent identity will have to be sent in the clear. The terminal - SHOULD store the pseudonym in a non-volatile memory so that it can be - maintained across reboots. An active attacker that impersonates the - network may use the AT_PERMANENT_ID_REQ attribute to attempt to learn - the subscriber's permanent identity. However, as discussed in - Section 4.2.2, the terminal can refuse to send the cleartext - permanent identity if it believes that the network should be able to - recognize the pseudonym. - - If the peer and server cannot guarantee that the pseudonym will be - maintained reliably, and identity privacy is required, then - additional protection from an external security mechanism (such as - Protected Extensible Authentication Protocol (PEAP) [PEAP]) may be - used. If an external security mechanism is in use, the identity - privacy features of EAP-SIM may not be useful. The security - considerations of using an external security mechanism with EAP-SIM - are beyond the scope of this document. - -12.3. Mutual Authentication and Triplet Exposure - - EAP-SIM provides mutual authentication. The peer believes that the - network is authentic because the network can calculate a correct - AT_MAC value in the EAP-Request/SIM/Challenge packet. To calculate - AT_MAC it is sufficient to know the RAND and Kc values from the GSM - triplets (RAND, SRES, Kc) used in the authentication. Because the - network selects the RAND challenges and the triplets, an attacker - that knows n (2 or 3) GSM triplets for the subscriber is able to - impersonate a valid network to the peer. (Some peers MAY employ an - implementation-specific counter-measure against impersonating a valid - network by re-using a previously used RAND; see below.) In other - words, the security of EAP-SIM is based on the secrecy of Kc keys, - which are considered secret intermediate results in the EAP-SIM - cryptographic calculations. - - Given physical access to the SIM card, it is easy to obtain any - number of GSM triplets. - - Another way to obtain triplets is to mount an attack on the peer - platform via a virus or other malicious piece of software. The peer - SHOULD be protected against triplet querying attacks by malicious - software. Care should be taken not to expose Kc keys to attackers - when they are stored or handled by the peer, or transmitted between - subsystems of the peer. Steps should be taken to limit the - transport, storage, and handling of these values outside a protected - environment within the peer. However, the virus protection of the - peer and the security capabilities of the peer's operating system are - outside the scope of this document. - - - - -Haverinen & Salowey Informational [Page 67] - -RFC 4186 EAP-SIM Authentication January 2006 - - - The EAP-SIM server typically obtains the triplets from the Home - Location Register (HLR). An attacker might try to obtain triplets by - attacking against the network used between the EAP-SIM server and the - HLR. Care should be taken not to expose Kc keys to attackers when - they are stored or handled by the EAP-SIM server, or transmitted - between the EAP server and the HLR. Steps should be taken to limit - the transport, storage, and handling of these values outside a - protected environment. However, the protection of the communications - between the EAP-SIM server and the HLR is outside the scope of this - document. - - If the same SIM credentials are also used for GSM traffic, the - triplets could be revealed in the GSM network; see Section 12.8. - - In GSM, the network is allowed to re-use the RAND challenge in - consecutive authentication exchanges. This is not allowed in - EAP-SIM. The EAP-SIM server is mandated to use fresh triplets (RAND - challenges) in consecutive authentication exchanges, as specified in - Section 3. EAP-SIM does not mandate any means for the peer to check - if the RANDs are fresh, so the security of the scheme leans on the - secrecy of the triplets. However, the peer MAY employ - implementation-specific mechanisms to remember some of the previously - used RANDs, and the peer MAY check the freshness of the server's - RANDs. The operation in cases when the peer detects that the RANDs - are not fresh is specified in Section 6.3.1. - - Preventing the re-use of authentication vectors has been taken into - account in the design of the UMTS Authentication and Key Agreement - (AKA), which is used in EAP-AKA [EAP-AKA]. In cases when the triplet - re-use properties of EAP-SIM are not considered sufficient, it is - advised to use EAP-AKA. - - Note that EAP-SIM mutual authentication is done with the EAP server. - In general, EAP methods do not authenticate the identity or services - provided by the EAP authenticator (if distinct from the EAP server) - unless they provide the so-called channel bindings property. The - vulnerabilities related to this have been discussed in [RFC3748], - [EAP-Keying], [Service-Identity]. - - EAP-SIM does not provide the channel bindings property, so it only - authenticates the EAP server. However, ongoing work such as - [Service-Identity] may provide such support as an extension to - popular EAP methods such as EAP-TLS, EAP-SIM, or EAP-AKA. - - - - - - - - -Haverinen & Salowey Informational [Page 68] - -RFC 4186 EAP-SIM Authentication January 2006 - - -12.4. Flooding the Authentication Centre - - The EAP-SIM server typically obtains authentication vectors from the - Authentication Centre (AuC). EAP-SIM introduces a new usage for the - AuC. The protocols between the EAP-SIM server and the AuC are out of - the scope of this document. However, it should be noted that a - malicious EAP-SIM peer may generate a lot of protocol requests to - mount a denial of service attack. The EAP-SIM server implementation - SHOULD take this into account and SHOULD take steps to limit the - traffic that it generates towards the AuC, preventing the attacker - from flooding the AuC and from extending the denial of service attack - from EAP-SIM to other users of the AuC. - -12.5. Key Derivation - - EAP-SIM supports key derivation. The key hierarchy is specified in - Section 7. EAP-SIM combines several GSM triplets in order to - generate stronger keying material and stronger AT_MAC values. The - actual strength of the resulting keys depends, among other things, on - operator-specific parameters including authentication algorithms, the - strength of the Ki key, and the quality of the RAND challenges. For - example, some SIM cards generate Kc keys with 10 bits set to zero. - Such restrictions may prevent the concatenation technique from - yielding strong session keys. Because the strength of the Ki key is - 128 bits, the ultimate strength of any derived secret key material is - never more than 128 bits. - - It should also be noted that a security policy that allows n=2 to be - used may compromise the security of a future policy that requires - three triplets, because adversaries may be able to exploit the - messages exchanged when the weaker policy is applied. - - There is no known way to obtain complete GSM triplets by mounting an - attack against EAP-SIM. A passive eavesdropper can learn n*RAND and - AT_MAC and may be able to link this information to the subscriber - identity. An active attacker that impersonates a GSM subscriber can - easily obtain n*RAND and AT_MAC values from the EAP server for any - given subscriber identity. However, calculating the Kc and SRES - values from AT_MAC would require the attacker to reverse the keyed - message authentication code function HMAC-SHA1-128. - - As EAP-SIM does not expose any values calculated from an individual - GSM Kc keys, it is not possible to mount a brute force attack on only - one of the Kc keys in EAP-SIM. Therefore, when considering brute - force attacks on the values exposed in EAP-SIM, the effective length - of EAP-SIM session keys is not compromised by the fact that they are - - - - - -Haverinen & Salowey Informational [Page 69] - -RFC 4186 EAP-SIM Authentication January 2006 - - - combined from several shorter keys, i.e., the effective length of 128 - bits may be achieved. For additional considerations, see Section - 12.8. - -12.6. Cryptographic Separation of Keys and Session Independence - - The EAP Transient Keys used to protect EAP-SIM packets (K_encr, - K_aut), the Master Session Key, and the Extended Master Session Key - are cryptographically separate in EAP-SIM. An attacker cannot derive - any non-trivial information about any of these keys based on the - other keys. An attacker also cannot calculate the pre-shared secret - (Ki) from the GSM Kc keys, from EAP-SIM K_encr, from EAP-SIM K_aut, - from the Master Session Key, or from the Extended Master Session Key. - - Each EAP-SIM exchange generates fresh keying material, and the keying - material exported from the method upon separate EAP-SIM exchanges is - cryptographically separate. The EAP-SIM peer contributes to the - keying material with the NONCE_MT parameter, which must be chosen - freshly for each full authentication exchange. The EAP server is - mandated to choose the RAND challenges freshly for each full - authentication exchange. If either the server or the peer chooses - its random value (NONCE_MT or RAND challenges) freshly, even if the - other entity re-used its value from a previous exchange, then the EAP - Transient Keys, the Master Session Key, and the Extended Master - Session Key will be different and cryptographically separate from the - corresponding values derived upon the previous full authentication - exchange. - - On fast re-authentication, freshness of the Master Session Key and - the Extended Master Session Key is provided with a counter - (AT_COUNTER). The same EAP Transient Keys (K_encr, K_aut) that were - used in the full authentication exchange are used to protect the EAP - negotiation. However, replay and integrity protection across all the - fast re-authentication exchanges that use the same EAP Transient Keys - is provided with AT_COUNTER. - - [RFC3748] defines session independence as the "demonstration that - passive attacks (such as capture of the EAP conversation) or active - attacks (including compromise of the MSK or EMSK) do not enable - compromise of subsequent or prior MSKs or EMSKs". Because the MSKs - and EMSKs are separate between EAP exchanges, EAP-SIM supports this - security claim. - - It should be noted that [Patel-2003], which predates [RFC3748], uses - a slightly different meaning for session independence. The EAP-SIM - protocol does not allow the peer to ensure that different Kc key - values would be used in different exchanges. Only the server is able - to ensure that fresh RANDs, and therefore, fresh Kc keys are used. - - - -Haverinen & Salowey Informational [Page 70] - -RFC 4186 EAP-SIM Authentication January 2006 - - - Hence, the peer cannot guarantee EAP-SIM sessions to be independent - with regard to the internal Kc values. However, in EAP-SIM, the Kc - keys are considered to be secret intermediate results, which are not - exported outside the method. See Section 12.3 for more information - about RAND re-use. - -12.7. Dictionary Attacks - - Because EAP-SIM is not a password protocol, it is not vulnerable to - dictionary attacks. (The pre-shared symmetric secret stored on the - SIM card is not a passphrase, nor is it derived from a passphrase.) - -12.8. Credentials Re-use - - EAP-SIM cannot prevent attacks over the GSM or GPRS radio networks. - If the same SIM credentials are also used in GSM or GPRS, it is - possible to mount attacks over the cellular interface. - - A passive attacker can eavesdrop GSM or GPRS traffic and obtain RAND, - SRES pairs. He can then use a brute force attack or other - cryptanalysis techniques to obtain the 64-bit Kc keys used to encrypt - the GSM or GPRS data. This makes it possible to attack each 64-bit - key separately. - - An active attacker can mount a "rogue GSM/GPRS base station attack", - replaying previously seen RAND challenges to obtain SRES values. He - can then use a brute force attack to obtain the Kc keys. If - successful, the attacker can impersonate a valid network or decrypt - previously seen traffic, because EAP-SIM does not provide perfect - forward secrecy (PFS). - - Due to several weaknesses in the GSM encryption algorithms, the - effective key strength of the Kc keys is much less than the expected - 64 bits (no more than 40 bits if the A5/1 GSM encryption algorithm is - used; as documented in [Barkan-2003], an active attacker can force - the peer to use the weaker A5/2 algorithm that can be broken in less - than a second). - - Because the A5 encryption algorithm is not used in EAP-SIM, and - because EAP-SIM does not expose any values calculated from individual - Kc keys, it should be noted that these attacks are not possible if - the SIM credentials used in EAP-SIM are not shared in GSM/GPRS. - - At the time this document was written, the 3rd Generation Partnership - Project (3GPP) has started to work on fixes to these A5 - vulnerabilities. One of the solution proposals discussed in 3GPP is - integrity-protected A5 version negotiation, which would require the - base station to prove knowledge of the Kc key before the terminal - - - -Haverinen & Salowey Informational [Page 71] - -RFC 4186 EAP-SIM Authentication January 2006 - - - sends any values calculated from the Kc to the network. Another - proposal is so-called special RANDs, where some bits of the RAND - challenge would be used for cryptographic separation by indicating - the allowed use of the triplet, such as the allowed A5 algorithm in - GSM or the fact that the triplet is intended for EAP-SIM. This is - currently a work in progress, and the mechanisms have not been - selected yet. - -12.9. Integrity and Replay Protection, and Confidentiality - - AT_MAC, AT_IV, AT_ENCR_DATA, and AT_COUNTER attributes are used to - provide integrity, replay and confidentiality protection for EAP-SIM - requests and responses. Integrity protection with AT_MAC includes - the EAP header. These attributes cannot be used during the - EAP/SIM/Start roundtrip. However, the protocol values (user identity - string, NONCE_MT, and version negotiation parameters) are - (implicitly) protected by later EAP-SIM messages by including them in - key derivation. - - Integrity protection (AT_MAC) is based on a keyed message - authentication code. Confidentiality (AT_ENCR_DATA and AT_IV) is - based on a block cipher. - - Confidentiality protection is applied only to a part of the protocol - fields. The table of attributes in Section 10.1 summarizes which - fields are confidentiality-protected. It should be noted that the - error and notification code attributes AT_CLIENT_ERROR_CODE and - AT_NOTIFICATION are not confidential, but they are transmitted in the - clear. Identity protection is discussed in Section 12.2. - - On full authentication, replay protection of the EAP exchange is - provided by the RAND values from the underlying GSM authentication - scheme and the use of the NONCE_MT value. Protection against replays - of EAP-SIM messages is also based on the fact that messages that can - include AT_MAC can only be sent once with a certain EAP-SIM Subtype, - and on the fact that a different K_aut key will be used for - calculating AT_MAC in each full authentication exchange. - - On fast re-authentication, a counter included in AT_COUNTER and a - server random nonce is used to provide replay protection. The - AT_COUNTER attribute is also included in EAP-SIM notifications if it - is used after successful authentication in order to provide replay - protection between re-authentication exchanges. - - Because EAP-SIM is not a tunneling method, EAP-Request/Notification, - EAP-Response/Notification, EAP-Success, or EAP-Failure packets are - not confidential, integrity-protected, or replay-protected in - EAP-SIM. On physically insecure networks, this may enable an - - - -Haverinen & Salowey Informational [Page 72] - -RFC 4186 EAP-SIM Authentication January 2006 - - - attacker to send false notifications to the peer and to mount denial - of service attacks by spoofing these packets. As discussed in - Section 6.3, the peer will only accept EAP-Success after the peer - successfully authenticates the server. Hence, the attacker cannot - force the peer to believe successful mutual authentication has - occurred until the peer successfully authenticates the server or - after the peer fails to authenticate the server. - - The security considerations of EAP-SIM result indications are covered - in Section 12.11 - - An eavesdropper will see the EAP-Request/Notification, - EAP-Response/Notification, EAP-Success, and EAP-Failure packets sent - in the clear. With EAP-SIM, confidential information MUST NOT be - transmitted in EAP Notification packets. - -12.10. Negotiation Attacks - - EAP-SIM does not protect the EAP-Response/Nak packet. Because - EAP-SIM does not protect the EAP method negotiation, EAP method - downgrading attacks may be possible, especially if the user uses the - same identity with EAP-SIM and other EAP methods. - - EAP-SIM includes a version negotiation procedure. In EAP-SIM the - keying material derivation includes the version list and selected - version to ensure that the protocol cannot be downgraded and that the - peer and server use the same version of EAP-SIM. - - EAP-SIM does not support ciphersuite negotiation. - -12.11. Protected Result Indications - - EAP-SIM supports optional protected success indications and - acknowledged failure indications. If a failure occurs after - successful authentication, then the EAP-SIM failure indication is - integrity- and replay-protected. - - Even if an EAP-Failure packet is lost when using EAP-SIM over an - unreliable medium, then the EAP-SIM failure indications will help - ensure that the peer and EAP server will know the other party's - authentication decision. If protected success indications are used, - then the loss of Success packet will also be addressed by the - acknowledged, integrity- and replay-protected EAP-SIM success - indication. If the optional success indications are not used, then - the peer may end up believing that the server succeeded - authentication, when it actually failed. Since access will not be - - - - - -Haverinen & Salowey Informational [Page 73] - -RFC 4186 EAP-SIM Authentication January 2006 - - - granted in this case, protected result indications are not needed - unless the client is not able to realize it does not have access for - an extended period of time. - -12.12. Man-in-the-Middle Attacks - - In order to avoid man-in-the-middle attacks and session hijacking, - user data SHOULD be integrity-protected on physically insecure - networks. The EAP-SIM Master Session Key, or keys derived from it, - MAY be used as the integrity protection keys, or, if an external - security mechanism such as PEAP is used, then the link integrity - protection keys MAY be derived by the external security mechanism. - - There are man-in-the-middle attacks associated with the use of any - EAP method within a tunneled protocol. For instance, an early - version of PEAP [PEAP-02] was vulnerable to this attack. This - specification does not address these attacks. If EAP-SIM is used - with a tunneling protocol, there should be cryptographic binding - provided between the protocol and EAP-SIM to prevent - man-in-the-middle attacks through rogue authenticators being able to - setup one-way authenticated tunnels. For example, newer versions of - PEAP include such cryptographic binding. The EAP-SIM Master Session - Key MAY be used to provide the cryptographic binding. However, the - mechanism by which the binding is provided depends on the tunneling - protocol and is beyond the scope of this document. - -12.13. Generating Random Numbers - - An EAP-SIM implementation SHOULD use a good source of randomness to - generate the random numbers required in the protocol. Please see - [RFC4086] for more information on generating random numbers for - security applications. - -13. Security Claims - - This section provides the security claims required by [RFC3748]. - - Auth. mechanism: EAP-SIM is based on the GSM SIM mechanism, which is - a challenge/response authentication and key agreement mechanism based - on a symmetric 128-bit pre-shared secret. EAP-SIM also makes use of - a peer challenge to provide mutual authentication. - - Ciphersuite negotiation: No - - Mutual authentication: Yes (Section 12.3) - - Integrity protection: Yes (Section 12.9) - - - - -Haverinen & Salowey Informational [Page 74] - -RFC 4186 EAP-SIM Authentication January 2006 - - - Replay protection: Yes (Section 12.9) - - Confidentiality: Yes, except method-specific success and failure - indications (Section 12.2, Section 12.9) - - Key derivation: Yes - - Key strength: EAP-SIM supports key derivation with 128-bit effective - key strength (Section 12.5). However, as discussed in Section 11, if - the same credentials are used in GSM/GPRS and in EAP-SIM, then the - key strength may be reduced considerably, basically to the same level - as in GSM, by mounting attacks over GSM/GPRS. For example an active - attack using a false GSM/GPRS base station reduces the effective key - strength to almost zero. - - Description of key hierarchy: Please see Section 7. - - Dictionary attack protection: N/A (Section 12.7) - - Fast reconnect: Yes - - Cryptographic binding: N/A - - Session independence: Yes (Section 12.6) - - Fragmentation: No - - Channel binding: No - - Indication of vulnerabilities: Vulnerabilities are discussed in - Section 12. - -14. Acknowledgements and Contributions - -14.1. Contributors - - In addition to the editors, Nora Dabbous, Jose Puthenkulam, and - Prasanna Satarasinghe were significant contributors to this document. - - Pasi Eronen and Jukka-Pekka Honkanen contributed Appendix A. - -14.2. Acknowledgements - - Juha Ala-Laurila, N. Asokan, Jan-Erik Ekberg, Patrik Flykt, - Jukka-Pekka Honkanen, Antti Kuikka, Jukka Latva, Lassi Lehtinen, Jyri - Rinnemaa, Timo Takamaki, and Raimo Vuonnala contributed many original - ideas and concepts to this protocol. - - - - -Haverinen & Salowey Informational [Page 75] - -RFC 4186 EAP-SIM Authentication January 2006 - - - N. Asokan, Pasi Eronen, and Jukka-Pekka Honkanen contributed and - helped in innumerable ways during the development of the protocol. - - Valtteri Niemi and Kaisa Nyberg contributed substantially to the - design of the key derivation and the fast re-authentication - procedure, and have also provided their cryptographic expertise in - many discussions related to this protocol. - - Simon Blake-Wilson provided very helpful comments on key derivation - and version negotiation. - - Thanks to Greg Rose for his very valuable comments to an early - version of this specification [S3-020125], and for reviewing and - providing very useful comments on version 12. - - Thanks to Bernard Aboba, Vladimir Alperovich, Florent Bersani, - Jacques Caron, Gopal Dommety, Augustin Farrugia, Mark Grayson, Max de - Groot, Prakash Iyer, Nishi Kant, Victor Lortz, Jouni Malinen, Sarvar - Patel, Tom Porcher, Michael Richardson, Stefan Schroeder, Uma - Shankar, Jesse Walker, and Thomas Wieland for their contributions and - critiques. Special thanks to Max for proposing improvements to the - MAC calculation. - - Thanks to Glen Zorn for reviewing this document and for providing - very useful comments on the protocol. - - Thanks to Sarvar Patel for his review of the protocol [Patel-2003]. - - Thanks to Bernard Aboba for reviewing this document for RFC 3748 - compliance. - - The identity privacy support is based on the identity privacy support - of [EAP-SRP]. The attribute format is based on the extension format - of Mobile IPv4 [RFC3344]. - - This protocol has been partly developed in parallel with EAP-AKA - [EAP-AKA], and hence this specification incorporates many ideas from - Jari Arkko. - - - - - - - - - - - - - -Haverinen & Salowey Informational [Page 76] - -RFC 4186 EAP-SIM Authentication January 2006 - - -14.2.1. Contributors' Addresses - - Nora Dabbous - Gemplus - 34 rue Guynemer - 92447 Issy les Moulineaux - France - - Phone: +33 1 4648 2000 - EMail: nora.dabbous@gemplus.com - - - Jose Puthenkulam - Intel Corporation - 2111 NE 25th Avenue, JF2-58 - Hillsboro, OR 97124 - USA - - Phone: +1 503 264 6121 - EMail: jose.p.puthenkulam@intel.com - - - Prasanna Satarasinghe - Transat Technologies - 180 State Street, Suite 240 - Southlake, TX 76092 - USA - - Phone: + 1 817 4814412 - EMail: prasannas@transat-tech.com - - - - - - - - - - - - - - - - - - - - - -Haverinen & Salowey Informational [Page 77] - -RFC 4186 EAP-SIM Authentication January 2006 - - -15. References - -15.1. Normative References - - [GSM-03.20] European Telecommunications Standards Institute, - "GSM Technical Specification GSM 03.20 (ETS 300 - 534): "Digital cellular telecommunication system - (Phase 2); Security related network functions"", - August 1997. - - [RFC2119] Bradner, S., "Key words for use in RFCs to - Indicate Requirement Levels", BCP 14, RFC 2119, - March 1997. - - [GSM-03.03] European Telecommunications Standards Institute, - "GSM Technical Specification GSM 03.03 (ETS 300 - 523): "Digital cellular telecommunication system - (Phase 2); Numbering, addressing and - identification"", April 1997. - - [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: - Keyed-Hashing for Message Authentication", RFC - 2104, February 1997. - - [RFC4282] Aboba, B., Beadles, M., Arkko, J., and P. Eronen, - "The Network Access Identifier", RFC 4282, - December 2005. - - [AES] National Institute of Standards and Technology, - "Federal Information Processing Standards (FIPS) - Publication 197, "Advanced Encryption Standard - (AES)"", November 2001. - http://csrc.nist.gov/publications/fips/fips197/ - fips-197.pdf - - [CBC] National Institute of Standards and Technology, - "NIST Special Publication 800-38A, "Recommendation - for Block Cipher Modes of Operation - Methods and - Techniques"", December 2001. - http://csrc.nist.gov/publications/nistpubs/ - 800-38a/sp800-38a.pdf - - [SHA-1] National Institute of Standards and Technology, - U.S. Department of Commerce, "Federal Information - Processing Standard (FIPS) Publication 180-1, - "Secure Hash Standard"", April 1995. - - - - - -Haverinen & Salowey Informational [Page 78] - -RFC 4186 EAP-SIM Authentication January 2006 - - - [PRF] National Institute of Standards and Technology, - "Federal Information Processing Standards (FIPS) - Publication 186-2 (with change notice); Digital - Signature Standard (DSS)", January 2000. - Available on-line at: - http://csrc.nist.gov/publications/ - fips/fips186-2/fips186-2-change1.pdf - - [RFC3629] Yergeau, F., "UTF-8, a transformation format of - ISO 10646", STD 63, RFC 3629, November 2003. - - [RFC3748] Aboba, B., Blunk, L., Vollbrecht, J., Carlson, J., - and H. Levkowetz, "Extensible Authentication - Protocol (EAP)", RFC 3748, June 2004. - - [EAP-AKA] Arkko, J. and H. Haverinen, "Extensible - Authentication Protocol Method for 3rd Generation - Authentication and Key Agreement (EAP-AKA)", RFC - 4187, January 2006. - -15.2. Informative References - - [3GPP-TS-23.003] 3rd Generation Partnership Project, "3GPP - Technical Specification 3GPP TS 23.003 V6.8.0: - "3rd Generation Parnership Project; Technical - Specification Group Core Network; Numbering, - addressing and identification (Release 6)"", - December 2005. - - [3GPP-TS-55.205] 3rd Generation Partnership Project, "3GPP - Technical Specification 3GPP TS 55.205 V 6.0.0: - "3rd Generation Partnership Project; Technical - Specification Group Services and System Aspects; - Specification of the GSM-MILENAGE Algorithms: An - example algorithm set for the GSM Authentication - and Key Generation functions A3 and A8 (Release - 6)"", December 2002. - - [PEAP] Palekar, A., Simon, D., Zorn, G., Salowey, J., - Zhou, H., and S. Josefsson, "Protected EAP - Protocol (PEAP) Version 2", Work in Progress, - October 2004. - - [PEAP-02] Anderson, H., Josefsson, S., Zorn, G., Simon, D., - and A. Palekar, "Protected EAP Protocol (PEAP)", - Work in Progress, February 2002. - - - - - -Haverinen & Salowey Informational [Page 79] - -RFC 4186 EAP-SIM Authentication January 2006 - - - [EAP-Keying] Aboba, B., Simon, D., Arkko, J., Eronen, P., and - H. Levkowetz, "Extensible Authentication Protocol - (EAP) Key Management Framework", Work in Progress, - October 2005. - - [Service-Identity] Arkko, J. and P. Eronen, "Authenticated Service - Information for the Extensible Authentication - Protocol (EAP)", Work in Progress, October 2004. - - [RFC4086] Eastlake, D., 3rd, Schiller, J., and S. Crocker, - "Randomness Requirements for Security", BCP 106, - RFC 4086, June 2005. - - [S3-020125] Qualcomm, "Comments on draft EAP/SIM, 3rd - Generation Partnership Project document 3GPP TSG - SA WG3 Security S3#22, S3-020125", February 2002. - - [RFC3344] Perkins, C., "IP Mobility Support for IPv4", RFC - 3344, August 2002. - - [RFC2548] Zorn, G., "Microsoft Vendor-specific RADIUS - Attributes ", RFC 2548, March 1999. - - [EAP-SRP] Carlson, J., Aboba, B., and H. Haverinen, "EAP - SRP-SHA1 Authentication Protocol", Work in - Progress, July 2001. - - [GSM-Cloning] Wagner, D., "GSM Cloning". Web page about - COMP-128 version 1 vulnerabilities, available at - http://www.isaac.cs.berkeley.edu/isaac/gsm.html - - [Barkan-2003] Barkan, E., Biham, E., and N. Keller, "Instant - Ciphertext-Only Cryptanalysis of GSM Encrypted - Communications". available on-line at - http://cryptome.org/gsm-crack-bbk.pdf - - [Patel-2003] Patel, S., "Analysis of EAP-SIM Session Key - Agreement". Posted to the EAP mailing list 29 - May,2003. http:// - mail.frascone.com/pipermail/public/eap/2003-May/ - 001267.html - - - - - - - - - - -Haverinen & Salowey Informational [Page 80] - -RFC 4186 EAP-SIM Authentication January 2006 - - -Appendix A. Test Vectors - - Test vectors for the NIST FIPS 186-2 pseudo-random number generator - [PRF] are available at the following URL: - http://csrc.nist.gov/encryption/dss/Examples-1024bit.pdf - - The following examples show the contents of EAP-SIM packets on full - authentication and fast re-authentication. - -A.1. EAP-Request/Identity - - The first packet is a plain Identity Request: - - 01 ; Code: Request - 00 ; Identifier: 0 - 00 05 ; Length: 5 octets - 01 ; Type: Identity - -A.2. EAP-Response/Identity - - The client's identity is "1244070100000001@eapsim.foo", so it - responds with the following packet: - - 02 ; Code: Response - 00 ; Identifier: 0 - 00 20 ; Length: 32 octets - 01 ; Type: Identity - 31 32 34 34 ; "1244070100000001@eapsim.foo" - 30 37 30 31 - 30 30 30 30 - 30 30 30 31 - 40 65 61 70 - 73 69 6d 2e - 66 6f 6f - - - - - - - - - - - - - - - - - -Haverinen & Salowey Informational [Page 81] - -RFC 4186 EAP-SIM Authentication January 2006 - - -A.3. EAP-Request/SIM/Start - - The server's first packet looks like this: - - 01 ; Code: Request - 01 ; Identifier: 1 - 00 10 ; Length: 16 octets - 12 ; Type: EAP-SIM - 0a ; EAP-SIM subtype: Start - 00 00 ; (reserved) - 0f ; Attribute type: AT_VERSION_LIST - 02 ; Attribute length: 8 octets (2*4) - 00 02 ; Actual version list length: 2 octets - 00 01 ; Version: 1 - 00 00 ; (attribute padding) - -A.4. EAP-Response/SIM/Start - - The client selects a nonce and responds with the following packet: - - 02 ; Code: Response - 01 ; Identifier: 1 - 00 20 ; Length: 32 octets - 12 ; Type: EAP-SIM - 0a ; EAP-SIM subtype: Start - 00 00 ; (reserved) - 07 ; Attribute type: AT_NONCE_MT - 05 ; Attribute length: 20 octets (5*4) - 00 00 ; (reserved) - 01 23 45 67 ; NONCE_MT value - 89 ab cd ef - fe dc ba 98 - 76 54 32 10 - 10 ; Attribute type: AT_SELECTED_VERSION - 01 ; Attribute length: 4 octets (1*4) - 00 01 ; Version: 1 - - - - - - - - - - - - - - - -Haverinen & Salowey Informational [Page 82] - -RFC 4186 EAP-SIM Authentication January 2006 - - -A.5. EAP-Request/SIM/Challenge - - Next, the server selects three authentication triplets - - (RAND1,SRES1,Kc1) = (10111213 14151617 18191a1b 1c1d1e1f, - d1d2d3d4, - a0a1a2a3 a4a5a6a7) - (RAND2,SRES2,Kc2) = (20212223 24252627 28292a2b 2c2d2e2f, - e1e2e3e4, - b0b1b2b3 b4b5b6b7) - (RAND3,SRES3,Kc3) = (30313233 34353637 38393a3b 3c3d3e3f, - f1f2f3f4, - c0c1c2c3 c4c5c6c7) - - Next, the MK is calculated as specified in Section 7*. - - MK = e576d5ca 332e9930 018bf1ba ee2763c7 95b3c712 - - And the other keys are derived using the PRNG: - - K_encr = 536e5ebc 4465582a a6a8ec99 86ebb620 - K_aut = 25af1942 efcbf4bc 72b39434 21f2a974 - MSK = 39d45aea f4e30601 983e972b 6cfd46d1 - c3637733 65690d09 cd44976b 525f47d3 - a60a985e 955c53b0 90b2e4b7 3719196a - 40254296 8fd14a88 8f46b9a7 886e4488 - EMSK = 5949eab0 fff69d52 315c6c63 4fd14a7f - 0d52023d 56f79698 fa6596ab eed4f93f - bb48eb53 4d985414 ceed0d9a 8ed33c38 - 7c9dfdab 92ffbdf2 40fcecf6 5a2c93b9 - - Next, the server selects a pseudonym and a fast re-authentication - identity (in this case, "w8w49PexCazWJ&xCIARmxuMKht5S1sxR - DqXSEFBEg3DcZP9cIxTe5J4OyIwNGVzxeJOU1G" and - "Y24fNSrz8BP274jOJaF17WfxI8YO7QX0 - 0pMXk9XMMVOw7broaNhTczuFq53aEpOkk3L0dm@eapsim.foo", respectively). - - - - - - - - - - - - - - - -Haverinen & Salowey Informational [Page 83] - -RFC 4186 EAP-SIM Authentication January 2006 - - - The following plaintext will be encrypted and stored in the - AT_ENCR_DATA attribute: - - 84 ; Attribute type: AT_NEXT_PSEUDONYM - 13 ; Attribute length: 76 octets (19*4) - 00 46 ; Actual pseudonym length: 70 octets - 77 38 77 34 39 50 65 78 43 61 7a 57 4a 26 78 43 - 49 41 52 6d 78 75 4d 4b 68 74 35 53 31 73 78 52 - 44 71 58 53 45 46 42 45 67 33 44 63 5a 50 39 63 - 49 78 54 65 35 4a 34 4f 79 49 77 4e 47 56 7a 78 - 65 4a 4f 55 31 47 - 00 00 ; (attribute padding) - 85 ; Attribute type: AT_NEXT_REAUTH_ID - 16 ; Attribute length: 88 octets (22*4) - 00 51 ; Actual re-auth identity length: 81 octets - 59 32 34 66 4e 53 72 7a 38 42 50 32 37 34 6a 4f - 4a 61 46 31 37 57 66 78 49 38 59 4f 37 51 58 30 - 30 70 4d 58 6b 39 58 4d 4d 56 4f 77 37 62 72 6f - 61 4e 68 54 63 7a 75 46 71 35 33 61 45 70 4f 6b - 6b 33 4c 30 64 6d 40 65 61 70 73 69 6d 2e 66 6f - 6f - 00 00 00 ; (attribute padding) - 06 ; Attribute type: AT_PADDING - 03 ; Attribute length: 12 octets (3*4) - 00 00 00 00 - 00 00 00 00 - 00 00 - - The EAP packet looks like this: - - 01 ; Code: Request - 02 ; Identifier: 2 - 01 18 ; Length: 280 octets - 12 ; Type: EAP-SIM - 0b ; EAP-SIM subtype: Challenge - 00 00 ; (reserved) - 01 ; Attribute type: AT_RAND - 0d ; Attribute length: 52 octets (13*4) - 00 00 ; (reserved) - 10 11 12 13 ; first RAND - 14 15 16 17 - 18 19 1a 1b - 1c 1d 1e 1f - 20 21 22 23 ; second RAND - 24 25 26 27 - 28 29 2a 2b - 2c 2d 2e 2f - - - - -Haverinen & Salowey Informational [Page 84] - -RFC 4186 EAP-SIM Authentication January 2006 - - - 30 31 32 33 ; third RAND - 34 35 36 37 - 38 39 3a 3b - 3c 3d 3e 3f - 81 ; Attribute type: AT_IV - 05 ; Attribute length: 20 octets (5*4) - 00 00 ; (reserved) - 9e 18 b0 c2 ; IV value - 9a 65 22 63 - c0 6e fb 54 - dd 00 a8 95 - 82 ; Attribute type: AT_ENCR_DATA - 2d ; Attribute length: 180 octets (45*4) - 00 00 ; (reserved) - 55 f2 93 9b bd b1 b1 9e a1 b4 7f c0 b3 e0 be 4c - ab 2c f7 37 2d 98 e3 02 3c 6b b9 24 15 72 3d 58 - ba d6 6c e0 84 e1 01 b6 0f 53 58 35 4b d4 21 82 - 78 ae a7 bf 2c ba ce 33 10 6a ed dc 62 5b 0c 1d - 5a a6 7a 41 73 9a e5 b5 79 50 97 3f c7 ff 83 01 - 07 3c 6f 95 31 50 fc 30 3e a1 52 d1 e1 0a 2d 1f - 4f 52 26 da a1 ee 90 05 47 22 52 bd b3 b7 1d 6f - 0c 3a 34 90 31 6c 46 92 98 71 bd 45 cd fd bc a6 - 11 2f 07 f8 be 71 79 90 d2 5f 6d d7 f2 b7 b3 20 - bf 4d 5a 99 2e 88 03 31 d7 29 94 5a ec 75 ae 5d - 43 c8 ed a5 fe 62 33 fc ac 49 4e e6 7a 0d 50 4d - 0b ; Attribute type: AT_MAC - 05 ; Attribute length: 20 octets (5*4) - 00 00 ; (reserved) - fe f3 24 ac ; MAC value - 39 62 b5 9f - 3b d7 82 53 - ae 4d cb 6a - - The MAC is calculated over the EAP packet above (with MAC value set - to zero), followed by the NONCE_MT value (a total of 296 bytes). - - - - - - - - - - - - - - - - -Haverinen & Salowey Informational [Page 85] - -RFC 4186 EAP-SIM Authentication January 2006 - - -A.6. EAP-Response/SIM/Challenge - - The client's response looks like this: - - 02 ; Code: Response - 02 ; Identifier: 2 - 00 1c ; Length: 28 octets - 12 ; Type: EAP-SIM - 0b ; EAP-SIM subtype: Challenge - 00 00 ; (reserved) - 0b ; Attribute type: AT_MAC - 05 ; Attribute length: 20 octets (5*4) - 00 00 ; (reserved) - f5 6d 64 33 ; MAC value - e6 8e d2 97 - 6a c1 19 37 - fc 3d 11 54 - - The MAC is calculated over the EAP packet above (with MAC value set - to zero), followed by the SRES values (a total of 40 bytes). - -A.7. EAP-Success - - The last packet is an EAP-Success: - - 03 ; Code: Success - 02 ; Identifier: 2 - 00 04 ; Length: 4 octets - -A.8. Fast Re-authentication - - When performing fast re-authentication, the EAP-Request/Identity - packet is the same as usual. The EAP-Response/Identity contains the - fast re-authentication identity (from AT_ENCR_DATA attribute above): - - 02 ; Code: Response - 00 ; Identifier: 0 - 00 56 ; Length: 86 octets - 01 ; Type: Identity - 59 32 34 66 4e 53 72 7a 38 42 50 32 37 34 6a 4f - 4a 61 46 31 37 57 66 78 49 38 59 4f 37 51 58 30 - 30 70 4d 58 6b 39 58 4d 4d 56 4f 77 37 62 72 6f - 61 4e 68 54 63 7a 75 46 71 35 33 61 45 70 4f 6b - 6b 33 4c 30 64 6d 40 65 61 70 73 69 6d 2e 66 6f - 6f - - - - - - -Haverinen & Salowey Informational [Page 86] - -RFC 4186 EAP-SIM Authentication January 2006 - - -A.9. EAP-Request/SIM/Re-authentication - - The server recognizes the reauthentication identity, so it will - respond with EAP-Request/SIM/Re-authentication. It retrieves the - associated counter value, generates a nonce, and picks a new - reauthentication identity (in this case, - "uta0M0iyIsMwWp5TTdSdnOLvg2XDVf21OYt1vnfiMcs5dnIDHOIFVavIRzMR - yzW6vFzdHW@eapsim.foo"). - - The following plaintext will be encrypted and stored in the - AT_ENCR_DATA attribute. Note that AT_PADDING is not used because the - length of the plaintext is a multiple of 16 bytes. - - 13 ; Attribute type: AT_COUNTER - 01 ; Attribute length: 4 octets (1*4) - 00 01 ; Counter value - 15 ; Attribute type: AT_NONCE_S - 05 ; Attribute length: 20 octets (5*4) - 00 00 ; (reserved) - 01 23 45 67 ; NONCE_S value - 89 ab cd ef - fe dc ba 98 - 76 54 32 10 - 85 ; Attribute type: AT_NEXT_REAUTH_ID - 16 ; Attribute length: 88 octets (22*4) - 00 51 ; Actual re-auth identity length: 81 octets - 75 74 61 30 4d 30 69 79 49 73 4d 77 57 70 35 54 - 54 64 53 64 6e 4f 4c 76 67 32 58 44 56 66 32 31 - 4f 59 74 31 76 6e 66 69 4d 63 73 35 64 6e 49 44 - 48 4f 49 46 56 61 76 49 52 7a 4d 52 79 7a 57 36 - 76 46 7a 64 48 57 40 65 61 70 73 69 6d 2e 66 6f - 6f - 00 00 00 ; (attribute padding) - - - - - - - - - - - - - - - - - - -Haverinen & Salowey Informational [Page 87] - -RFC 4186 EAP-SIM Authentication January 2006 - - - The EAP packet looks like this: - - 01 ; Code: Request - 01 ; Identifier: 1 - 00 a4 ; Length: 164 octets - 12 ; Type: EAP-SIM - 0d ; EAP-SIM subtype: Re-authentication - 00 00 ; (reserved) - 81 ; Attribute type: AT_IV - 05 ; Attribute length: 20 octets (5*4) - 00 00 ; (reserved) - d5 85 ac 77 ; IV value - 86 b9 03 36 - 65 7c 77 b4 - 65 75 b9 c4 - 82 ; Attribute type: AT_ENCR_DATA - 1d ; Attribute length: 116 octets (29*4) - 00 00 ; (reserved) - 68 62 91 a9 d2 ab c5 8c aa 32 94 b6 e8 5b 44 84 - 6c 44 e5 dc b2 de 8b 9e 80 d6 9d 49 85 8a 5d b8 - 4c dc 1c 9b c9 5c 01 b9 6b 6e ca 31 34 74 ae a6 - d3 14 16 e1 9d aa 9d f7 0f 05 00 88 41 ca 80 14 - 96 4d 3b 30 a4 9b cf 43 e4 d3 f1 8e 86 29 5a 4a - 2b 38 d9 6c 97 05 c2 bb b0 5c 4a ac e9 7d 5e af - f5 64 04 6c 8b d3 0b c3 9b e5 e1 7a ce 2b 10 a6 - 0b ; Attribute type: AT_MAC - 05 ; Attribute length: 20 octets (5*4) - 00 00 ; (reserved) - 48 3a 17 99 ; MAC value - b8 3d 7c d3 - d0 a1 e4 01 - d9 ee 47 70 - - The MAC is calculated over the EAP packet above (with MAC value set - to zero; a total of 164 bytes). - - Finally, the server derives new keys. The XKEY' is calculated as - described in Section 7*: - - XKEY' = 863dc120 32e08343 c1a2308d b48377f6 801f58d4 - - - - - - - - - - - -Haverinen & Salowey Informational [Page 88] - -RFC 4186 EAP-SIM Authentication January 2006 - - - The new MSK and EMSK are derived using the PRNG (note that K_encr and - K_aut stay the same). - - MSK = 6263f614 973895e1 335f7e30 cff028ee - 2176f519 002c9abe 732fe0ef 00cf167c - 756d9e4c ed6d5ed6 40eb3fe3 8565ca07 - 6e7fb8a8 17cfe8d9 adbce441 d47c4f5e - EMSK = 3d8ff786 3a630b2b 06e2cf20 9684c13f - 6b82f992 f2b06f1b 54bf51ef 237f2a40 - 1ef5e0d7 e098a34c 533eaebf 34578854 - b7721526 20a777f0 e0340884 a294fb73 - -A.10. EAP-Response/SIM/Re-authentication - - The client's response includes the counter as well. The following - plaintext will be encrypted and stored in the AT_ENCR_DATA attribute: - - 13 ; Attribute type: AT_COUNTER - 01 ; Attribute length: 4 octets (1*4) - 00 01 ; Counter value - 06 ; Attribute type: AT_PADDING - 03 ; Attribute length: 12 octets (3*4) - 00 00 00 00 - 00 00 00 00 - 00 00 - - The EAP packet looks like this: - - 02 ; Code: Response - 01 ; Identifier: 1 - 00 44 ; Length: 68 octets - 12 ; Type: EAP-SIM - 0d ; EAP-SIM subtype: Re-authentication - 00 00 ; (reserved) - 81 ; Attribute type: AT_IV - 05 ; Attribute length: 20 octets (5*4) - 00 00 ; (reserved) - cd f7 ff a6 ; IV value - 5d e0 4c 02 - 6b 56 c8 6b - 76 b1 02 ea - 82 ; Attribute type: AT_ENCR_DATA - 05 ; Attribute length: 20 octets (5*4) - 00 00 ; (reserved) - b6 ed d3 82 - 79 e2 a1 42 - 3c 1a fc 5c - 45 5c 7d 56 - - - -Haverinen & Salowey Informational [Page 89] - -RFC 4186 EAP-SIM Authentication January 2006 - - - 0b ; Attribute type: AT_MAC - 05 ; Attribute length: 20 octets (5*4) - 00 00 ; (reserved) - fa f7 6b 71 ; MAC value - fb e2 d2 55 - b9 6a 35 66 - c9 15 c6 17 - - The MAC is calculated over the EAP packet above (with MAC value set - to zero), followed by the NONCE_S value (a total of 84 bytes). - - The next packet will be EAP-Success: - - 03 ; Code: Success - 01 ; Identifier: 1 - 00 04 ; Length: 4 octets - -Appendix B. Pseudo-Random Number Generator - - The "|" character denotes concatenation, and "^" denotes - exponentiation. - - Step 1: Choose a new, secret value for the seed-key, XKEY - - Step 2: In hexadecimal notation let - t = 67452301 EFCDAB89 98BADCFE 10325476 C3D2E1F0 - This is the initial value for H0|H1|H2|H3|H4 - in the FIPS SHS [SHA-1] - - Step 3: For j = 0 to m - 1 do - 3.1 XSEED_j = 0 /* no optional user input */ - 3.2 For i = 0 to 1 do - a. XVAL = (XKEY + XSEED_j) mod 2^b - b. w_i = G(t, XVAL) - c. XKEY = (1 + XKEY + w_i) mod 2^b - 3.3 x_j = w_0|w_1 - - - - - - - - - - - - - - - -Haverinen & Salowey Informational [Page 90] - -RFC 4186 EAP-SIM Authentication January 2006 - - -Authors' Addresses - - Henry Haverinen (editor) - Nokia Enterprise Solutions - P.O. Box 12 - FIN-40101 Jyvaskyla - Finland - - EMail: henry.haverinen@nokia.com - - - Joseph Salowey (editor) - Cisco Systems - 2901 Third Avenue - Seattle, WA 98121 - USA - - Phone: +1 206 256 3380 - EMail: jsalowey@cisco.com - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Haverinen & Salowey Informational [Page 91] - -RFC 4186 EAP-SIM Authentication January 2006 - - -Full Copyright Statement - - Copyright (C) The Internet Society (2006). - - This document is subject to the rights, licenses and restrictions - contained in BCP 78, and except as set forth therein, the authors - retain all their rights. - - This document and the information contained herein are provided on an - "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS - OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET - ENGINEERING TASK FORCE DISCLAIM 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. - -Intellectual Property - - The IETF takes no position regarding the validity or scope of any - Intellectual Property Rights or other rights that might be claimed to - pertain to the implementation or use of the technology described in - this document or the extent to which any license under such rights - might or might not be available; nor does it represent that it has - made any independent effort to identify any such rights. Information - on the procedures with respect to rights in RFC documents can be - found in BCP 78 and BCP 79. - - Copies of IPR disclosures made to the IETF Secretariat and any - assurances of licenses to be made available, or the result of an - attempt made to obtain a general license or permission for the use of - such proprietary rights by implementers or users of this - specification can be obtained from the IETF on-line IPR repository at - http://www.ietf.org/ipr. - - The IETF invites any interested party to bring to its attention any - copyrights, patents or patent applications, or other proprietary - rights that may cover technology that may be required to implement - this standard. Please address the information to the IETF at - ietf-ipr@ietf.org. - -Acknowledgement - - Funding for the RFC Editor function is provided by the IETF - Administrative Support Activity (IASA). - - - - - - - -Haverinen & Salowey Informational [Page 92] - diff --git a/src/charon/doc/standards/rfc4301.txt b/src/charon/doc/standards/rfc4301.txt deleted file mode 100644 index 4a8eba975..000000000 --- a/src/charon/doc/standards/rfc4301.txt +++ /dev/null @@ -1,5659 +0,0 @@ - - - - - - -Network Working Group S. Kent -Request for Comments: 4301 K. Seo -Obsoletes: 2401 BBN Technologies -Category: Standards Track December 2005 - - - Security Architecture for the Internet Protocol - -Status of This Memo - - This document specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" (STD 1) for the standardization state - and status of this protocol. Distribution of this memo is unlimited. - -Copyright Notice - - Copyright (C) The Internet Society (2005). - -Abstract - - This document describes an updated version of the "Security - Architecture for IP", which is designed to provide security services - for traffic at the IP layer. This document obsoletes RFC 2401 - (November 1998). - -Dedication - - This document is dedicated to the memory of Charlie Lynn, a long-time - senior colleague at BBN, who made very significant contributions to - the IPsec documents. - - - - - - - - - - - - - - - - - - - -Kent & Seo Standards Track [Page 1] - -RFC 4301 Security Architecture for IP December 2005 - - -Table of Contents - - 1. Introduction ....................................................4 - 1.1. Summary of Contents of Document ............................4 - 1.2. Audience ...................................................4 - 1.3. Related Documents ..........................................5 - 2. Design Objectives ...............................................5 - 2.1. Goals/Objectives/Requirements/Problem Description ..........5 - 2.2. Caveats and Assumptions ....................................6 - 3. System Overview .................................................7 - 3.1. What IPsec Does ............................................7 - 3.2. How IPsec Works ............................................9 - 3.3. Where IPsec Can Be Implemented ............................10 - 4. Security Associations ..........................................11 - 4.1. Definition and Scope ......................................12 - 4.2. SA Functionality ..........................................16 - 4.3. Combining SAs .............................................17 - 4.4. Major IPsec Databases .....................................18 - 4.4.1. The Security Policy Database (SPD) .................19 - 4.4.1.1. Selectors .................................26 - 4.4.1.2. Structure of an SPD Entry .................30 - 4.4.1.3. More Regarding Fields Associated - with Next Layer Protocols .................32 - 4.4.2. Security Association Database (SAD) ................34 - 4.4.2.1. Data Items in the SAD .....................36 - 4.4.2.2. Relationship between SPD, PFP - flag, packet, and SAD .....................38 - 4.4.3. Peer Authorization Database (PAD) ..................43 - 4.4.3.1. PAD Entry IDs and Matching Rules ..........44 - 4.4.3.2. IKE Peer Authentication Data ..............45 - 4.4.3.3. Child SA Authorization Data ...............46 - 4.4.3.4. How the PAD Is Used .......................46 - 4.5. SA and Key Management .....................................47 - 4.5.1. Manual Techniques ..................................48 - 4.5.2. Automated SA and Key Management ....................48 - 4.5.3. Locating a Security Gateway ........................49 - 4.6. SAs and Multicast .........................................50 - 5. IP Traffic Processing ..........................................50 - 5.1. Outbound IP Traffic Processing - (protected-to-unprotected) ................................52 - 5.1.1. Handling an Outbound Packet That Must Be - Discarded ..........................................54 - 5.1.2. Header Construction for Tunnel Mode ................55 - 5.1.2.1. IPv4: Header Construction for - Tunnel Mode ...............................57 - 5.1.2.2. IPv6: Header Construction for - Tunnel Mode ...............................59 - 5.2. Processing Inbound IP Traffic (unprotected-to-protected) ..59 - - - -Kent & Seo Standards Track [Page 2] - -RFC 4301 Security Architecture for IP December 2005 - - - 6. ICMP Processing ................................................63 - 6.1. Processing ICMP Error Messages Directed to an - IPsec Implementation ......................................63 - 6.1.1. ICMP Error Messages Received on the - Unprotected Side of the Boundary ...................63 - 6.1.2. ICMP Error Messages Received on the - Protected Side of the Boundary .....................64 - 6.2. Processing Protected, Transit ICMP Error Messages .........64 - 7. Handling Fragments (on the protected side of the IPsec - boundary) ......................................................66 - 7.1. Tunnel Mode SAs that Carry Initial and Non-Initial - Fragments .................................................67 - 7.2. Separate Tunnel Mode SAs for Non-Initial Fragments ........67 - 7.3. Stateful Fragment Checking ................................68 - 7.4. BYPASS/DISCARD Traffic ....................................69 - 8. Path MTU/DF Processing .........................................69 - 8.1. DF Bit ....................................................69 - 8.2. Path MTU (PMTU) Discovery .................................70 - 8.2.1. Propagation of PMTU ................................70 - 8.2.2. PMTU Aging .........................................71 - 9. Auditing .......................................................71 - 10. Conformance Requirements ......................................71 - 11. Security Considerations .......................................72 - 12. IANA Considerations ...........................................72 - 13. Differences from RFC 2401 .....................................72 - 14. Acknowledgements ..............................................75 - Appendix A: Glossary ..............................................76 - Appendix B: Decorrelation .........................................79 - B.1. Decorrelation Algorithm ...................................79 - Appendix C: ASN.1 for an SPD Entry ................................82 - Appendix D: Fragment Handling Rationale ...........................88 - D.1. Transport Mode and Fragments ..............................88 - D.2. Tunnel Mode and Fragments .................................89 - D.3. The Problem of Non-Initial Fragments ......................90 - D.4. BYPASS/DISCARD Traffic ....................................93 - D.5. Just say no to ports? .....................................94 - D.6. Other Suggested Solutions..................................94 - D.7. Consistency................................................95 - D.8. Conclusions................................................95 - Appendix E: Example of Supporting Nested SAs via SPD and - Forwarding Table Entries...............................96 - References.........................................................98 - Normative References............................................98 - Informative References..........................................99 - - - - - - - -Kent & Seo Standards Track [Page 3] - -RFC 4301 Security Architecture for IP December 2005 - - -1. Introduction - -1.1. Summary of Contents of Document - - This document specifies the base architecture for IPsec-compliant - systems. It describes how to provide a set of security services for - traffic at the IP layer, in both the IPv4 [Pos81a] and IPv6 [DH98] - environments. This document describes the requirements for systems - that implement IPsec, the fundamental elements of such systems, and - how the elements fit together and fit into the IP environment. It - also describes the security services offered by the IPsec protocols, - and how these services can be employed in the IP environment. This - document does not address all aspects of the IPsec architecture. - Other documents address additional architectural details in - specialized environments, e.g., use of IPsec in Network Address - Translation (NAT) environments and more comprehensive support for IP - multicast. The fundamental components of the IPsec security - architecture are discussed in terms of their underlying, required - functionality. Additional RFCs (see Section 1.3 for pointers to - other documents) define the protocols in (a), (c), and (d). - - a. Security Protocols -- Authentication Header (AH) and - Encapsulating Security Payload (ESP) - b. Security Associations -- what they are and how they work, - how they are managed, associated processing - c. Key Management -- manual and automated (The Internet Key - Exchange (IKE)) - d. Cryptographic algorithms for authentication and encryption - - This document is not a Security Architecture for the Internet; it - addresses security only at the IP layer, provided through the use of - a combination of cryptographic and protocol security mechanisms. - - The spelling "IPsec" is preferred and used throughout this and all - related IPsec standards. All other capitalizations of IPsec (e.g., - IPSEC, IPSec, ipsec) are deprecated. However, any capitalization of - the sequence of letters "IPsec" should be understood to refer to the - IPsec protocols. - - 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 RFC 2119 [Bra97]. - -1.2. Audience - - The target audience for this document is primarily individuals who - implement this IP security technology or who architect systems that - will use this technology. Technically adept users of this technology - - - -Kent & Seo Standards Track [Page 4] - -RFC 4301 Security Architecture for IP December 2005 - - - (end users or system administrators) also are part of the target - audience. A glossary is provided in Appendix A to help fill in gaps - in background/vocabulary. This document assumes that the reader is - familiar with the Internet Protocol (IP), related networking - technology, and general information system security terms and - concepts. - -1.3. Related Documents - - As mentioned above, other documents provide detailed definitions of - some of the components of IPsec and of their interrelationship. They - include RFCs on the following topics: - - a. security protocols -- RFCs describing the Authentication - Header (AH) [Ken05b] and Encapsulating Security Payload - (ESP) [Ken05a] protocols. - b. cryptographic algorithms for integrity and encryption -- one - RFC that defines the mandatory, default algorithms for use - with AH and ESP [Eas05], a similar RFC that defines the - mandatory algorithms for use with IKEv2 [Sch05] plus a - separate RFC for each cryptographic algorithm. - c. automatic key management -- RFCs on "The Internet Key - Exchange (IKEv2) Protocol" [Kau05] and "Cryptographic - Algorithms for Use in the Internet Key Exchange Version 2 - (IKEv2)" [Sch05]. - -2. Design Objectives - -2.1. Goals/Objectives/Requirements/Problem Description - - IPsec is designed to provide interoperable, high quality, - cryptographically-based security for IPv4 and IPv6. The set of - security services offered includes access control, connectionless - integrity, data origin authentication, detection and rejection of - replays (a form of partial sequence integrity), confidentiality (via - encryption), and limited traffic flow confidentiality. These - services are provided at the IP layer, offering protection in a - standard fashion for all protocols that may be carried over IP - (including IP itself). - - IPsec includes a specification for minimal firewall functionality, - since that is an essential aspect of access control at the IP layer. - Implementations are free to provide more sophisticated firewall - mechanisms, and to implement the IPsec-mandated functionality using - those more sophisticated mechanisms. (Note that interoperability may - suffer if additional firewall constraints on traffic flows are - imposed by an IPsec implementation but cannot be negotiated based on - the traffic selector features defined in this document and negotiated - - - -Kent & Seo Standards Track [Page 5] - -RFC 4301 Security Architecture for IP December 2005 - - - via IKEv2.) The IPsec firewall function makes use of the - cryptographically-enforced authentication and integrity provided for - all IPsec traffic to offer better access control than could be - obtained through use of a firewall (one not privy to IPsec internal - parameters) plus separate cryptographic protection. - - Most of the security services are provided through use of two traffic - security protocols, the Authentication Header (AH) and the - Encapsulating Security Payload (ESP), and through the use of - cryptographic key management procedures and protocols. The set of - IPsec protocols employed in a context, and the ways in which they are - employed, will be determined by the users/administrators in that - context. It is the goal of the IPsec architecture to ensure that - compliant implementations include the services and management - interfaces needed to meet the security requirements of a broad user - population. - - When IPsec is correctly implemented and deployed, it ought not - adversely affect users, hosts, and other Internet components that do - not employ IPsec for traffic protection. IPsec security protocols - (AH and ESP, and to a lesser extent, IKE) are designed to be - cryptographic algorithm independent. This modularity permits - selection of different sets of cryptographic algorithms as - appropriate, without affecting the other parts of the implementation. - For example, different user communities may select different sets of - cryptographic algorithms (creating cryptographically-enforced - cliques) if required. - - To facilitate interoperability in the global Internet, a set of - default cryptographic algorithms for use with AH and ESP is specified - in [Eas05] and a set of mandatory-to-implement algorithms for IKEv2 - is specified in [Sch05]. [Eas05] and [Sch05] will be periodically - updated to keep pace with computational and cryptologic advances. By - specifying these algorithms in documents that are separate from the - AH, ESP, and IKEv2 specifications, these algorithms can be updated or - replaced without affecting the standardization progress of the rest - of the IPsec document suite. The use of these cryptographic - algorithms, in conjunction with IPsec traffic protection and key - management protocols, is intended to permit system and application - developers to deploy high quality, Internet-layer, cryptographic - security technology. - -2.2. Caveats and Assumptions - - The suite of IPsec protocols and associated default cryptographic - algorithms are designed to provide high quality security for Internet - traffic. However, the security offered by use of these protocols - ultimately depends on the quality of their implementation, which is - - - -Kent & Seo Standards Track [Page 6] - -RFC 4301 Security Architecture for IP December 2005 - - - outside the scope of this set of standards. Moreover, the security - of a computer system or network is a function of many factors, - including personnel, physical, procedural, compromising emanations, - and computer security practices. Thus, IPsec is only one part of an - overall system security architecture. - - Finally, the security afforded by the use of IPsec is critically - dependent on many aspects of the operating environment in which the - IPsec implementation executes. For example, defects in OS security, - poor quality of random number sources, sloppy system management - protocols and practices, etc., can all degrade the security provided - by IPsec. As above, none of these environmental attributes are - within the scope of this or other IPsec standards. - -3. System Overview - - This section provides a high level description of how IPsec works, - the components of the system, and how they fit together to provide - the security services noted above. The goal of this description is - to enable the reader to "picture" the overall process/system, see how - it fits into the IP environment, and to provide context for later - sections of this document, which describe each of the components in - more detail. - - An IPsec implementation operates in a host, as a security gateway - (SG), or as an independent device, affording protection to IP - traffic. (A security gateway is an intermediate system implementing - IPsec, e.g., a firewall or router that has been IPsec-enabled.) More - detail on these classes of implementations is provided later, in - Section 3.3. The protection offered by IPsec is based on requirements - defined by a Security Policy Database (SPD) established and - maintained by a user or system administrator, or by an application - operating within constraints established by either of the above. In - general, packets are selected for one of three processing actions - based on IP and next layer header information ("Selectors", Section - 4.4.1.1) matched against entries in the SPD. Each packet is either - PROTECTed using IPsec security services, DISCARDed, or allowed to - BYPASS IPsec protection, based on the applicable SPD policies - identified by the Selectors. - -3.1. What IPsec Does - - IPsec creates a boundary between unprotected and protected - interfaces, for a host or a network (see Figure 1 below). Traffic - traversing the boundary is subject to the access controls specified - by the user or administrator responsible for the IPsec configuration. - These controls indicate whether packets cross the boundary unimpeded, - are afforded security services via AH or ESP, or are discarded. - - - -Kent & Seo Standards Track [Page 7] - -RFC 4301 Security Architecture for IP December 2005 - - - IPsec security services are offered at the IP layer through selection - of appropriate security protocols, cryptographic algorithms, and - cryptographic keys. IPsec can be used to protect one or more "paths" - (a) between a pair of hosts, (b) between a pair of security gateways, - or (c) between a security gateway and a host. A compliant host - implementation MUST support (a) and (c) and a compliant security - gateway must support all three of these forms of connectivity, since - under certain circumstances a security gateway acts as a host. - - Unprotected - ^ ^ - | | - +-------------|-------|-------+ - | +-------+ | | | - | |Discard|<--| V | - | +-------+ |B +--------+ | - ................|y..| AH/ESP |..... IPsec Boundary - | +---+ |p +--------+ | - | |IKE|<----|a ^ | - | +---+ |s | | - | +-------+ |s | | - | |Discard|<--| | | - | +-------+ | | | - +-------------|-------|-------+ - | | - V V - Protected - - Figure 1. Top Level IPsec Processing Model - - In this diagram, "unprotected" refers to an interface that might also - be described as "black" or "ciphertext". Here, "protected" refers to - an interface that might also be described as "red" or "plaintext". - The protected interface noted above may be internal, e.g., in a host - implementation of IPsec, the protected interface may link to a socket - layer interface presented by the OS. In this document, the term - "inbound" refers to traffic entering an IPsec implementation via the - unprotected interface or emitted by the implementation on the - unprotected side of the boundary and directed towards the protected - interface. The term "outbound" refers to traffic entering the - implementation via the protected interface, or emitted by the - implementation on the protected side of the boundary and directed - toward the unprotected interface. An IPsec implementation may - support more than one interface on either or both sides of the - boundary. - - - - - - -Kent & Seo Standards Track [Page 8] - -RFC 4301 Security Architecture for IP December 2005 - - - Note the facilities for discarding traffic on either side of the - IPsec boundary, the BYPASS facility that allows traffic to transit - the boundary without cryptographic protection, and the reference to - IKE as a protected-side key and security management function. - - IPsec optionally supports negotiation of IP compression [SMPT01], - motivated in part by the observation that when encryption is employed - within IPsec, it prevents effective compression by lower protocol - layers. - -3.2. How IPsec Works - - IPsec uses two protocols to provide traffic security services -- - Authentication Header (AH) and Encapsulating Security Payload (ESP). - Both protocols are described in detail in their respective RFCs - [Ken05b, Ken05a]. IPsec implementations MUST support ESP and MAY - support AH. (Support for AH has been downgraded to MAY because - experience has shown that there are very few contexts in which ESP - cannot provide the requisite security services. Note that ESP can be - used to provide only integrity, without confidentiality, making it - comparable to AH in most contexts.) - - o The IP Authentication Header (AH) [Ken05b] offers integrity and - data origin authentication, with optional (at the discretion of - the receiver) anti-replay features. - - o The Encapsulating Security Payload (ESP) protocol [Ken05a] offers - the same set of services, and also offers confidentiality. Use of - ESP to provide confidentiality without integrity is NOT - RECOMMENDED. When ESP is used with confidentiality enabled, there - are provisions for limited traffic flow confidentiality, i.e., - provisions for concealing packet length, and for facilitating - efficient generation and discard of dummy packets. This - capability is likely to be effective primarily in virtual private - network (VPN) and overlay network contexts. - - o Both AH and ESP offer access control, enforced through the - distribution of cryptographic keys and the management of traffic - flows as dictated by the Security Policy Database (SPD, Section - 4.4.1). - - These protocols may be applied individually or in combination with - each other to provide IPv4 and IPv6 security services. However, most - security requirements can be met through the use of ESP by itself. - Each protocol supports two modes of use: transport mode and tunnel - mode. In transport mode, AH and ESP provide protection primarily for - - - - - -Kent & Seo Standards Track [Page 9] - -RFC 4301 Security Architecture for IP December 2005 - - - next layer protocols; in tunnel mode, AH and ESP are applied to - tunneled IP packets. The differences between the two modes are - discussed in Section 4.1. - - IPsec allows the user (or system administrator) to control the - granularity at which a security service is offered. For example, one - can create a single encrypted tunnel to carry all the traffic between - two security gateways, or a separate encrypted tunnel can be created - for each TCP connection between each pair of hosts communicating - across these gateways. IPsec, through the SPD management paradigm, - incorporates facilities for specifying: - - o which security protocol (AH or ESP) to employ, the mode (transport - or tunnel), security service options, what cryptographic - algorithms to use, and in what combinations to use the specified - protocols and services, and - - o the granularity at which protection should be applied. - - Because most of the security services provided by IPsec require the - use of cryptographic keys, IPsec relies on a separate set of - mechanisms for putting these keys in place. This document requires - support for both manual and automated distribution of keys. It - specifies a specific public-key based approach (IKEv2 [Kau05]) for - automated key management, but other automated key distribution - techniques MAY be used. - - Note: This document mandates support for several features for which - support is available in IKEv2 but not in IKEv1, e.g., negotiation of - an SA representing ranges of local and remote ports or negotiation of - multiple SAs with the same selectors. Therefore, this document - assumes use of IKEv2 or a key and security association management - system with comparable features. - -3.3. Where IPsec Can Be Implemented - - There are many ways in which IPsec may be implemented in a host, or - in conjunction with a router or firewall to create a security - gateway, or as an independent security device. - - a. IPsec may be integrated into the native IP stack. This requires - access to the IP source code and is applicable to both hosts and - security gateways, although native host implementations benefit - the most from this strategy, as explained later (Section 4.4.1, - paragraph 6; Section 4.4.1.1, last paragraph). - - - - - - -Kent & Seo Standards Track [Page 10] - -RFC 4301 Security Architecture for IP December 2005 - - - b. In a "bump-in-the-stack" (BITS) implementation, IPsec is - implemented "underneath" an existing implementation of an IP - protocol stack, between the native IP and the local network - drivers. Source code access for the IP stack is not required in - this context, making this implementation approach appropriate for - use with legacy systems. This approach, when it is adopted, is - usually employed in hosts. - - c. The use of a dedicated, inline security protocol processor is a - common design feature of systems used by the military, and of some - commercial systems as well. It is sometimes referred to as a - "bump-in-the-wire" (BITW) implementation. Such implementations - may be designed to serve either a host or a gateway. Usually, the - BITW device is itself IP addressable. When supporting a single - host, it may be quite analogous to a BITS implementation, but in - supporting a router or firewall, it must operate like a security - gateway. - - This document often talks in terms of use of IPsec by a host or a - security gateway, without regard to whether the implementation is - native, BITS, or BITW. When the distinctions among these - implementation options are significant, the document makes reference - to specific implementation approaches. - - A host implementation of IPsec may appear in devices that might not - be viewed as "hosts". For example, a router might employ IPsec to - protect routing protocols (e.g., BGP) and management functions (e.g., - Telnet), without affecting subscriber traffic traversing the router. - A security gateway might employ separate IPsec implementations to - protect its management traffic and subscriber traffic. The - architecture described in this document is very flexible. For - example, a computer with a full-featured, compliant, native OS IPsec - implementation should be capable of being configured to protect - resident (host) applications and to provide security gateway - protection for traffic traversing the computer. Such configuration - would make use of the forwarding tables and the SPD selection - function described in Sections 5.1 and 5.2. - -4. Security Associations - - This section defines Security Association management requirements for - all IPv6 implementations and for those IPv4 implementations that - implement AH, ESP, or both AH and ESP. The concept of a "Security - Association" (SA) is fundamental to IPsec. Both AH and ESP make use - of SAs, and a major function of IKE is the establishment and - maintenance of SAs. All implementations of AH or ESP MUST support - the concept of an SA as described below. The remainder of this - - - - -Kent & Seo Standards Track [Page 11] - -RFC 4301 Security Architecture for IP December 2005 - - - section describes various aspects of SA management, defining required - characteristics for SA policy management and SA management - techniques. - -4.1. Definition and Scope - - An SA is a simplex "connection" that affords security services to the - traffic carried by it. Security services are afforded to an SA by - the use of AH, or ESP, but not both. If both AH and ESP protection - are applied to a traffic stream, then two SAs must be created and - coordinated to effect protection through iterated application of the - security protocols. To secure typical, bi-directional communication - between two IPsec-enabled systems, a pair of SAs (one in each - direction) is required. IKE explicitly creates SA pairs in - recognition of this common usage requirement. - - For an SA used to carry unicast traffic, the Security Parameters - Index (SPI) by itself suffices to specify an SA. (For information on - the SPI, see Appendix A and the AH and ESP specifications [Ken05b, - Ken05a].) However, as a local matter, an implementation may choose - to use the SPI in conjunction with the IPsec protocol type (AH or - ESP) for SA identification. If an IPsec implementation supports - multicast, then it MUST support multicast SAs using the algorithm - below for mapping inbound IPsec datagrams to SAs. Implementations - that support only unicast traffic need not implement this de- - multiplexing algorithm. - - In many secure multicast architectures, e.g., [RFC3740], a central - Group Controller/Key Server unilaterally assigns the Group Security - Association's (GSA's) SPI. This SPI assignment is not negotiated or - coordinated with the key management (e.g., IKE) subsystems that - reside in the individual end systems that constitute the group. - Consequently, it is possible that a GSA and a unicast SA can - simultaneously use the same SPI. A multicast-capable IPsec - implementation MUST correctly de-multiplex inbound traffic even in - the context of SPI collisions. - - Each entry in the SA Database (SAD) (Section 4.4.2) must indicate - whether the SA lookup makes use of the destination IP address, or the - destination and source IP addresses, in addition to the SPI. For - multicast SAs, the protocol field is not employed for SA lookups. - For each inbound, IPsec-protected packet, an implementation must - conduct its search of the SAD such that it finds the entry that - matches the "longest" SA identifier. In this context, if two or more - SAD entries match based on the SPI value, then the entry that also - matches based on destination address, or destination and source - address (as indicated in the SAD entry) is the "longest" match. This - implies a logical ordering of the SAD search as follows: - - - -Kent & Seo Standards Track [Page 12] - -RFC 4301 Security Architecture for IP December 2005 - - - 1. Search the SAD for a match on the combination of SPI, - destination address, and source address. If an SAD entry - matches, then process the inbound packet with that - matching SAD entry. Otherwise, proceed to step 2. - - 2. Search the SAD for a match on both SPI and destination address. - If the SAD entry matches, then process the inbound packet - with that matching SAD entry. Otherwise, proceed to step 3. - - 3. Search the SAD for a match on only SPI if the receiver has - chosen to maintain a single SPI space for AH and ESP, and on - both SPI and protocol, otherwise. If an SAD entry matches, - then process the inbound packet with that matching SAD entry. - Otherwise, discard the packet and log an auditable event. - - In practice, an implementation may choose any method (or none at all) - to accelerate this search, although its externally visible behavior - MUST be functionally equivalent to having searched the SAD in the - above order. For example, a software-based implementation could - index into a hash table by the SPI. The SAD entries in each hash - table bucket's linked list could be kept sorted to have those SAD - entries with the longest SA identifiers first in that linked list. - Those SAD entries having the shortest SA identifiers could be sorted - so that they are the last entries in the linked list. A - hardware-based implementation may be able to effect the longest match - search intrinsically, using commonly available Ternary - Content-Addressable Memory (TCAM) features. - - The indication of whether source and destination address matching is - required to map inbound IPsec traffic to SAs MUST be set either as a - side effect of manual SA configuration or via negotiation using an SA - management protocol, e.g., IKE or Group Domain of Interpretation - (GDOI) [RFC3547]. Typically, Source-Specific Multicast (SSM) [HC03] - groups use a 3-tuple SA identifier composed of an SPI, a destination - multicast address, and source address. An Any-Source Multicast group - SA requires only an SPI and a destination multicast address as an - identifier. - - If different classes of traffic (distinguished by Differentiated - Services Code Point (DSCP) bits [NiBlBaBL98], [Gro02]) are sent on - the same SA, and if the receiver is employing the optional - anti-replay feature available in both AH and ESP, this could result - in inappropriate discarding of lower priority packets due to the - windowing mechanism used by this feature. Therefore, a sender SHOULD - put traffic of different classes, but with the same selector values, - on different SAs to support Quality of Service (QoS) appropriately. - To permit this, the IPsec implementation MUST permit establishment - and maintenance of multiple SAs between a given sender and receiver, - - - -Kent & Seo Standards Track [Page 13] - -RFC 4301 Security Architecture for IP December 2005 - - - with the same selectors. Distribution of traffic among these - parallel SAs to support QoS is locally determined by the sender and - is not negotiated by IKE. The receiver MUST process the packets from - the different SAs without prejudice. These requirements apply to - both transport and tunnel mode SAs. In the case of tunnel mode SAs, - the DSCP values in question appear in the inner IP header. In - transport mode, the DSCP value might change en route, but this should - not cause problems with respect to IPsec processing since the value - is not employed for SA selection and MUST NOT be checked as part of - SA/packet validation. However, if significant re-ordering of packets - occurs in an SA, e.g., as a result of changes to DSCP values en - route, this may trigger packet discarding by a receiver due to - application of the anti-replay mechanism. - - DISCUSSION: Although the DSCP [NiBlBaBL98, Gro02] and Explicit - Congestion Notification (ECN) [RaFlBl01] fields are not "selectors", - as that term in used in this architecture, the sender will need a - mechanism to direct packets with a given (set of) DSCP values to the - appropriate SA. This mechanism might be termed a "classifier". - - As noted above, two types of SAs are defined: transport mode and - tunnel mode. IKE creates pairs of SAs, so for simplicity, we choose - to require that both SAs in a pair be of the same mode, transport or - tunnel. - - A transport mode SA is an SA typically employed between a pair of - hosts to provide end-to-end security services. When security is - desired between two intermediate systems along a path (vs. end-to-end - use of IPsec), transport mode MAY be used between security gateways - or between a security gateway and a host. In the case where - transport mode is used between security gateways or between a - security gateway and a host, transport mode may be used to support - in-IP tunneling (e.g., IP-in-IP [Per96] or Generic Routing - Encapsulation (GRE) tunneling [FaLiHaMeTr00] or dynamic routing - [ToEgWa04]) over transport mode SAs. To clarify, the use of - transport mode by an intermediate system (e.g., a security gateway) - is permitted only when applied to packets whose source address (for - outbound packets) or destination address (for inbound packets) is an - address belonging to the intermediate system itself. The access - control functions that are an important part of IPsec are - significantly limited in this context, as they cannot be applied to - the end-to-end headers of the packets that traverse a transport mode - SA used in this fashion. Thus, this way of using transport mode - should be evaluated carefully before being employed in a specific - context. - - - - - - -Kent & Seo Standards Track [Page 14] - -RFC 4301 Security Architecture for IP December 2005 - - - In IPv4, a transport mode security protocol header appears - immediately after the IP header and any options, and before any next - layer protocols (e.g., TCP or UDP). In IPv6, the security protocol - header appears after the base IP header and selected extension - headers, but may appear before or after destination options; it MUST - appear before next layer protocols (e.g., TCP, UDP, Stream Control - Transmission Protocol (SCTP)). In the case of ESP, a transport mode - SA provides security services only for these next layer protocols, - not for the IP header or any extension headers preceding the ESP - header. In the case of AH, the protection is also extended to - selected portions of the IP header preceding it, selected portions of - extension headers, and selected options (contained in the IPv4 - header, IPv6 Hop-by-Hop extension header, or IPv6 Destination - extension headers). For more details on the coverage afforded by AH, - see the AH specification [Ken05b]. - - A tunnel mode SA is essentially an SA applied to an IP tunnel, with - the access controls applied to the headers of the traffic inside the - tunnel. Two hosts MAY establish a tunnel mode SA between themselves. - Aside from the two exceptions below, whenever either end of a - security association is a security gateway, the SA MUST be tunnel - mode. Thus, an SA between two security gateways is typically a - tunnel mode SA, as is an SA between a host and a security gateway. - The two exceptions are as follows. - - o Where traffic is destined for a security gateway, e.g., Simple - Network Management Protocol (SNMP) commands, the security gateway - is acting as a host and transport mode is allowed. In this case, - the SA terminates at a host (management) function within a - security gateway and thus merits different treatment. - - o As noted above, security gateways MAY support a transport mode SA - to provide security for IP traffic between two intermediate - systems along a path, e.g., between a host and a security gateway - or between two security gateways. - - Several concerns motivate the use of tunnel mode for an SA involving - a security gateway. For example, if there are multiple paths (e.g., - via different security gateways) to the same destination behind a - security gateway, it is important that an IPsec packet be sent to the - security gateway with which the SA was negotiated. Similarly, a - packet that might be fragmented en route must have all the fragments - delivered to the same IPsec instance for reassembly prior to - cryptographic processing. Also, when a fragment is processed by - IPsec and transmitted, then fragmented en route, it is critical that - there be inner and outer headers to retain the fragmentation state - data for the pre- and post-IPsec packet formats. Hence there are - several reasons for employing tunnel mode when either end of an SA is - - - -Kent & Seo Standards Track [Page 15] - -RFC 4301 Security Architecture for IP December 2005 - - - a security gateway. (Use of an IP-in-IP tunnel in conjunction with - transport mode can also address these fragmentation issues. However, - this configuration limits the ability of IPsec to enforce access - control policies on traffic.) - - Note: AH and ESP cannot be applied using transport mode to IPv4 - packets that are fragments. Only tunnel mode can be employed in such - cases. For IPv6, it would be feasible to carry a plaintext fragment - on a transport mode SA; however, for simplicity, this restriction - also applies to IPv6 packets. See Section 7 for more details on - handling plaintext fragments on the protected side of the IPsec - barrier. - - For a tunnel mode SA, there is an "outer" IP header that specifies - the IPsec processing source and destination, plus an "inner" IP - header that specifies the (apparently) ultimate source and - destination for the packet. The security protocol header appears - after the outer IP header, and before the inner IP header. If AH is - employed in tunnel mode, portions of the outer IP header are afforded - protection (as above), as well as all of the tunneled IP packet - (i.e., all of the inner IP header is protected, as well as next layer - protocols). If ESP is employed, the protection is afforded only to - the tunneled packet, not to the outer header. - - In summary, - - a) A host implementation of IPsec MUST support both transport and - tunnel mode. This is true for native, BITS, and BITW - implementations for hosts. - - b) A security gateway MUST support tunnel mode and MAY support - transport mode. If it supports transport mode, that should be - used only when the security gateway is acting as a host, e.g., for - network management, or to provide security between two - intermediate systems along a path. - -4.2. SA Functionality - - The set of security services offered by an SA depends on the security - protocol selected, the SA mode, the endpoints of the SA, and the - election of optional services within the protocol. - - For example, both AH and ESP offer integrity and authentication - services, but the coverage differs for each protocol and differs for - transport vs. tunnel mode. If the integrity of an IPv4 option or - IPv6 extension header must be protected en route between sender and - receiver, AH can provide this service, except for IP or extension - headers that may change in a fashion not predictable by the sender. - - - -Kent & Seo Standards Track [Page 16] - -RFC 4301 Security Architecture for IP December 2005 - - - However, the same security may be achieved in some contexts by - applying ESP to a tunnel carrying a packet. - - The granularity of access control provided is determined by the - choice of the selectors that define each SA. Moreover, the - authentication means employed by IPsec peers, e.g., during creation - of an IKE (vs. child) SA also affects the granularity of the access - control afforded. - - If confidentiality is selected, then an ESP (tunnel mode) SA between - two security gateways can offer partial traffic flow confidentiality. - The use of tunnel mode allows the inner IP headers to be encrypted, - concealing the identities of the (ultimate) traffic source and - destination. Moreover, ESP payload padding also can be invoked to - hide the size of the packets, further concealing the external - characteristics of the traffic. Similar traffic flow confidentiality - services may be offered when a mobile user is assigned a dynamic IP - address in a dialup context, and establishes a (tunnel mode) ESP SA - to a corporate firewall (acting as a security gateway). Note that - fine-granularity SAs generally are more vulnerable to traffic - analysis than coarse-granularity ones that are carrying traffic from - many subscribers. - - Note: A compliant implementation MUST NOT allow instantiation of an - ESP SA that employs both NULL encryption and no integrity algorithm. - An attempt to negotiate such an SA is an auditable event by both - initiator and responder. The audit log entry for this event SHOULD - include the current date/time, local IKE IP address, and remote IKE - IP address. The initiator SHOULD record the relevant SPD entry. - -4.3. Combining SAs - - This document does not require support for nested security - associations or for what RFC 2401 [RFC2401] called "SA bundles". - These features still can be effected by appropriate configuration of - both the SPD and the local forwarding functions (for inbound and - outbound traffic), but this capability is outside of the IPsec module - and thus the scope of this specification. As a result, management of - nested/bundled SAs is potentially more complex and less assured than - under the model implied by RFC 2401 [RFC2401]. An implementation - that provides support for nested SAs SHOULD provide a management - interface that enables a user or administrator to express the nesting - requirement, and then create the appropriate SPD entries and - forwarding table entries to effect the requisite processing. (See - Appendix E for an example of how to configure nested SAs.) - - - - - - -Kent & Seo Standards Track [Page 17] - -RFC 4301 Security Architecture for IP December 2005 - - -4.4. Major IPsec Databases - - Many of the details associated with processing IP traffic in an IPsec - implementation are largely a local matter, not subject to - standardization. However, some external aspects of the processing - must be standardized to ensure interoperability and to provide a - minimum management capability that is essential for productive use of - IPsec. This section describes a general model for processing IP - traffic relative to IPsec functionality, in support of these - interoperability and functionality goals. The model described below - is nominal; implementations need not match details of this model as - presented, but the external behavior of implementations MUST - correspond to the externally observable characteristics of this model - in order to be compliant. - - There are three nominal databases in this model: the Security Policy - Database (SPD), the Security Association Database (SAD), and the Peer - Authorization Database (PAD). The first specifies the policies that - determine the disposition of all IP traffic inbound or outbound from - a host or security gateway (Section 4.4.1). The second database - contains parameters that are associated with each established (keyed) - SA (Section 4.4.2). The third database, the PAD, provides a link - between an SA management protocol (such as IKE) and the SPD (Section - 4.4.3). - - Multiple Separate IPsec Contexts - - If an IPsec implementation acts as a security gateway for multiple - subscribers, it MAY implement multiple separate IPsec contexts. - Each context MAY have and MAY use completely independent - identities, policies, key management SAs, and/or IPsec SAs. This - is for the most part a local implementation matter. However, a - means for associating inbound (SA) proposals with local contexts - is required. To this end, if supported by the key management - protocol in use, context identifiers MAY be conveyed from - initiator to responder in the signaling messages, with the result - that IPsec SAs are created with a binding to a particular context. - For example, a security gateway that provides VPN service to - multiple customers will be able to associate each customer's - traffic with the correct VPN. - - Forwarding vs Security Decisions - - The IPsec model described here embodies a clear separation between - forwarding (routing) and security decisions, to accommodate a wide - range of contexts where IPsec may be employed. Forwarding may be - trivial, in the case where there are only two interfaces, or it - may be complex, e.g., if the context in which IPsec is implemented - - - -Kent & Seo Standards Track [Page 18] - -RFC 4301 Security Architecture for IP December 2005 - - - employs a sophisticated forwarding function. IPsec assumes only - that outbound and inbound traffic that has passed through IPsec - processing is forwarded in a fashion consistent with the context - in which IPsec is implemented. Support for nested SAs is - optional; if required, it requires coordination between forwarding - tables and SPD entries to cause a packet to traverse the IPsec - boundary more than once. - - "Local" vs "Remote" - - In this document, with respect to IP addresses and ports, the - terms "Local" and "Remote" are used for policy rules. "Local" - refers to the entity being protected by an IPsec implementation, - i.e., the "source" address/port of outbound packets or the - "destination" address/port of inbound packets. "Remote" refers to - a peer entity or peer entities. The terms "source" and - "destination" are used for packet header fields. - - "Non-initial" vs "Initial" Fragments - - Throughout this document, the phrase "non-initial fragments" is - used to mean fragments that do not contain all of the selector - values that may be needed for access control (e.g., they might not - contain Next Layer Protocol, source and destination ports, ICMP - message type/code, Mobility Header type). And the phrase "initial - fragment" is used to mean a fragment that contains all the - selector values needed for access control. However, it should be - noted that for IPv6, which fragment contains the Next Layer - Protocol and ports (or ICMP message type/code or Mobility Header - type [Mobip]) will depend on the kind and number of extension - headers present. The "initial fragment" might not be the first - fragment, in this context. - -4.4.1. The Security Policy Database (SPD) - - An SA is a management construct used to enforce security policy for - traffic crossing the IPsec boundary. Thus, an essential element of - SA processing is an underlying Security Policy Database (SPD) that - specifies what services are to be offered to IP datagrams and in what - fashion. The form of the database and its interface are outside the - scope of this specification. However, this section specifies minimum - management functionality that must be provided, to allow a user or - system administrator to control whether and how IPsec is applied to - traffic transmitted or received by a host or transiting a security - gateway. The SPD, or relevant caches, must be consulted during the - processing of all traffic (inbound and outbound), including traffic - not protected by IPsec, that traverses the IPsec boundary. This - includes IPsec management traffic such as IKE. An IPsec - - - -Kent & Seo Standards Track [Page 19] - -RFC 4301 Security Architecture for IP December 2005 - - - implementation MUST have at least one SPD, and it MAY support - multiple SPDs, if appropriate for the context in which the IPsec - implementation operates. There is no requirement to maintain SPDs on - a per-interface basis, as was specified in RFC 2401 [RFC2401]. - However, if an implementation supports multiple SPDs, then it MUST - include an explicit SPD selection function that is invoked to select - the appropriate SPD for outbound traffic processing. The inputs to - this function are the outbound packet and any local metadata (e.g., - the interface via which the packet arrived) required to effect the - SPD selection function. The output of the function is an SPD - identifier (SPD-ID). - - The SPD is an ordered database, consistent with the use of Access - Control Lists (ACLs) or packet filters in firewalls, routers, etc. - The ordering requirement arises because entries often will overlap - due to the presence of (non-trivial) ranges as values for selectors. - Thus, a user or administrator MUST be able to order the entries to - express a desired access control policy. There is no way to impose a - general, canonical order on SPD entries, because of the allowed use - of wildcards for selector values and because the different types of - selectors are not hierarchically related. - - Processing Choices: DISCARD, BYPASS, PROTECT - - An SPD must discriminate among traffic that is afforded IPsec - protection and traffic that is allowed to bypass IPsec. This - applies to the IPsec protection to be applied by a sender and to - the IPsec protection that must be present at the receiver. For - any outbound or inbound datagram, three processing choices are - possible: DISCARD, BYPASS IPsec, or PROTECT using IPsec. The - first choice refers to traffic that is not allowed to traverse the - IPsec boundary (in the specified direction). The second choice - refers to traffic that is allowed to cross the IPsec boundary - without IPsec protection. The third choice refers to traffic that - is afforded IPsec protection, and for such traffic the SPD must - specify the security protocols to be employed, their mode, - security service options, and the cryptographic algorithms to be - used. - - SPD-S, SPD-I, SPD-O - - An SPD is logically divided into three pieces. The SPD-S (secure - traffic) contains entries for all traffic subject to IPsec - protection. SPD-O (outbound) contains entries for all outbound - traffic that is to be bypassed or discarded. SPD-I (inbound) is - applied to inbound traffic that will be bypassed or discarded. - All three of these can be decorrelated (with the exception noted - above for native host implementations) to facilitate caching. If - - - -Kent & Seo Standards Track [Page 20] - -RFC 4301 Security Architecture for IP December 2005 - - - an IPsec implementation supports only one SPD, then the SPD - consists of all three parts. If multiple SPDs are supported, some - of them may be partial, e.g., some SPDs might contain only SPD-I - entries, to control inbound bypassed traffic on a per-interface - basis. The split allows SPD-I to be consulted without having to - consult SPD-S, for such traffic. Since the SPD-I is just a part - of the SPD, if a packet that is looked up in the SPD-I cannot be - matched to an entry there, then the packet MUST be discarded. - Note that for outbound traffic, if a match is not found in SPD-S, - then SPD-O must be checked to see if the traffic should be - bypassed. Similarly, if SPD-O is checked first and no match is - found, then SPD-S must be checked. In an ordered, - non-decorrelated SPD, the entries for the SPD-S, SPD-I, and SPD-O - are interleaved. So there is one lookup in the SPD. - - SPD Entries - - Each SPD entry specifies packet disposition as BYPASS, DISCARD, or - PROTECT. The entry is keyed by a list of one or more selectors. - The SPD contains an ordered list of these entries. The required - selector types are defined in Section 4.4.1.1. These selectors are - used to define the granularity of the SAs that are created in - response to an outbound packet or in response to a proposal from a - peer. The detailed structure of an SPD entry is described in - Section 4.4.1.2. Every SPD SHOULD have a nominal, final entry that - matches anything that is otherwise unmatched, and discards it. - - The SPD MUST permit a user or administrator to specify policy - entries as follows: - - - SPD-I: For inbound traffic that is to be bypassed or discarded, - the entry consists of the values of the selectors that apply to - the traffic to be bypassed or discarded. - - - SPD-O: For outbound traffic that is to be bypassed or - discarded, the entry consists of the values of the selectors - that apply to the traffic to be bypassed or discarded. - - - SPD-S: For traffic that is to be protected using IPsec, the - entry consists of the values of the selectors that apply to the - traffic to be protected via AH or ESP, controls on how to - create SAs based on these selectors, and the parameters needed - to effect this protection (e.g., algorithms, modes, etc.). Note - that an SPD-S entry also contains information such as "populate - from packet" (PFP) flag (see paragraphs below on "How To Derive - the Values for an SAD entry") and bits indicating whether the - - - - - -Kent & Seo Standards Track [Page 21] - -RFC 4301 Security Architecture for IP December 2005 - - - SA lookup makes use of the local and remote IP addresses in - addition to the SPI (see AH [Ken05b] or ESP [Ken05a] - specifications). - - Representing Directionality in an SPD Entry - - For traffic protected by IPsec, the Local and Remote address and - ports in an SPD entry are swapped to represent directionality, - consistent with IKE conventions. In general, the protocols that - IPsec deals with have the property of requiring symmetric SAs with - flipped Local/Remote IP addresses. However, for ICMP, there is - often no such bi-directional authorization requirement. - Nonetheless, for the sake of uniformity and simplicity, SPD - entries for ICMP are specified in the same way as for other - protocols. Note also that for ICMP, Mobility Header, and - non-initial fragments, there are no port fields in these packets. - ICMP has message type and code and Mobility Header has mobility - header type. Thus, SPD entries have provisions for expressing - access controls appropriate for these protocols, in lieu of the - normal port field controls. For bypassed or discarded traffic, - separate inbound and outbound entries are supported, e.g., to - permit unidirectional flows if required. - - OPAQUE and ANY - - For each selector in an SPD entry, in addition to the literal - values that define a match, there are two special values: ANY and - OPAQUE. ANY is a wildcard that matches any value in the - corresponding field of the packet, or that matches packets where - that field is not present or is obscured. OPAQUE indicates that - the corresponding selector field is not available for examination - because it may not be present in a fragment, it does not exist for - the given Next Layer Protocol, or prior application of IPsec may - have encrypted the value. The ANY value encompasses the OPAQUE - value. Thus, OPAQUE need be used only when it is necessary to - distinguish between the case of any allowed value for a field, vs. - the absence or unavailability (e.g., due to encryption) of the - field. - - How to Derive the Values for an SAD Entry - - For each selector in an SPD entry, the entry specifies how to - derive the corresponding values for a new SA Database (SAD, see - Section 4.4.2) entry from those in the SPD and the packet. The - goal is to allow an SAD entry and an SPD cache entry to be created - based on specific selector values from the packet, or from the - matching SPD entry. For outbound traffic, there are SPD-S cache - entries and SPD-O cache entries. For inbound traffic not - - - -Kent & Seo Standards Track [Page 22] - -RFC 4301 Security Architecture for IP December 2005 - - - protected by IPsec, there are SPD-I cache entries and there is the - SAD, which represents the cache for inbound IPsec-protected - traffic (see Section 4.4.2). If IPsec processing is specified for - an entry, a "populate from packet" (PFP) flag may be asserted for - one or more of the selectors in the SPD entry (Local IP address; - Remote IP address; Next Layer Protocol; and, depending on Next - Layer Protocol, Local port and Remote port, or ICMP type/code, or - Mobility Header type). If asserted for a given selector X, the - flag indicates that the SA to be created should take its value for - X from the value in the packet. Otherwise, the SA should take its - value(s) for X from the value(s) in the SPD entry. Note: In the - non-PFP case, the selector values negotiated by the SA management - protocol (e.g., IKEv2) may be a subset of those in the SPD entry, - depending on the SPD policy of the peer. Also, whether a single - flag is used for, e.g., source port, ICMP type/code, and Mobility - Header (MH) type, or a separate flag is used for each, is a local - matter. - - The following example illustrates the use of the PFP flag in the - context of a security gateway or a BITS/BITW implementation. - Consider an SPD entry where the allowed value for Remote address - is a range of IPv4 addresses: 192.0.2.1 to 192.0.2.10. Suppose an - outbound packet arrives with a destination address of 192.0.2.3, - and there is no extant SA to carry this packet. The value used - for the SA created to transmit this packet could be either of the - two values shown below, depending on what the SPD entry for this - selector says is the source of the selector value: - - PFP flag value example of new - for the Remote SAD dest. address - addr. selector selector value - --------------- ------------ - a. PFP TRUE 192.0.2.3 (one host) - b. PFP FALSE 192.0.2.1 to 192.0.2.10 (range of hosts) - - Note that if the SPD entry above had a value of ANY for the Remote - address, then the SAD selector value would have to be ANY for case - (b), but would still be as illustrated for case (a). Thus, the - PFP flag can be used to prohibit sharing of an SA, even among - packets that match the same SPD entry. - - Management Interface - - For every IPsec implementation, there MUST be a management - interface that allows a user or system administrator to manage the - SPD. The interface must allow the user (or administrator) to - specify the security processing to be applied to every packet that - traverses the IPsec boundary. (In a native host IPsec - - - -Kent & Seo Standards Track [Page 23] - -RFC 4301 Security Architecture for IP December 2005 - - - implementation making use of a socket interface, the SPD may not - need to be consulted on a per-packet basis, as noted at the end of - Section 4.4.1.1 and in Section 5.) The management interface for - the SPD MUST allow creation of entries consistent with the - selectors defined in Section 4.4.1.1, and MUST support (total) - ordering of these entries, as seen via this interface. The SPD - entries' selectors are analogous to the ACL or packet filters - commonly found in a stateless firewall or packet filtering router - and which are currently managed this way. - - In host systems, applications MAY be allowed to create SPD - entries. (The means of signaling such requests to the IPsec - implementation are outside the scope of this standard.) However, - the system administrator MUST be able to specify whether or not a - user or application can override (default) system policies. The - form of the management interface is not specified by this document - and may differ for hosts vs. security gateways, and within hosts - the interface may differ for socket-based vs. BITS - implementations. However, this document does specify a standard - set of SPD elements that all IPsec implementations MUST support. - - Decorrelation - - The processing model described in this document assumes the - ability to decorrelate overlapping SPD entries to permit caching, - which enables more efficient processing of outbound traffic in - security gateways and BITS/BITW implementations. Decorrelation - [CoSa04] is only a means of improving performance and simplifying - the processing description. This RFC does not require a compliant - implementation to make use of decorrelation. For example, native - host implementations typically make use of caching implicitly - because they bind SAs to socket interfaces, and thus there is no - requirement to be able to decorrelate SPD entries in these - implementations. - - Note: Unless otherwise qualified, the use of "SPD" refers to the - body of policy information in both ordered or decorrelated - (unordered) state. Appendix B provides an algorithm that can be - used to decorrelate SPD entries, but any algorithm that produces - equivalent output may be used. Note that when an SPD entry is - decorrelated all the resulting entries MUST be linked together, so - that all members of the group derived from an individual, SPD - entry (prior to decorrelation) can all be placed into caches and - into the SAD at the same time. For example, suppose one starts - with an entry A (from an ordered SPD) that when decorrelated, - yields entries A1, A2, and A3. When a packet comes along that - matches, say A2, and triggers the creation of an SA, the SA - management protocol (e.g., IKEv2) negotiates A. And all 3 - - - -Kent & Seo Standards Track [Page 24] - -RFC 4301 Security Architecture for IP December 2005 - - - decorrelated entries, A1, A2, and A3, are placed in the - appropriate SPD-S cache and linked to the SA. The intent is that - use of a decorrelated SPD ought not to create more SAs than would - have resulted from use of a not-decorrelated SPD. - - If a decorrelated SPD is employed, there are three options for - what an initiator sends to a peer via an SA management protocol - (e.g., IKE). By sending the complete set of linked, decorrelated - entries that were selected from the SPD, a peer is given the best - possible information to enable selection of the appropriate SPD - entry at its end, especially if the peer has also decorrelated its - SPD. However, if a large number of decorrelated entries are - linked, this may create large packets for SA negotiation, and - hence fragmentation problems for the SA management protocol. - - Alternatively, the original entry from the (correlated) SPD may be - retained and passed to the SA management protocol. Passing the - correlated SPD entry keeps the use of a decorrelated SPD a local - matter, not visible to peers, and avoids possible fragmentation - concerns, although it provides less precise information to a - responder for matching against the responder's SPD. - - An intermediate approach is to send a subset of the complete set - of linked, decorrelated SPD entries. This approach can avoid the - fragmentation problems cited above yet provide better information - than the original, correlated entry. The major shortcoming of - this approach is that it may cause additional SAs to be created - later, since only a subset of the linked, decorrelated entries are - sent to a peer. Implementers are free to employ any of the - approaches cited above. - - A responder uses the traffic selector proposals it receives via an - SA management protocol to select an appropriate entry in its SPD. - The intent of the matching is to select an SPD entry and create an - SA that most closely matches the intent of the initiator, so that - traffic traversing the resulting SA will be accepted at both ends. - If the responder employs a decorrelated SPD, it SHOULD use the - decorrelated SPD entries for matching, as this will generally - result in creation of SAs that are more likely to match the intent - of both peers. If the responder has a correlated SPD, then it - SHOULD match the proposals against the correlated entries. For - IKEv2, use of a decorrelated SPD offers the best opportunity for a - responder to generate a "narrowed" response. - - In all cases, when a decorrelated SPD is available, the - decorrelated entries are used to populate the SPD-S cache. If the - SPD is not decorrelated, caching is not allowed and an ordered - - - - -Kent & Seo Standards Track [Page 25] - -RFC 4301 Security Architecture for IP December 2005 - - - search of SPD MUST be performed to verify that inbound traffic - arriving on an SA is consistent with the access control policy - expressed in the SPD. - - Handling Changes to the SPD While the System Is Running - - If a change is made to the SPD while the system is running, a - check SHOULD be made of the effect of this change on extant SAs. - An implementation SHOULD check the impact of an SPD change on - extant SAs and SHOULD provide a user/administrator with a - mechanism for configuring what actions to take, e.g., delete an - affected SA, allow an affected SA to continue unchanged, etc. - -4.4.1.1. Selectors - - An SA may be fine-grained or coarse-grained, depending on the - selectors used to define the set of traffic for the SA. For example, - all traffic between two hosts may be carried via a single SA, and - afforded a uniform set of security services. Alternatively, traffic - between a pair of hosts might be spread over multiple SAs, depending - on the applications being used (as defined by the Next Layer Protocol - and related fields, e.g., ports), with different security services - offered by different SAs. Similarly, all traffic between a pair of - security gateways could be carried on a single SA, or one SA could be - assigned for each communicating host pair. The following selector - parameters MUST be supported by all IPsec implementations to - facilitate control of SA granularity. Note that both Local and - Remote addresses should either be IPv4 or IPv6, but not a mix of - address types. Also, note that the Local/Remote port selectors (and - ICMP message type and code, and Mobility Header type) may be labeled - as OPAQUE to accommodate situations where these fields are - inaccessible due to packet fragmentation. - - - Remote IP Address(es) (IPv4 or IPv6): This is a list of ranges - of IP addresses (unicast, broadcast (IPv4 only)). This - structure allows expression of a single IP address (via a - trivial range), or a list of addresses (each a trivial range), - or a range of addresses (low and high values, inclusive), as - well as the most generic form of a list of ranges. Address - ranges are used to support more than one remote system sharing - the same SA, e.g., behind a security gateway. - - - Local IP Address(es) (IPv4 or IPv6): This is a list of ranges of - IP addresses (unicast, broadcast (IPv4 only)). This structure - allows expression of a single IP address (via a trivial range), - or a list of addresses (each a trivial range), or a range of - addresses (low and high values, inclusive), as well as the most - generic form of a list of ranges. Address ranges are used to - - - -Kent & Seo Standards Track [Page 26] - -RFC 4301 Security Architecture for IP December 2005 - - - support more than one source system sharing the same SA, e.g., - behind a security gateway. Local refers to the address(es) - being protected by this implementation (or policy entry). - - Note: The SPD does not include support for multicast address - entries. To support multicast SAs, an implementation should - make use of a Group SPD (GSPD) as defined in [RFC3740]. GSPD - entries require a different structure, i.e., one cannot use the - symmetric relationship associated with local and remote address - values for unicast SAs in a multicast context. Specifically, - outbound traffic directed to a multicast address on an SA would - not be received on a companion, inbound SA with the multicast - address as the source. - - - Next Layer Protocol: Obtained from the IPv4 "Protocol" or the - IPv6 "Next Header" fields. This is an individual protocol - number, ANY, or for IPv6 only, OPAQUE. The Next Layer Protocol - is whatever comes after any IP extension headers that are - present. To simplify locating the Next Layer Protocol, there - SHOULD be a mechanism for configuring which IPv6 extension - headers to skip. The default configuration for which protocols - to skip SHOULD include the following protocols: 0 (Hop-by-hop - options), 43 (Routing Header), 44 (Fragmentation Header), and 60 - (Destination Options). Note: The default list does NOT include - 51 (AH) or 50 (ESP). From a selector lookup point of view, - IPsec treats AH and ESP as Next Layer Protocols. - - Several additional selectors depend on the Next Layer Protocol - value: - - * If the Next Layer Protocol uses two ports (as do TCP, UDP, - SCTP, and others), then there are selectors for Local and - Remote Ports. Each of these selectors has a list of ranges - of values. Note that the Local and Remote ports may not be - available in the case of receipt of a fragmented packet or if - the port fields have been protected by IPsec (encrypted); - thus, a value of OPAQUE also MUST be supported. Note: In a - non-initial fragment, port values will not be available. If - a port selector specifies a value other than ANY or OPAQUE, - it cannot match packets that are non-initial fragments. If - the SA requires a port value other than ANY or OPAQUE, an - arriving fragment without ports MUST be discarded. (See - Section 7, "Handling Fragments".) - - * If the Next Layer Protocol is a Mobility Header, then there - is a selector for IPv6 Mobility Header message type (MH type) - [Mobip]. This is an 8-bit value that identifies a particular - mobility message. Note that the MH type may not be available - - - -Kent & Seo Standards Track [Page 27] - -RFC 4301 Security Architecture for IP December 2005 - - - in the case of receipt of a fragmented packet. (See Section - 7, "Handling Fragments".) For IKE, the IPv6 Mobility Header - message type (MH type) is placed in the most significant - eight bits of the 16-bit local "port" selector. - - * If the Next Layer Protocol value is ICMP, then there is a - 16-bit selector for the ICMP message type and code. The - message type is a single 8-bit value, which defines the type - of an ICMP message, or ANY. The ICMP code is a single 8-bit - value that defines a specific subtype for an ICMP message. - For IKE, the message type is placed in the most significant 8 - bits of the 16-bit selector and the code is placed in the - least significant 8 bits. This 16-bit selector can contain a - single type and a range of codes, a single type and ANY code, - and ANY type and ANY code. Given a policy entry with a range - of Types (T-start to T-end) and a range of Codes (C-start to - C-end), and an ICMP packet with Type t and Code c, an - implementation MUST test for a match using - - (T-start*256) + C-start <= (t*256) + c <= (T-end*256) + - C-end - - Note that the ICMP message type and code may not be available - in the case of receipt of a fragmented packet. (See Section - 7, "Handling Fragments".) - - - Name: This is not a selector like the others above. It is not - acquired from a packet. A name may be used as a symbolic - identifier for an IPsec Local or Remote address. Named SPD - entries are used in two ways: - - 1. A named SPD entry is used by a responder (not an initiator) - in support of access control when an IP address would not be - appropriate for the Remote IP address selector, e.g., for - "road warriors". The name used to match this field is - communicated during the IKE negotiation in the ID payload. - In this context, the initiator's Source IP address (inner IP - header in tunnel mode) is bound to the Remote IP address in - the SAD entry created by the IKE negotiation. This address - overrides the Remote IP address value in the SPD, when the - SPD entry is selected in this fashion. All IPsec - implementations MUST support this use of names. - - 2. A named SPD entry may be used by an initiator to identify a - user for whom an IPsec SA will be created (or for whom - traffic may be bypassed). The initiator's IP source address - (from inner IP header in tunnel mode) is used to replace the - following if and when they are created: - - - -Kent & Seo Standards Track [Page 28] - -RFC 4301 Security Architecture for IP December 2005 - - - - local address in the SPD cache entry - - local address in the outbound SAD entry - - remote address in the inbound SAD entry - - Support for this use is optional for multi-user, native host - implementations and not applicable to other implementations. - Note that this name is used only locally; it is not - communicated by the key management protocol. Also, name - forms other than those used for case 1 above (responder) are - applicable in the initiator context (see below). - - An SPD entry can contain both a name (or a list of names) and - also values for the Local or Remote IP address. - - For case 1, responder, the identifiers employed in named SPD - entries are one of the following four types: - - a. a fully qualified user name string (email), e.g., - mozart@foo.example.com - (this corresponds to ID_RFC822_ADDR in IKEv2) - - b. a fully qualified DNS name, e.g., - foo.example.com - (this corresponds to ID_FQDN in IKEv2) - - c. X.500 distinguished name, e.g., [WaKiHo97], - CN = Stephen T. Kent, O = BBN Technologies, - SP = MA, C = US - (this corresponds to ID_DER_ASN1_DN in IKEv2, after - decoding) - - d. a byte string - (this corresponds to Key_ID in IKEv2) - - For case 2, initiator, the identifiers employed in named SPD - entries are of type byte string. They are likely to be Unix - UIDs, Windows security IDs, or something similar, but could - also be a user name or account name. In all cases, this - identifier is only of local concern and is not transmitted. - - The IPsec implementation context determines how selectors are used. - For example, a native host implementation typically makes use of a - socket interface. When a new connection is established, the SPD can - be consulted and an SA bound to the socket. Thus, traffic sent via - that socket need not result in additional lookups to the SPD (SPD-O - and SPD-S) cache. In contrast, a BITS, BITW, or security gateway - implementation needs to look at each packet and perform an - SPD-O/SPD-S cache lookup based on the selectors. - - - -Kent & Seo Standards Track [Page 29] - -RFC 4301 Security Architecture for IP December 2005 - - -4.4.1.2. Structure of an SPD Entry - - This section contains a prose description of an SPD entry. Also, - Appendix C provides an example of an ASN.1 definition of an SPD - entry. - - This text describes the SPD in a fashion that is intended to map - directly into IKE payloads to ensure that the policy required by SPD - entries can be negotiated through IKE. Unfortunately, the semantics - of the version of IKEv2 published concurrently with this document - [Kau05] do not align precisely with those defined for the SPD. - Specifically, IKEv2 does not enable negotiation of a single SA that - binds multiple pairs of local and remote addresses and ports to a - single SA. Instead, when multiple local and remote addresses and - ports are negotiated for an SA, IKEv2 treats these not as pairs, but - as (unordered) sets of local and remote values that can be - arbitrarily paired. Until IKE provides a facility that conveys the - semantics that are expressed in the SPD via selector sets (as - described below), users MUST NOT include multiple selector sets in a - single SPD entry unless the access control intent aligns with the IKE - "mix and match" semantics. An implementation MAY warn users, to - alert them to this problem if users create SPD entries with multiple - selector sets, the syntax of which indicates possible conflicts with - current IKE semantics. - - The management GUI can offer the user other forms of data entry and - display, e.g., the option of using address prefixes as well as - ranges, and symbolic names for protocols, ports, etc. (Do not confuse - the use of symbolic names in a management interface with the SPD - selector "Name".) Note that Remote/Local apply only to IP addresses - and ports, not to ICMP message type/code or Mobility Header type. - Also, if the reserved, symbolic selector value OPAQUE or ANY is - employed for a given selector type, only that value may appear in the - list for that selector, and it must appear only once in the list for - that selector. Note that ANY and OPAQUE are local syntax conventions - -- IKEv2 negotiates these values via the ranges indicated below: - - ANY: start = 0 end = <max> - OPAQUE: start = <max> end = 0 - - An SPD is an ordered list of entries each of which contains the - following fields. - - o Name -- a list of IDs. This quasi-selector is optional. - The forms that MUST be supported are described above in - Section 4.4.1.1 under "Name". - - - - - -Kent & Seo Standards Track [Page 30] - -RFC 4301 Security Architecture for IP December 2005 - - - o PFP flags -- one per traffic selector. A given flag, e.g., - for Next Layer Protocol, applies to the relevant selector - across all "selector sets" (see below) contained in an SPD - entry. When creating an SA, each flag specifies for the - corresponding traffic selector whether to instantiate the - selector from the corresponding field in the packet that - triggered the creation of the SA or from the value(s) in - the corresponding SPD entry (see Section 4.4.1, "How to - Derive the Values for an SAD Entry"). Whether a single - flag is used for, e.g., source port, ICMP type/code, and - MH type, or a separate flag is used for each, is a local - matter. There are PFP flags for: - - Local Address - - Remote Address - - Next Layer Protocol - - Local Port, or ICMP message type/code or Mobility - Header type (depending on the next layer protocol) - - Remote Port, or ICMP message type/code or Mobility - Header type (depending on the next layer protocol) - - o One to N selector sets that correspond to the "condition" - for applying a particular IPsec action. Each selector set - contains: - - Local Address - - Remote Address - - Next Layer Protocol - - Local Port, or ICMP message type/code or Mobility - Header type (depending on the next layer protocol) - - Remote Port, or ICMP message type/code or Mobility - Header type (depending on the next layer protocol) - - Note: The "next protocol" selector is an individual value - (unlike the local and remote IP addresses) in a selector - set entry. This is consistent with how IKEv2 negotiates - the Traffic Selector (TS) values for an SA. It also makes - sense because one may need to associate different port - fields with different protocols. It is possible to - associate multiple protocols (and ports) with a single SA - by specifying multiple selector sets for that SA. - - o Processing info -- which action is required -- PROTECT, - BYPASS, or DISCARD. There is just one action that goes - with all the selector sets, not a separate action for each - set. If the required processing is PROTECT, the entry - contains the following information. - - IPsec mode -- tunnel or transport - - - - - -Kent & Seo Standards Track [Page 31] - -RFC 4301 Security Architecture for IP December 2005 - - - - (if tunnel mode) local tunnel address -- For a - non-mobile host, if there is just one interface, this - is straightforward; if there are multiple - interfaces, this must be statically configured. For a - mobile host, the specification of the local address - is handled externally to IPsec. - - (if tunnel mode) remote tunnel address -- There is no - standard way to determine this. See 4.5.3, "Locating - a Security Gateway". - - Extended Sequence Number -- Is this SA using extended - sequence numbers? - - stateful fragment checking -- Is this SA using - stateful fragment checking? (See Section 7 for more - details.) - - Bypass DF bit (T/F) -- applicable to tunnel mode SAs - - Bypass DSCP (T/F) or map to unprotected DSCP values - (array) if needed to restrict bypass of DSCP values -- - applicable to tunnel mode SAs - - IPsec protocol -- AH or ESP - - algorithms -- which ones to use for AH, which ones to - use for ESP, which ones to use for combined mode, - ordered by decreasing priority - - It is a local matter as to what information is kept with regard to - handling extant SAs when the SPD is changed. - -4.4.1.3. More Regarding Fields Associated with Next Layer Protocols - - Additional selectors are often associated with fields in the Next - Layer Protocol header. A particular Next Layer Protocol can have - zero, one, or two selectors. There may be situations where there - aren't both local and remote selectors for the fields that are - dependent on the Next Layer Protocol. The IPv6 Mobility Header has - only a Mobility Header message type. AH and ESP have no further - selector fields. A system may be willing to send an ICMP message - type and code that it does not want to receive. In the descriptions - below, "port" is used to mean a field that is dependent on the Next - Layer Protocol. - - A. If a Next Layer Protocol has no "port" selectors, then - the Local and Remote "port" selectors are set to OPAQUE in - the relevant SPD entry, e.g., - - Local's - next layer protocol = AH - "port" selector = OPAQUE - - - - - -Kent & Seo Standards Track [Page 32] - -RFC 4301 Security Architecture for IP December 2005 - - - Remote's - next layer protocol = AH - "port" selector = OPAQUE - - B. Even if a Next Layer Protocol has only one selector, e.g., - Mobility Header type, then the Local and Remote "port" - selectors are used to indicate whether a system is - willing to send and/or receive traffic with the specified - "port" values. For example, if Mobility Headers of a - specified type are allowed to be sent and received via an - SA, then the relevant SPD entry would be set as follows: - - Local's - next layer protocol = Mobility Header - "port" selector = Mobility Header message type - - Remote's - next layer protocol = Mobility Header - "port" selector = Mobility Header message type - - If Mobility Headers of a specified type are allowed to be - sent but NOT received via an SA, then the relevant SPD - entry would be set as follows: - - Local's - next layer protocol = Mobility Header - "port" selector = Mobility Header message type - - Remote's - next layer protocol = Mobility Header - "port" selector = OPAQUE - - If Mobility Headers of a specified type are allowed to be - received but NOT sent via an SA, then the relevant SPD - entry would be set as follows: - - Local's - next layer protocol = Mobility Header - "port" selector = OPAQUE - - Remote's - next layer protocol = Mobility Header - "port" selector = Mobility Header message type - - C. If a system is willing to send traffic with a particular - "port" value but NOT receive traffic with that kind of - port value, the system's traffic selectors are set as - follows in the relevant SPD entry: - - - -Kent & Seo Standards Track [Page 33] - -RFC 4301 Security Architecture for IP December 2005 - - - Local's - next layer protocol = ICMP - "port" selector = <specific ICMP type & code> - - Remote's - next layer protocol = ICMP - "port" selector = OPAQUE - - D. To indicate that a system is willing to receive traffic - with a particular "port" value but NOT send that kind of - traffic, the system's traffic selectors are set as follows - in the relevant SPD entry: - - Local's - next layer protocol = ICMP - "port" selector = OPAQUE - - Remote's - next layer protocol = ICMP - "port" selector = <specific ICMP type & code> - - For example, if a security gateway is willing to allow - systems behind it to send ICMP traceroutes, but is not - willing to let outside systems run ICMP traceroutes to - systems behind it, then the security gateway's traffic - selectors are set as follows in the relevant SPD entry: - - Local's - next layer protocol = 1 (ICMPv4) - "port" selector = 30 (traceroute) - - Remote's - next layer protocol = 1 (ICMPv4) - "port" selector = OPAQUE - -4.4.2. Security Association Database (SAD) - - In each IPsec implementation, there is a nominal Security Association - Database (SAD), in which each entry defines the parameters associated - with one SA. Each SA has an entry in the SAD. For outbound - processing, each SAD entry is pointed to by entries in the SPD-S part - of the SPD cache. For inbound processing, for unicast SAs, the SPI - is used either alone to look up an SA or in conjunction with the - IPsec protocol type. If an IPsec implementation supports multicast, - the SPI plus destination address, or SPI plus destination and source - addresses are used to look up the SA. (See Section 4.1 for details on - the algorithm that MUST be used for mapping inbound IPsec datagrams - to SAs.) The following parameters are associated with each entry in - - - -Kent & Seo Standards Track [Page 34] - -RFC 4301 Security Architecture for IP December 2005 - - - the SAD. They should all be present except where otherwise noted, - e.g., AH Authentication algorithm. This description does not purport - to be a MIB, only a specification of the minimal data items required - to support an SA in an IPsec implementation. - - For each of the selectors defined in Section 4.4.1.1, the entry for - an inbound SA in the SAD MUST be initially populated with the value - or values negotiated at the time the SA was created. (See the - paragraph in Section 4.4.1 under "Handling Changes to the SPD while - the System is Running" for guidance on the effect of SPD changes on - extant SAs.) For a receiver, these values are used to check that the - header fields of an inbound packet (after IPsec processing) match the - selector values negotiated for the SA. Thus, the SAD acts as a cache - for checking the selectors of inbound traffic arriving on SAs. For - the receiver, this is part of verifying that a packet arriving on an - SA is consistent with the policy for the SA. (See Section 6 for rules - for ICMP messages.) These fields can have the form of specific - values, ranges, ANY, or OPAQUE, as described in Section 4.4.1.1, - "Selectors". Note also that there are a couple of situations in - which the SAD can have entries for SAs that do not have corresponding - entries in the SPD. Since this document does not mandate that the - SAD be selectively cleared when the SPD is changed, SAD entries can - remain when the SPD entries that created them are changed or deleted. - Also, if a manually keyed SA is created, there could be an SAD entry - for this SA that does not correspond to any SPD entry. - - Note: The SAD can support multicast SAs, if manually configured. An - outbound multicast SA has the same structure as a unicast SA. The - source address is that of the sender, and the destination address is - the multicast group address. An inbound, multicast SA must be - configured with the source addresses of each peer authorized to - transmit to the multicast SA in question. The SPI value for a - multicast SA is provided by a multicast group controller, not by the - receiver, as for a unicast SA. Because an SAD entry may be required - to accommodate multiple, individual IP source addresses that were - part of an SPD entry (for unicast SAs), the required facility for - inbound, multicast SAs is a feature already present in an IPsec - implementation. However, because the SPD has no provisions for - accommodating multicast entries, this document does not specify an - automated way to create an SAD entry for a multicast, inbound SA. - Only manually configured SAD entries can be created to accommodate - inbound, multicast traffic. - - Implementation Guidance: This document does not specify how an SPD-S - entry refers to the corresponding SAD entry, as this is an - implementation-specific detail. However, some implementations (based - on experience from RFC 2401) are known to have problems in this - regard. In particular, simply storing the (remote tunnel header IP - - - -Kent & Seo Standards Track [Page 35] - -RFC 4301 Security Architecture for IP December 2005 - - - address, remote SPI) pair in the SPD cache is not sufficient, since - the pair does not always uniquely identify a single SAD entry. For - instance, two hosts behind the same NAT could choose the same SPI - value. The situation also may arise if a host is assigned an IP - address (e.g., via DHCP) previously used by some other host, and the - SAs associated with the old host have not yet been deleted via dead - peer detection mechanisms. This may lead to packets being sent over - the wrong SA or, if key management ensures the pair is unique, - denying the creation of otherwise valid SAs. Thus, implementors - should implement links between the SPD cache and the SAD in a way - that does not engender such problems. - -4.4.2.1. Data Items in the SAD - - The following data items MUST be in the SAD: - - o Security Parameter Index (SPI): a 32-bit value selected by the - receiving end of an SA to uniquely identify the SA. In an SAD - entry for an outbound SA, the SPI is used to construct the - packet's AH or ESP header. In an SAD entry for an inbound SA, the - SPI is used to map traffic to the appropriate SA (see text on - unicast/multicast in Section 4.1). - - o Sequence Number Counter: a 64-bit counter used to generate the - Sequence Number field in AH or ESP headers. 64-bit sequence - numbers are the default, but 32-bit sequence numbers are also - supported if negotiated. - - o Sequence Counter Overflow: a flag indicating whether overflow of - the sequence number counter should generate an auditable event and - prevent transmission of additional packets on the SA, or whether - rollover is permitted. The audit log entry for this event SHOULD - include the SPI value, current date/time, Local Address, Remote - Address, and the selectors from the relevant SAD entry. - - o Anti-Replay Window: a 64-bit counter and a bit-map (or equivalent) - used to determine whether an inbound AH or ESP packet is a replay. - - Note: If anti-replay has been disabled by the receiver for an SA, - e.g., in the case of a manually keyed SA, then the Anti-Replay - Window is ignored for the SA in question. 64-bit sequence numbers - are the default, but this counter size accommodates 32-bit - sequence numbers as well. - - o AH Authentication algorithm, key, etc. This is required only if - AH is supported. - - - - - -Kent & Seo Standards Track [Page 36] - -RFC 4301 Security Architecture for IP December 2005 - - - o ESP Encryption algorithm, key, mode, IV, etc. If a combined mode - algorithm is used, these fields will not be applicable. - - o ESP integrity algorithm, keys, etc. If the integrity service is - not selected, these fields will not be applicable. If a combined - mode algorithm is used, these fields will not be applicable. - - o ESP combined mode algorithms, key(s), etc. This data is used when - a combined mode (encryption and integrity) algorithm is used with - ESP. If a combined mode algorithm is not used, these fields are - not applicable. - - o Lifetime of this SA: a time interval after which an SA must be - replaced with a new SA (and new SPI) or terminated, plus an - indication of which of these actions should occur. This may be - expressed as a time or byte count, or a simultaneous use of both - with the first lifetime to expire taking precedence. A compliant - implementation MUST support both types of lifetimes, and MUST - support a simultaneous use of both. If time is employed, and if - IKE employs X.509 certificates for SA establishment, the SA - lifetime must be constrained by the validity intervals of the - certificates, and the NextIssueDate of the Certificate Revocation - Lists (CRLs) used in the IKE exchange for the SA. Both initiator - and responder are responsible for constraining the SA lifetime in - this fashion. Note: The details of how to handle the refreshing - of keys when SAs expire is a local matter. However, one - reasonable approach is: - - (a) If byte count is used, then the implementation SHOULD count the - number of bytes to which the IPsec cryptographic algorithm is - applied. For ESP, this is the encryption algorithm (including - Null encryption) and for AH, this is the authentication - algorithm. This includes pad bytes, etc. Note that - implementations MUST be able to handle having the counters at - the ends of an SA get out of synch, e.g., because of packet - loss or because the implementations at each end of the SA - aren't doing things the same way. - - (b) There SHOULD be two kinds of lifetime -- a soft lifetime that - warns the implementation to initiate action such as setting up - a replacement SA, and a hard lifetime when the current SA ends - and is destroyed. - - (c) If the entire packet does not get delivered during the SA's - lifetime, the packet SHOULD be discarded. - - o IPsec protocol mode: tunnel or transport. Indicates which mode of - AH or ESP is applied to traffic on this SA. - - - -Kent & Seo Standards Track [Page 37] - -RFC 4301 Security Architecture for IP December 2005 - - - o Stateful fragment checking flag. Indicates whether or not - stateful fragment checking applies to this SA. - - o Bypass DF bit (T/F) -- applicable to tunnel mode SAs where both - inner and outer headers are IPv4. - - o DSCP values -- the set of DSCP values allowed for packets carried - over this SA. If no values are specified, no DSCP-specific - filtering is applied. If one or more values are specified, these - are used to select one SA among several that match the traffic - selectors for an outbound packet. Note that these values are NOT - checked against inbound traffic arriving on the SA. - - o Bypass DSCP (T/F) or map to unprotected DSCP values (array) if - needed to restrict bypass of DSCP values -- applicable to tunnel - mode SAs. This feature maps DSCP values from an inner header to - values in an outer header, e.g., to address covert channel - signaling concerns. - - o Path MTU: any observed path MTU and aging variables. - - o Tunnel header IP source and destination address -- both addresses - must be either IPv4 or IPv6 addresses. The version implies the - type of IP header to be used. Only used when the IPsec protocol - mode is tunnel. - -4.4.2.2. Relationship between SPD, PFP flag, packet, and SAD - - For each selector, the following tables show the relationship - between the value in the SPD, the PFP flag, the value in the - triggering packet, and the resulting value in the SAD. Note that - the administrative interface for IPsec can use various syntactic - options to make it easier for the administrator to enter rules. - For example, although a list of ranges is what IKEv2 sends, it - might be clearer and less error prone for the user to enter a - single IP address or IP address prefix. - - - - - - - - - - - - - - - -Kent & Seo Standards Track [Page 38] - -RFC 4301 Security Architecture for IP December 2005 - - - Value in - Triggering Resulting SAD - Selector SPD Entry PFP Packet Entry - -------- ---------------- --- ------------ -------------- - loc addr list of ranges 0 IP addr "S" list of ranges - ANY 0 IP addr "S" ANY - list of ranges 1 IP addr "S" "S" - ANY 1 IP addr "S" "S" - - rem addr list of ranges 0 IP addr "D" list of ranges - ANY 0 IP addr "D" ANY - list of ranges 1 IP addr "D" "D" - ANY 1 IP addr "D" "D" - - protocol list of prot's* 0 prot. "P" list of prot's* - ANY** 0 prot. "P" ANY - OPAQUE**** 0 prot. "P" OPAQUE - - list of prot's* 0 not avail. discard packet - ANY** 0 not avail. ANY - OPAQUE**** 0 not avail. OPAQUE - - list of prot's* 1 prot. "P" "P" - ANY** 1 prot. "P" "P" - OPAQUE**** 1 prot. "P" *** - - list of prot's* 1 not avail. discard packet - ANY** 1 not avail. discard packet - OPAQUE**** 1 not avail. *** - - - - - - - - - - - - - - - - - - - - - - -Kent & Seo Standards Track [Page 39] - -RFC 4301 Security Architecture for IP December 2005 - - - If the protocol is one that has two ports, then there will be - selectors for both Local and Remote ports. - - Value in - Triggering Resulting SAD - Selector SPD Entry PFP Packet Entry - -------- ---------------- --- ------------ -------------- - loc port list of ranges 0 src port "s" list of ranges - ANY 0 src port "s" ANY - OPAQUE 0 src port "s" OPAQUE - - list of ranges 0 not avail. discard packet - ANY 0 not avail. ANY - OPAQUE 0 not avail. OPAQUE - - list of ranges 1 src port "s" "s" - ANY 1 src port "s" "s" - OPAQUE 1 src port "s" *** - - list of ranges 1 not avail. discard packet - ANY 1 not avail. discard packet - OPAQUE 1 not avail. *** - - - rem port list of ranges 0 dst port "d" list of ranges - ANY 0 dst port "d" ANY - OPAQUE 0 dst port "d" OPAQUE - - list of ranges 0 not avail. discard packet - ANY 0 not avail. ANY - OPAQUE 0 not avail. OPAQUE - - list of ranges 1 dst port "d" "d" - ANY 1 dst port "d" "d" - OPAQUE 1 dst port "d" *** - - list of ranges 1 not avail. discard packet - ANY 1 not avail. discard packet - OPAQUE 1 not avail. *** - - - - - - - - - - - - -Kent & Seo Standards Track [Page 40] - -RFC 4301 Security Architecture for IP December 2005 - - - If the protocol is mobility header, then there will be a selector - for mh type. - - Value in - Triggering Resulting SAD - Selector SPD Entry PFP Packet Entry - -------- ---------------- --- ------------ -------------- - mh type list of ranges 0 mh type "T" list of ranges - ANY 0 mh type "T" ANY - OPAQUE 0 mh type "T" OPAQUE - - list of ranges 0 not avail. discard packet - ANY 0 not avail. ANY - OPAQUE 0 not avail. OPAQUE - - list of ranges 1 mh type "T" "T" - ANY 1 mh type "T" "T" - OPAQUE 1 mh type "T" *** - - list of ranges 1 not avail. discard packet - ANY 1 not avail. discard packet - OPAQUE 1 not avail. *** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Kent & Seo Standards Track [Page 41] - -RFC 4301 Security Architecture for IP December 2005 - - - If the protocol is ICMP, then there will be a 16-bit selector for - ICMP type and ICMP code. Note that the type and code are bound to - each other, i.e., the codes apply to the particular type. This - 16-bit selector can contain a single type and a range of codes, a - single type and ANY code, and ANY type and ANY code. - - Value in - Triggering Resulting SAD - Selector SPD Entry PFP Packet Entry - --------- ---------------- --- ------------ -------------- - ICMP type a single type & 0 type "t" & single type & - and code range of codes code "c" range of codes - a single type & 0 type "t" & single type & - ANY code code "c" ANY code - ANY type & ANY 0 type "t" & ANY type & - code code "c" ANY code - OPAQUE 0 type "t" & OPAQUE - code "c" - - a single type & 0 not avail. discard packet - range of codes - a single type & 0 not avail. discard packet - ANY code - ANY type & 0 not avail. ANY type & - ANY code ANY code - OPAQUE 0 not avail. OPAQUE - - a single type & 1 type "t" & "t" and "c" - range of codes code "c" - a single type & 1 type "t" & "t" and "c" - ANY code code "c" - ANY type & 1 type "t" & "t" and "c" - ANY code code "c" - OPAQUE 1 type "t" & *** - code "c" - - a single type & 1 not avail. discard packet - range of codes - a single type & 1 not avail. discard packet - ANY code - ANY type & 1 not avail. discard packet - ANY code - OPAQUE 1 not avail. *** - - - - - - - - -Kent & Seo Standards Track [Page 42] - -RFC 4301 Security Architecture for IP December 2005 - - - If the name selector is used: - - Value in - Triggering Resulting SAD - Selector SPD Entry PFP Packet Entry - --------- ---------------- --- ------------ -------------- - name list of user or N/A N/A N/A - system names - - * "List of protocols" is the information, not the way - that the SPD or SAD or IKEv2 have to represent this - information. - ** 0 (zero) is used by IKE to indicate ANY for - protocol. - *** Use of PFP=1 with an OPAQUE value is an error and - SHOULD be prohibited by an IPsec implementation. - **** The protocol field cannot be OPAQUE in IPv4. This - table entry applies only to IPv6. - -4.4.3. Peer Authorization Database (PAD) - - The Peer Authorization Database (PAD) provides the link between the - SPD and a security association management protocol such as IKE. It - embodies several critical functions: - - o identifies the peers or groups of peers that are authorized - to communicate with this IPsec entity - o specifies the protocol and method used to authenticate each - peer - o provides the authentication data for each peer - o constrains the types and values of IDs that can be asserted - by a peer with regard to child SA creation, to ensure that the - peer does not assert identities for lookup in the SPD that it - is not authorized to represent, when child SAs are created - o peer gateway location info, e.g., IP address(es) or DNS names, - MAY be included for peers that are known to be "behind" a - security gateway - - The PAD provides these functions for an IKE peer when the peer acts - as either the initiator or the responder. - - To perform these functions, the PAD contains an entry for each peer - or group of peers with which the IPsec entity will communicate. An - entry names an individual peer (a user, end system or security - gateway) or specifies a group of peers (using ID matching rules - defined below). The entry specifies the authentication protocol - (e.g., IKEv1, IKEv2, KINK) method used (e.g., certificates or pre- - shared secrets) and the authentication data (e.g., the pre-shared - - - -Kent & Seo Standards Track [Page 43] - -RFC 4301 Security Architecture for IP December 2005 - - - secret or the trust anchor relative to which the peer's certificate - will be validated). For certificate-based authentication, the entry - also may provide information to assist in verifying the revocation - status of the peer, e.g., a pointer to a CRL repository or the name - of an Online Certificate Status Protocol (OCSP) server associated - with the peer or with the trust anchor associated with the peer. - - Each entry also specifies whether the IKE ID payload will be used as - a symbolic name for SPD lookup, or whether the remote IP address - provided in traffic selector payloads will be used for SPD lookups - when child SAs are created. - - Note that the PAD information MAY be used to support creation of more - than one tunnel mode SA at a time between two peers, e.g., two - tunnels to protect the same addresses/hosts, but with different - tunnel endpoints. - -4.4.3.1. PAD Entry IDs and Matching Rules - - The PAD is an ordered database, where the order is defined by an - administrator (or a user in the case of a single-user end system). - Usually, the same administrator will be responsible for both the PAD - and SPD, since the two databases must be coordinated. The ordering - requirement for the PAD arises for the same reason as for the SPD, - i.e., because use of "star name" entries allows for overlaps in the - set of IKE IDs that could match a specific entry. - - Six types of IDs are supported for entries in the PAD, consistent - with the symbolic name types and IP addresses used to identify SPD - entries. The ID for each entry acts as the index for the PAD, i.e., - it is the value used to select an entry. All of these ID types can - be used to match IKE ID payload types. The six types are: - - o DNS name (specific or partial) - o Distinguished Name (complete or sub-tree constrained) - o RFC 822 email address (complete or partially qualified) - o IPv4 address (range) - o IPv6 address (range) - o Key ID (exact match only) - - The first three name types can accommodate sub-tree matching as well - as exact matches. A DNS name may be fully qualified and thus match - exactly one name, e.g., foo.example.com. Alternatively, the name may - encompass a group of peers by being partially specified, e.g., the - string ".example.com" could be used to match any DNS name ending in - these two domain name components. - - - - - -Kent & Seo Standards Track [Page 44] - -RFC 4301 Security Architecture for IP December 2005 - - - Similarly, a Distinguished Name may specify a complete Distinguished - Name to match exactly one entry, e.g., CN = Stephen, O = BBN - Technologies, SP = MA, C = US. Alternatively, an entry may encompass - a group of peers by specifying a sub-tree, e.g., an entry of the form - "C = US, SP = MA" might be used to match all DNs that contain these - two attributes as the top two Relative Distinguished Names (RDNs). - - For an RFC 822 e-mail addresses, the same options exist. A complete - address such as foo@example.com matches one entity, but a sub-tree - name such as "@example.com" could be used to match all the entities - with names ending in those two domain names to the right of the @. - - The specific syntax used by an implementation to accommodate sub-tree - matching for distinguished names, domain names or RFC 822 e-mail - addresses is a local matter. But, at a minimum, sub-tree matching of - the sort described above MUST be supported. (Substring matching - within a DN, DNS name, or RFC 822 address MAY be supported, but is - not required.) - - For IPv4 and IPv6 addresses, the same address range syntax used for - SPD entries MUST be supported. This allows specification of an - individual address (via a trivial range), an address prefix (by - choosing a range that adheres to Classless Inter-Domain Routing - (CIDR)-style prefixes), or an arbitrary address range. - - The Key ID field is defined as an OCTET string in IKE. For this name - type, only exact-match syntax MUST be supported (since there is no - explicit structure for this ID type). Additional matching functions - MAY be supported for this ID type. - -4.4.3.2. IKE Peer Authentication Data - - Once an entry is located based on an ordered search of the PAD based - on ID field matching, it is necessary to verify the asserted - identity, i.e., to authenticate the asserted ID. For each PAD entry, - there is an indication of the type of authentication to be performed. - This document requires support for two required authentication data - types: - - - X.509 certificate - - pre-shared secret - - For authentication based on an X.509 certificate, the PAD entry - contains a trust anchor via which the end entity (EE) certificate for - the peer must be verifiable, either directly or via a certificate - path. See RFC 3280 for the definition of a trust anchor. An entry - used with certificate-based authentication MAY include additional - data to facilitate certificate revocation status, e.g., a list of - - - -Kent & Seo Standards Track [Page 45] - -RFC 4301 Security Architecture for IP December 2005 - - - appropriate OCSP responders or CRL repositories, and associated - authentication data. For authentication based on a pre-shared - secret, the PAD contains the pre-shared secret to be used by IKE. - - This document does not require that the IKE ID asserted by a peer be - syntactically related to a specific field in an end entity - certificate that is employed to authenticate the identity of that - peer. However, it often will be appropriate to impose such a - requirement, e.g., when a single entry represents a set of peers each - of whom may have a distinct SPD entry. Thus, implementations MUST - provide a means for an administrator to require a match between an - asserted IKE ID and the subject name or subject alt name in a - certificate. The former is applicable to IKE IDs expressed as - distinguished names; the latter is appropriate for DNS names, RFC 822 - e-mail addresses, and IP addresses. Since KEY ID is intended for - identifying a peer authenticated via a pre-shared secret, there is no - requirement to match this ID type to a certificate field. - - See IKEv1 [HarCar98] and IKEv2 [Kau05] for details of how IKE - performs peer authentication using certificates or pre-shared - secrets. - - This document does not mandate support for any other authentication - methods, although such methods MAY be employed. - -4.4.3.3. Child SA Authorization Data - - Once an IKE peer is authenticated, child SAs may be created. Each - PAD entry contains data to constrain the set of IDs that can be - asserted by an IKE peer, for matching against the SPD. Each PAD - entry indicates whether the IKE ID is to be used as a symbolic name - for SPD matching, or whether an IP address asserted in a traffic - selector payload is to be used. - - If the entry indicates that the IKE ID is to be used, then the PAD - entry ID field defines the authorized set of IDs. If the entry - indicates that child SAs traffic selectors are to be used, then an - additional data element is required, in the form of IPv4 and/or IPv6 - address ranges. (A peer may be authorized for both address types, so - there MUST be provision for both a v4 and a v6 address range.) - -4.4.3.4. How the PAD Is Used - - During the initial IKE exchange, the initiator and responder each - assert their identity via the IKE ID payload and send an AUTH payload - to verify the asserted identity. One or more CERT payloads may be - transmitted to facilitate the verification of each asserted identity. - - - - -Kent & Seo Standards Track [Page 46] - -RFC 4301 Security Architecture for IP December 2005 - - - When an IKE entity receives an IKE ID payload, it uses the asserted - ID to locate an entry in the PAD, using the matching rules described - above. The PAD entry specifies the authentication method to be - employed for the identified peer. This ensures that the right method - is used for each peer and that different methods can be used for - different peers. The entry also specifies the authentication data - that will be used to verify the asserted identity. This data is - employed in conjunction with the specified method to authenticate the - peer, before any CHILD SAs are created. - - Child SAs are created based on the exchange of traffic selector - payloads, either at the end of the initial IKE exchange or in - subsequent CREATE_CHILD_SA exchanges. The PAD entry for the (now - authenticated) IKE peer is used to constrain creation of child SAs; - specifically, the PAD entry specifies how the SPD is searched using a - traffic selector proposal from a peer. There are two choices: either - the IKE ID asserted by the peer is used to find an SPD entry via its - symbolic name, or peer IP addresses asserted in traffic selector - payloads are used for SPD lookups based on the remote IP address - field portion of an SPD entry. It is necessary to impose these - constraints on creation of child SAs to prevent an authenticated peer - from spoofing IDs associated with other, legitimate peers. - - Note that because the PAD is checked before searching for an SPD - entry, this safeguard protects an initiator against spoofing attacks. - For example, assume that IKE A receives an outbound packet destined - for IP address X, a host served by a security gateway. RFC 2401 - [RFC2401] and this document do not specify how A determines the - address of the IKE peer serving X. However, any peer contacted by A - as the presumed representative for X must be registered in the PAD in - order to allow the IKE exchange to be authenticated. Moreover, when - the authenticated peer asserts that it represents X in its traffic - selector exchange, the PAD will be consulted to determine if the peer - in question is authorized to represent X. Thus, the PAD provides a - binding of address ranges (or name sub-spaces) to peers, to counter - such attacks. - -4.5. SA and Key Management - - All IPsec implementations MUST support both manual and automated SA - and cryptographic key management. The IPsec protocols, AH and ESP, - are largely independent of the associated SA management techniques, - although the techniques involved do affect some of the security - services offered by the protocols. For example, the optional - anti-replay service available for AH and ESP requires automated SA - management. Moreover, the granularity of key distribution employed - with IPsec determines the granularity of authentication provided. In - general, data origin authentication in AH and ESP is limited by the - - - -Kent & Seo Standards Track [Page 47] - -RFC 4301 Security Architecture for IP December 2005 - - - extent to which secrets used with the integrity algorithm (or with a - key management protocol that creates such secrets) are shared among - multiple possible sources. - - The following text describes the minimum requirements for both types - of SA management. - -4.5.1. Manual Techniques - - The simplest form of management is manual management, in which a - person manually configures each system with keying material and SA - management data relevant to secure communication with other systems. - Manual techniques are practical in small, static environments but - they do not scale well. For example, a company could create a - virtual private network (VPN) using IPsec in security gateways at - several sites. If the number of sites is small, and since all the - sites come under the purview of a single administrative domain, this - might be a feasible context for manual management techniques. In - this case, the security gateway might selectively protect traffic to - and from other sites within the organization using a manually - configured key, while not protecting traffic for other destinations. - It also might be appropriate when only selected communications need - to be secured. A similar argument might apply to use of IPsec - entirely within an organization for a small number of hosts and/or - gateways. Manual management techniques often employ statically - configured, symmetric keys, though other options also exist. - -4.5.2. Automated SA and Key Management - - Widespread deployment and use of IPsec requires an Internet-standard, - scalable, automated, SA management protocol. Such support is - required to facilitate use of the anti-replay features of AH and ESP, - and to accommodate on-demand creation of SAs, e.g., for user- and - session-oriented keying. (Note that the notion of "rekeying" an SA - actually implies creation of a new SA with a new SPI, a process that - generally implies use of an automated SA/key management protocol.) - - The default automated key management protocol selected for use with - IPsec is IKEv2 [Kau05]. This document assumes the availability of - certain functions from the key management protocol that are not - supported by IKEv1. Other automated SA management protocols MAY be - employed. - - When an automated SA/key management protocol is employed, the output - from this protocol is used to generate multiple keys for a single SA. - This also occurs because distinct keys are used for each of the two - - - - - -Kent & Seo Standards Track [Page 48] - -RFC 4301 Security Architecture for IP December 2005 - - - SAs created by IKE. If both integrity and confidentiality are - employed, then a minimum of four keys are required. Additionally, - some cryptographic algorithms may require multiple keys, e.g., 3DES. - - The Key Management System may provide a separate string of bits for - each key or it may generate one string of bits from which all keys - are extracted. If a single string of bits is provided, care needs to - be taken to ensure that the parts of the system that map the string - of bits to the required keys do so in the same fashion at both ends - of the SA. To ensure that the IPsec implementations at each end of - the SA use the same bits for the same keys, and irrespective of which - part of the system divides the string of bits into individual keys, - the encryption keys MUST be taken from the first (left-most, - high-order) bits and the integrity keys MUST be taken from the - remaining bits. The number of bits for each key is defined in the - relevant cryptographic algorithm specification RFC. In the case of - multiple encryption keys or multiple integrity keys, the - specification for the cryptographic algorithm must specify the order - in which they are to be selected from a single string of bits - provided to the cryptographic algorithm. - -4.5.3. Locating a Security Gateway - - This section discusses issues relating to how a host learns about the - existence of relevant security gateways and, once a host has - contacted these security gateways, how it knows that these are the - correct security gateways. The details of where the required - information is stored is a local matter, but the Peer Authorization - Database (PAD) described in Section 4.4 is the most likely candidate. - (Note: S* indicates a system that is running IPsec, e.g., SH1 and SG2 - below.) - - Consider a situation in which a remote host (SH1) is using the - Internet to gain access to a server or other machine (H2) and there - is a security gateway (SG2), e.g., a firewall, through which H1's - traffic must pass. An example of this situation would be a mobile - host crossing the Internet to his home organization's firewall (SG2). - This situation raises several issues: - - 1. How does SH1 know/learn about the existence of the security - gateway SG2? - - 2. How does it authenticate SG2, and once it has authenticated SG2, - how does it confirm that SG2 has been authorized to represent H2? - - 3. How does SG2 authenticate SH1 and verify that SH1 is authorized to - contact H2? - - - - -Kent & Seo Standards Track [Page 49] - -RFC 4301 Security Architecture for IP December 2005 - - - 4. How does SH1 know/learn about any additional gateways that provide - alternate paths to H2? - - To address these problems, an IPsec-supporting host or security - gateway MUST have an administrative interface that allows the - user/administrator to configure the address of one or more security - gateways for ranges of destination addresses that require its use. - This includes the ability to configure information for locating and - authenticating one or more security gateways and verifying the - authorization of these gateways to represent the destination host. - (The authorization function is implied in the PAD.) This document - does not address the issue of how to automate the - discovery/verification of security gateways. - -4.6. SAs and Multicast - - The receiver-orientation of the SA implies that, in the case of - unicast traffic, the destination system will select the SPI value. - By having the destination select the SPI value, there is no potential - for manually configured SAs to conflict with automatically configured - (e.g., via a key management protocol) SAs or for SAs from multiple - sources to conflict with each other. For multicast traffic, there - are multiple destination systems associated with a single SA. So - some system or person will need to coordinate among all multicast - groups to select an SPI or SPIs on behalf of each multicast group and - then communicate the group's IPsec information to all of the - legitimate members of that multicast group via mechanisms not defined - here. - - Multiple senders to a multicast group SHOULD use a single Security - Association (and hence SPI) for all traffic to that group when a - symmetric key encryption or integrity algorithm is employed. In such - circumstances, the receiver knows only that the message came from a - system possessing the key for that multicast group. In such - circumstances, a receiver generally will not be able to authenticate - which system sent the multicast traffic. Specifications for other, - more general multicast approaches are deferred to the IETF Multicast - Security Working Group. - -5. IP Traffic Processing - - As mentioned in Section 4.4.1, "The Security Policy Database (SPD)", - the SPD (or associated caches) MUST be consulted during the - processing of all traffic that crosses the IPsec protection boundary, - including IPsec management traffic. If no policy is found in the SPD - that matches a packet (for either inbound or outbound traffic), the - packet MUST be discarded. To simplify processing, and to allow for - very fast SA lookups (for SG/BITS/BITW), this document introduces the - - - -Kent & Seo Standards Track [Page 50] - -RFC 4301 Security Architecture for IP December 2005 - - - notion of an SPD cache for all outbound traffic (SPD-O plus SPD-S), - and a cache for inbound, non-IPsec-protected traffic (SPD-I). (As - mentioned earlier, the SAD acts as a cache for checking the selectors - of inbound IPsec-protected traffic arriving on SAs.) There is - nominally one cache per SPD. For the purposes of this specification, - it is assumed that each cached entry will map to exactly one SA. - Note, however, exceptions arise when one uses multiple SAs to carry - traffic of different priorities (e.g., as indicated by distinct DSCP - values) but the same selectors. Note also, that there are a couple - of situations in which the SAD can have entries for SAs that do not - have corresponding entries in the SPD. Since this document does not - mandate that the SAD be selectively cleared when the SPD is changed, - SAD entries can remain when the SPD entries that created them are - changed or deleted. Also, if a manually keyed SA is created, there - could be an SAD entry for this SA that does not correspond to any SPD - entry. - - Since SPD entries may overlap, one cannot safely cache these entries - in general. Simple caching might result in a match against a cache - entry, whereas an ordered search of the SPD would have resulted in a - match against a different entry. But, if the SPD entries are first - decorrelated, then the resulting entries can safely be cached. Each - cached entry will indicate that matching traffic should be bypassed - or discarded, appropriately. (Note: The original SPD entry might - result in multiple SAs, e.g., because of PFP.) Unless otherwise - noted, all references below to the "SPD" or "SPD cache" or "cache" - are to a decorrelated SPD (SPD-I, SPD-O, SPD-S) or the SPD cache - containing entries from the decorrelated SPD. - - Note: In a host IPsec implementation based on sockets, the SPD will - be consulted whenever a new socket is created to determine what, if - any, IPsec processing will be applied to the traffic that will flow - on that socket. This provides an implicit caching mechanism, and the - portions of the preceding discussion that address caching can be - ignored in such implementations. - - Note: It is assumed that one starts with a correlated SPD because - that is how users and administrators are accustomed to managing these - sorts of access control lists or firewall filter rules. Then the - decorrelation algorithm is applied to build a list of cache-able SPD - entries. The decorrelation is invisible at the management interface. - - For inbound IPsec traffic, the SAD entry selected by the SPI serves - as the cache for the selectors to be matched against arriving IPsec - packets, after AH or ESP processing has been performed. - - - - - - -Kent & Seo Standards Track [Page 51] - -RFC 4301 Security Architecture for IP December 2005 - - -5.1. Outbound IP Traffic Processing (protected-to-unprotected) - - First consider the path for traffic entering the implementation via a - protected interface and exiting via an unprotected interface. - - Unprotected Interface - ^ - | - (nested SAs) +----------+ - -------------------|Forwarding|<-----+ - | +----------+ | - | ^ | - | | BYPASS | - V +-----+ | - +-------+ | SPD | +--------+ - ...| SPD-I |.................|Cache|.....|PROCESS |...IPsec - | (*) | | (*) |---->|(AH/ESP)| boundary - +-------+ +-----+ +--------+ - | +-------+ / ^ - | |DISCARD| <--/ | - | +-------+ | - | | - | +-------------+ - |---------------->|SPD Selection| - +-------------+ - ^ - | +------+ - | -->| ICMP | - | / +------+ - |/ - | - | - Protected Interface - - - Figure 2. Processing Model for Outbound Traffic - (*) = The SPD caches are shown here. If there - is a cache miss, then the SPD is checked. - There is no requirement that an - implementation buffer the packet if - there is a cache miss. - - - - - - - - - - -Kent & Seo Standards Track [Page 52] - -RFC 4301 Security Architecture for IP December 2005 - - - IPsec MUST perform the following steps when processing outbound - packets: - - 1. When a packet arrives from the subscriber (protected) interface, - invoke the SPD selection function to obtain the SPD-ID needed to - choose the appropriate SPD. (If the implementation uses only one - SPD, this step is a no-op.) - - 2. Match the packet headers against the cache for the SPD specified - by the SPD-ID from step 1. Note that this cache contains entries - from SPD-O and SPD-S. - - 3a. If there is a match, then process the packet as specified by the - matching cache entry, i.e., BYPASS, DISCARD, or PROTECT using AH - or ESP. If IPsec processing is applied, there is a link from the - SPD cache entry to the relevant SAD entry (specifying the mode, - cryptographic algorithms, keys, SPI, PMTU, etc.). IPsec - processing is as previously defined, for tunnel or transport - modes and for AH or ESP, as specified in their respective RFCs - [Ken05b, Ken05a]. Note that the SA PMTU value, plus the value of - the stateful fragment checking flag (and the DF bit in the IP - header of the outbound packet) determine whether the packet can - (must) be fragmented prior to or after IPsec processing, or if it - must be discarded and an ICMP PMTU message is sent. - - 3b. If no match is found in the cache, search the SPD (SPD-S and - SPD-O parts) specified by SPD-ID. If the SPD entry calls for - BYPASS or DISCARD, create one or more new outbound SPD cache - entries and if BYPASS, create one or more new inbound SPD cache - entries. (More than one cache entry may be created since a - decorrelated SPD entry may be linked to other such entries that - were created as a side effect of the decorrelation process.) If - the SPD entry calls for PROTECT, i.e., creation of an SA, the key - management mechanism (e.g., IKEv2) is invoked to create the SA. - If SA creation succeeds, a new outbound (SPD-S) cache entry is - created, along with outbound and inbound SAD entries, otherwise - the packet is discarded. (A packet that triggers an SPD lookup - MAY be discarded by the implementation, or it MAY be processed - against the newly created cache entry, if one is created.) Since - SAs are created in pairs, an SAD entry for the corresponding - inbound SA also is created, and it contains the selector values - derived from the SPD entry (and packet, if any PFP flags were - "true") used to create the inbound SA, for use in checking - inbound traffic delivered via the SA. - - 4. The packet is passed to the outbound forwarding function - (operating outside of the IPsec implementation), to select the - interface to which the packet will be directed. This function - - - -Kent & Seo Standards Track [Page 53] - -RFC 4301 Security Architecture for IP December 2005 - - - may cause the packet to be passed back across the IPsec boundary, - for additional IPsec processing, e.g., in support of nested SAs. - If so, there MUST be an entry in SPD-I database that permits - inbound bypassing of the packet, otherwise the packet will be - discarded. If necessary, i.e., if there is more than one SPD-I, - the traffic being looped back MAY be tagged as coming from this - internal interface. This would allow the use of a different - SPD-I for "real" external traffic vs. looped traffic, if needed. - - Note: With the exception of IPv4 and IPv6 transport mode, an SG, - BITS, or BITW implementation MAY fragment packets before applying - IPsec. (This applies only to IPv4. For IPv6 packets, only the - originator is allowed to fragment them.) The device SHOULD have a - configuration setting to disable this. The resulting fragments are - evaluated against the SPD in the normal manner. Thus, fragments not - containing port numbers (or ICMP message type and code, or Mobility - Header type) will only match rules having port (or ICMP message type - and code, or MH type) selectors of OPAQUE or ANY. (See Section 7 for - more details.) - - Note: With regard to determining and enforcing the PMTU of an SA, the - IPsec system MUST follow the steps described in Section 8.2. - -5.1.1. Handling an Outbound Packet That Must Be Discarded - - If an IPsec system receives an outbound packet that it finds it must - discard, it SHOULD be capable of generating and sending an ICMP - message to indicate to the sender of the outbound packet that the - packet was discarded. The type and code of the ICMP message will - depend on the reason for discarding the packet, as specified below. - The reason SHOULD be recorded in the audit log. The audit log entry - for this event SHOULD include the reason, current date/time, and the - selector values from the packet. - - a. The selectors of the packet matched an SPD entry requiring the - packet to be discarded. - - IPv4 Type = 3 (destination unreachable) Code = 13 - (Communication Administratively Prohibited) - - IPv6 Type = 1 (destination unreachable) Code = 1 - (Communication with destination administratively - prohibited) - - b1. The IPsec system successfully reached the remote peer but was - unable to negotiate the SA required by the SPD entry matching the - packet because, for example, the remote peer is administratively - prohibited from communicating with the initiator, the initiating - - - -Kent & Seo Standards Track [Page 54] - -RFC 4301 Security Architecture for IP December 2005 - - - peer was unable to authenticate itself to the remote peer, the - remote peer was unable to authenticate itself to the initiating - peer, or the SPD at the remote peer did not have a suitable - entry. - - IPv4 Type = 3 (destination unreachable) Code = 13 - (Communication Administratively Prohibited) - - IPv6 Type = 1 (destination unreachable) Code = 1 - (Communication with destination administratively - prohibited) - - b2. The IPsec system was unable to set up the SA required by the SPD - entry matching the packet because the IPsec peer at the other end - of the exchange could not be contacted. - - IPv4 Type = 3 (destination unreachable) Code = 1 (host - unreachable) - - IPv6 Type = 1 (destination unreachable) Code = 3 (address - unreachable) - - Note that an attacker behind a security gateway could send packets - with a spoofed source address, W.X.Y.Z, to an IPsec entity causing it - to send ICMP messages to W.X.Y.Z. This creates an opportunity for a - denial of service (DoS) attack among hosts behind a security gateway. - To address this, a security gateway SHOULD include a management - control to allow an administrator to configure an IPsec - implementation to send or not send the ICMP messages under these - circumstances, and if this facility is selected, to rate limit the - transmission of such ICMP responses. - -5.1.2. Header Construction for Tunnel Mode - - This section describes the handling of the inner and outer IP - headers, extension headers, and options for AH and ESP tunnels, with - regard to outbound traffic processing. This includes how to - construct the encapsulating (outer) IP header, how to process fields - in the inner IP header, and what other actions should be taken for - outbound, tunnel mode traffic. The general processing described here - is modeled after RFC 2003, "IP Encapsulation within IP" [Per96]: - - o The outer IP header Source Address and Destination Address - identify the "endpoints" of the tunnel (the encapsulator and - decapsulator). The inner IP header Source Address and Destination - Addresses identify the original sender and recipient of the - datagram (from the perspective of this tunnel), respectively. - - - - -Kent & Seo Standards Track [Page 55] - -RFC 4301 Security Architecture for IP December 2005 - - - (See footnote 3 after the table in 5.1.2.1 for more details on the - encapsulating source IP address.) - - o The inner IP header is not changed except as noted below for TTL - (or Hop Limit) and the DS/ECN Fields. The inner IP header - otherwise remains unchanged during its delivery to the tunnel exit - point. - - o No change to IP options or extension headers in the inner header - occurs during delivery of the encapsulated datagram through the - tunnel. - - Note: IPsec tunnel mode is different from IP-in-IP tunneling (RFC - 2003 [Per96]) in several ways: - - o IPsec offers certain controls to a security administrator to - manage covert channels (which would not normally be a concern for - tunneling) and to ensure that the receiver examines the right - portions of the received packet with respect to application of - access controls. An IPsec implementation MAY be configurable with - regard to how it processes the outer DS field for tunnel mode for - transmitted packets. For outbound traffic, one configuration - setting for the outer DS field will operate as described in the - following sections on IPv4 and IPv6 header processing for IPsec - tunnels. Another will allow the outer DS field to be mapped to a - fixed value, which MAY be configured on a per-SA basis. (The value - might really be fixed for all traffic outbound from a device, but - per-SA granularity allows that as well.) This configuration option - allows a local administrator to decide whether the covert channel - provided by copying these bits outweighs the benefits of copying. - - o IPsec describes how to handle ECN or DS and provides the ability - to control propagation of changes in these fields between - unprotected and protected domains. In general, propagation from a - protected to an unprotected domain is a covert channel and thus - controls are provided to manage the bandwidth of this channel. - Propagation of ECN values in the other direction are controlled so - that only legitimate ECN changes (indicating occurrence of - congestion between the tunnel endpoints) are propagated. By - default, DS propagation from an unprotected domain to a protected - domain is not permitted. However, if the sender and receiver do - not share the same DS code space, and the receiver has no way of - learning how to map between the two spaces, then it may be - appropriate to deviate from the default. Specifically, an IPsec - implementation MAY be configurable in terms of how it processes - the outer DS field for tunnel mode for received packets. It may - be configured to either discard the outer DS value (the default) - OR to overwrite the inner DS field with the outer DS field. If - - - -Kent & Seo Standards Track [Page 56] - -RFC 4301 Security Architecture for IP December 2005 - - - offered, the discard vs. overwrite behavior MAY be configured on a - per-SA basis. This configuration option allows a local - administrator to decide whether the vulnerabilities created by - copying these bits outweigh the benefits of copying. See - [RFC2983] for further information on when each of these behaviors - may be useful, and also for the possible need for diffserv traffic - conditioning prior or subsequent to IPsec processing (including - tunnel decapsulation). - - o IPsec allows the IP version of the encapsulating header to be - different from that of the inner header. - - The tables in the following sub-sections show the handling for the - different header/option fields ("constructed" means that the value in - the outer field is constructed independently of the value in the - inner). - -5.1.2.1. IPv4: Header Construction for Tunnel Mode - - <-- How Outer Hdr Relates to Inner Hdr --> - Outer Hdr at Inner Hdr at - IPv4 Encapsulator Decapsulator - Header fields: -------------------- ------------ - version 4 (1) no change - header length constructed no change - DS Field copied from inner hdr (5) no change - ECN Field copied from inner hdr constructed (6) - total length constructed no change - ID constructed no change - flags (DF,MF) constructed, DF (4) no change - fragment offset constructed no change - TTL constructed (2) decrement (2) - protocol AH, ESP no change - checksum constructed constructed (2)(6) - src address constructed (3) no change - dest address constructed (3) no change - Options never copied no change - - Notes: - - (1) The IP version in the encapsulating header can be different - from the value in the inner header. - - (2) The TTL in the inner header is decremented by the encapsulator - prior to forwarding and by the decapsulator if it forwards the - packet. (The IPv4 checksum changes when the TTL changes.) - - - - - -Kent & Seo Standards Track [Page 57] - -RFC 4301 Security Architecture for IP December 2005 - - - Note: Decrementing the TTL value is a normal part of - forwarding a packet. Thus, a packet originating from the same - node as the encapsulator does not have its TTL decremented, - since the sending node is originating the packet rather than - forwarding it. This applies to BITS and native IPsec - implementations in hosts and routers. However, the IPsec - processing model includes an external forwarding capability. - TTL processing can be used to prevent looping of packets, - e.g., due to configuration errors, within the context of this - processing model. - - (3) Local and Remote addresses depend on the SA, which is used to - determine the Remote address, which in turn determines which - Local address (net interface) is used to forward the packet. - - Note: For multicast traffic, the destination address, or - source and destination addresses, may be required for - demuxing. In that case, it is important to ensure consistency - over the lifetime of the SA by ensuring that the source - address that appears in the encapsulating tunnel header is the - same as the one that was negotiated during the SA - establishment process. There is an exception to this general - rule, i.e., a mobile IPsec implementation will update its - source address as it moves. - - (4) Configuration determines whether to copy from the inner header - (IPv4 only), clear, or set the DF. - - (5) If the packet will immediately enter a domain for which the - DSCP value in the outer header is not appropriate, that value - MUST be mapped to an appropriate value for the domain - [NiBlBaBL98]. See RFC 2475 [BBCDWW98] for further - information. - - (6) If the ECN field in the inner header is set to ECT(0) or - ECT(1), where ECT is ECN-Capable Transport (ECT), and if the - ECN field in the outer header is set to Congestion Experienced - (CE), then set the ECN field in the inner header to CE; - otherwise, make no change to the ECN field in the inner - header. (The IPv4 checksum changes when the ECN changes.) - - Note: IPsec does not copy the options from the inner header into the - outer header, nor does IPsec construct the options in the outer - header. However, post-IPsec code MAY insert/construct options for - the outer header. - - - - - - -Kent & Seo Standards Track [Page 58] - -RFC 4301 Security Architecture for IP December 2005 - - -5.1.2.2. IPv6: Header Construction for Tunnel Mode - - <-- How Outer Hdr Relates Inner Hdr ---> - Outer Hdr at Inner Hdr at - IPv6 Encapsulator Decapsulator - Header fields: -------------------- ------------ - version 6 (1) no change - DS Field copied from inner hdr (5) no change (9) - ECN Field copied from inner hdr constructed (6) - flow label copied or configured (8) no change - payload length constructed no change - next header AH,ESP,routing hdr no change - hop limit constructed (2) decrement (2) - src address constructed (3) no change - dest address constructed (3) no change - Extension headers never copied (7) no change - - Notes: - - (1) - (6) See Section 5.1.2.1. - - (7) IPsec does not copy the extension headers from the inner - packet into outer headers, nor does IPsec construct extension - headers in the outer header. However, post-IPsec code MAY - insert/construct extension headers for the outer header. - - (8) See [RaCoCaDe04]. Copying is acceptable only for end systems, - not SGs. If an SG copied flow labels from the inner header to - the outer header, collisions might result. - - (9) An implementation MAY choose to provide a facility to pass the - DS value from the outer header to the inner header, on a per- - SA basis, for received tunnel mode packets. The motivation - for providing this feature is to accommodate situations in - which the DS code space at the receiver is different from that - of the sender and the receiver has no way of knowing how to - translate from the sender's space. There is a danger in - copying this value from the outer header to the inner header, - since it enables an attacker to modify the outer DSCP value in - a fashion that may adversely affect other traffic at the - receiver. Hence the default behavior for IPsec - implementations is NOT to permit such copying. - -5.2. Processing Inbound IP Traffic (unprotected-to-protected) - - Inbound processing is somewhat different from outbound processing, - because of the use of SPIs to map IPsec-protected traffic to SAs. - The inbound SPD cache (SPD-I) is applied only to bypassed or - - - -Kent & Seo Standards Track [Page 59] - -RFC 4301 Security Architecture for IP December 2005 - - - discarded traffic. If an arriving packet appears to be an IPsec - fragment from an unprotected interface, reassembly is performed prior - to IPsec processing. The intent for any SPD cache is that a packet - that fails to match any entry is then referred to the corresponding - SPD. Every SPD SHOULD have a nominal, final entry that catches - anything that is otherwise unmatched, and discards it. This ensures - that non-IPsec-protected traffic that arrives and does not match any - SPD-I entry will be discarded. - - Unprotected Interface - | - V - +-----+ IPsec protected - ------------------->|Demux|-------------------+ - | +-----+ | - | | | - | Not IPsec | | - | | | - | V | - | +-------+ +---------+ | - | |DISCARD|<---|SPD-I (*)| | - | +-------+ +---------+ | - | | | - | |-----+ | - | | | | - | | V | - | | +------+ | - | | | ICMP | | - | | +------+ | - | | V - +---------+ | +-----------+ - ....|SPD-O (*)|............|...................|PROCESS(**)|...IPsec - +---------+ | | (AH/ESP) | Boundary - ^ | +-----------+ - | | +---+ | - | BYPASS | +-->|IKE| | - | | | +---+ | - | V | V - | +----------+ +---------+ +----+ - |--------<------|Forwarding|<---------|SAD Check|-->|ICMP| - nested SAs +----------+ | (***) | +----+ - | +---------+ - V - Protected Interface - - Figure 3. Processing Model for Inbound Traffic - - - - - -Kent & Seo Standards Track [Page 60] - -RFC 4301 Security Architecture for IP December 2005 - - - (*) = The caches are shown here. If there is - a cache miss, then the SPD is checked. - There is no requirement that an - implementation buffer the packet if - there is a cache miss. - (**) = This processing includes using the - packet's SPI, etc., to look up the SA - in the SAD, which forms a cache of the - SPD for inbound packets (except for - cases noted in Sections 4.4.2 and 5). - See step 3a below. - (***) = This SAD check refers to step 4 below. - - Prior to performing AH or ESP processing, any IP fragments that - arrive via the unprotected interface are reassembled (by IP). Each - inbound IP datagram to which IPsec processing will be applied is - identified by the appearance of the AH or ESP values in the IP Next - Protocol field (or of AH or ESP as a next layer protocol in the IPv6 - context). - - IPsec MUST perform the following steps: - - 1. When a packet arrives, it may be tagged with the ID of the - interface (physical or virtual) via which it arrived, if - necessary, to support multiple SPDs and associated SPD-I caches. - (The interface ID is mapped to a corresponding SPD-ID.) - - 2. The packet is examined and demuxed into one of two categories: - - If the packet appears to be IPsec protected and it is addressed - to this device, an attempt is made to map it to an active SA - via the SAD. Note that the device may have multiple IP - addresses that may be used in the SAD lookup, e.g., in the case - of protocols such as SCTP. - - Traffic not addressed to this device, or addressed to this - device and not AH or ESP, is directed to SPD-I lookup. (This - implies that IKE traffic MUST have an explicit BYPASS entry in - the SPD.) If multiple SPDs are employed, the tag assigned to - the packet in step 1 is used to select the appropriate SPD-I - (and cache) to search. SPD-I lookup determines whether the - action is DISCARD or BYPASS. - - 3a. If the packet is addressed to the IPsec device and AH or ESP is - specified as the protocol, the packet is looked up in the SAD. - For unicast traffic, use only the SPI (or SPI plus protocol). - For multicast traffic, use the SPI plus the destination or SPI - plus destination and source addresses, as specified in Section - 4.1. In either case (unicast or multicast), if there is no match, - discard the traffic. This is an auditable event. The audit log - - - -Kent & Seo Standards Track [Page 61] - -RFC 4301 Security Architecture for IP December 2005 - - - entry for this event SHOULD include the current date/time, SPI, - source and destination of the packet, IPsec protocol, and any - other selector values of the packet that are available. If the - packet is found in the SAD, process it accordingly (see step 4). - - 3b. If the packet is not addressed to the device or is addressed to - this device and is not AH or ESP, look up the packet header in - the (appropriate) SPD-I cache. If there is a match and the - packet is to be discarded or bypassed, do so. If there is no - cache match, look up the packet in the corresponding SPD-I and - create a cache entry as appropriate. (No SAs are created in - response to receipt of a packet that requires IPsec protection; - only BYPASS or DISCARD cache entries can be created this way.) If - there is no match, discard the traffic. This is an auditable - event. The audit log entry for this event SHOULD include the - current date/time, SPI if available, IPsec protocol if available, - source and destination of the packet, and any other selector - values of the packet that are available. - - 3c. Processing of ICMP messages is assumed to take place on the - unprotected side of the IPsec boundary. Unprotected ICMP - messages are examined and local policy is applied to determine - whether to accept or reject these messages and, if accepted, what - action to take as a result. For example, if an ICMP unreachable - message is received, the implementation must decide whether to - act on it, reject it, or act on it with constraints. (See Section - 6.) - - 4. Apply AH or ESP processing as specified, using the SAD entry - selected in step 3a above. Then match the packet against the - inbound selectors identified by the SAD entry to verify that the - received packet is appropriate for the SA via which it was - received. - - 5. If an IPsec system receives an inbound packet on an SA and the - packet's header fields are not consistent with the selectors for - the SA, it MUST discard the packet. This is an auditable event. - The audit log entry for this event SHOULD include the current - date/time, SPI, IPsec protocol(s), source and destination of the - packet, any other selector values of the packet that are - available, and the selector values from the relevant SAD entry. - The system SHOULD also be capable of generating and sending an - IKE notification of INVALID_SELECTORS to the sender (IPsec peer), - indicating that the received packet was discarded because of - failure to pass selector checks. - - - - - - -Kent & Seo Standards Track [Page 62] - -RFC 4301 Security Architecture for IP December 2005 - - - To minimize the impact of a DoS attack, or a mis-configured peer, the - IPsec system SHOULD include a management control to allow an - administrator to configure the IPsec implementation to send or not - send this IKE notification, and if this facility is selected, to rate - limit the transmission of such notifications. - - After traffic is bypassed or processed through IPsec, it is handed to - the inbound forwarding function for disposition. This function may - cause the packet to be sent (outbound) across the IPsec boundary for - additional inbound IPsec processing, e.g., in support of nested SAs. - If so, then as with ALL outbound traffic that is to be bypassed, the - packet MUST be matched against an SPD-O entry. Ultimately, the - packet should be forwarded to the destination host or process for - disposition. - -6. ICMP Processing - - This section describes IPsec handling of ICMP traffic. There are two - categories of ICMP traffic: error messages (e.g., type = destination - unreachable) and non-error messages (e.g., type = echo). This - section applies exclusively to error messages. Disposition of - non-error, ICMP messages (that are not addressed to the IPsec - implementation itself) MUST be explicitly accounted for using SPD - entries. - - The discussion in this section applies to ICMPv6 as well as to - ICMPv4. Also, a mechanism SHOULD be provided to allow an - administrator to cause ICMP error messages (selected, all, or none) - to be logged as an aid to problem diagnosis. - -6.1. Processing ICMP Error Messages Directed to an IPsec Implementation - -6.1.1. ICMP Error Messages Received on the Unprotected Side of the - Boundary - - Figure 3 in Section 5.2 shows a distinct ICMP processing module on - the unprotected side of the IPsec boundary, for processing ICMP - messages (error or otherwise) that are addressed to the IPsec device - and that are not protected via AH or ESP. An ICMP message of this - sort is unauthenticated, and its processing may result in denial or - degradation of service. This suggests that, in general, it would be - desirable to ignore such messages. However, many ICMP messages will - be received by hosts or security gateways from unauthenticated - sources, e.g., routers in the public Internet. Ignoring these ICMP - messages can degrade service, e.g., because of a failure to process - PMTU message and redirection messages. Thus, there is also a - motivation for accepting and acting upon unauthenticated ICMP - messages. - - - -Kent & Seo Standards Track [Page 63] - -RFC 4301 Security Architecture for IP December 2005 - - - To accommodate both ends of this spectrum, a compliant IPsec - implementation MUST permit a local administrator to configure an - IPsec implementation to accept or reject unauthenticated ICMP - traffic. This control MUST be at the granularity of ICMP type and - MAY be at the granularity of ICMP type and code. Additionally, an - implementation SHOULD incorporate mechanisms and parameters for - dealing with such traffic. For example, there could be the ability - to establish a minimum PMTU for traffic (on a per destination basis), - to prevent receipt of an unauthenticated ICMP from setting the PMTU - to a trivial size. - - If an ICMP PMTU message passes the checks above and the system is - configured to accept it, then there are two possibilities. If the - implementation applies fragmentation on the ciphertext side of the - boundary, then the accepted PMTU information is passed to the - forwarding module (outside of the IPsec implementation), which uses - it to manage outbound packet fragmentation. If the implementation is - configured to effect plaintext side fragmentation, then the PMTU - information is passed to the plaintext side and processed as - described in Section 8.2. - -6.1.2. ICMP Error Messages Received on the Protected Side of the - Boundary - - These ICMP messages are not authenticated, but they do come from - sources on the protected side of the IPsec boundary. Thus, these - messages generally are viewed as more "trustworthy" than their - counterparts arriving from sources on the unprotected side of the - boundary. The major security concern here is that a compromised host - or router might emit erroneous ICMP error messages that could degrade - service for other devices "behind" the security gateway, or that - could even result in violations of confidentiality. For example, if - a bogus ICMP redirect were consumed by a security gateway, it could - cause the forwarding table on the protected side of the boundary to - be modified so as to deliver traffic to an inappropriate destination - "behind" the gateway. Thus, implementers MUST provide controls to - allow local administrators to constrain the processing of ICMP error - messages received on the protected side of the boundary, and directed - to the IPsec implementation. These controls are of the same type as - those employed on the unprotected side, described above in Section - 6.1.1. - -6.2. Processing Protected, Transit ICMP Error Messages - - When an ICMP error message is transmitted via an SA to a device - "behind" an IPsec implementation, both the payload and the header of - the ICMP message require checking from an access control perspective. - If one of these messages is forwarded to a host behind a security - - - -Kent & Seo Standards Track [Page 64] - -RFC 4301 Security Architecture for IP December 2005 - - - gateway, the receiving host IP implementation will make decisions - based on the payload, i.e., the header of the packet that purportedly - triggered the error response. Thus, an IPsec implementation MUST be - configurable to check that this payload header information is - consistent with the SA via which it arrives. (This means that the - payload header, with source and destination address and port fields - reversed, matches the traffic selectors for the SA.) If this sort of - check is not performed, then, for example, anyone with whom the - receiving IPsec system (A) has an active SA could send an ICMP - Destination Unreachable message that refers to any host/net with - which A is currently communicating, and thus effect a highly - efficient DoS attack regarding communication with other peers of A. - Normal IPsec receiver processing of traffic is not sufficient to - protect against such attacks. However, not all contexts may require - such checks, so it is also necessary to allow a local administrator - to configure an implementation to NOT perform such checks. - - To accommodate both policies, the following convention is adopted. - If an administrator wants to allow ICMP error messages to be carried - by an SA without inspection of the payload, then configure an SPD - entry that explicitly allows for carriage of such traffic. If an - administrator wants IPsec to check the payload of ICMP error messages - for consistency, then do not create any SPD entries that accommodate - carriage of such traffic based on the ICMP packet header. This - convention motivates the following processing description. - - IPsec senders and receivers MUST support the following processing for - ICMP error messages that are sent and received via SAs. - - If an SA exists that accommodates an outbound ICMP error message, - then the message is mapped to the SA and only the IP and ICMP headers - are checked upon receipt, just as would be the case for other - traffic. If no SA exists that matches the traffic selectors - associated with an ICMP error message, then the SPD is searched to - determine if such an SA can be created. If so, the SA is created and - the ICMP error message is transmitted via that SA. Upon receipt, - this message is subject to the usual traffic selector checks at the - receiver. This processing is exactly what would happen for traffic - in general, and thus does not represent any special processing for - ICMP error messages. - - If no SA exists that would carry the outbound ICMP message in - question, and if no SPD entry would allow carriage of this outbound - ICMP error message, then an IPsec implementation MUST map the message - to the SA that would carry the return traffic associated with the - packet that triggered the ICMP error message. This requires an IPsec - implementation to detect outbound ICMP error messages that map to no - extant SA or SPD entry, and treat them specially with regard to SA - - - -Kent & Seo Standards Track [Page 65] - -RFC 4301 Security Architecture for IP December 2005 - - - creation and lookup. The implementation extracts the header for the - packet that triggered the error (from the ICMP message payload), - reverses the source and destination IP address fields, extracts the - protocol field, and reverses the port fields (if accessible). It - then uses this extracted information to locate an appropriate, active - outbound SA, and transmits the error message via this SA. If no such - SA exists, no SA will be created, and this is an auditable event. - - If an IPsec implementation receives an inbound ICMP error message on - an SA, and the IP and ICMP headers of the message do not match the - traffic selectors for the SA, the receiver MUST process the received - message in a special fashion. Specifically, the receiver must - extract the header of the triggering packet from the ICMP payload, - and reverse fields as described above to determine if the packet is - consistent with the selectors for the SA via which the ICMP error - message was received. If the packet fails this check, the IPsec - implementation MUST NOT forwarded the ICMP message to the - destination. This is an auditable event. - -7. Handling Fragments (on the protected side of the IPsec boundary) - - Earlier sections of this document describe mechanisms for (a) - fragmenting an outbound packet after IPsec processing has been - applied and reassembling it at the receiver before IPsec processing - and (b) handling inbound fragments received from the unprotected side - of the IPsec boundary. This section describes how an implementation - should handle the processing of outbound plaintext fragments on the - protected side of the IPsec boundary. (See Appendix D, "Fragment - Handling Rationale".) In particular, it addresses: - - o mapping an outbound non-initial fragment to the right SA - (or finding the right SPD entry) - o verifying that a received non-initial fragment is - authorized for the SA via which it was received - o mapping outbound and inbound non-initial fragments to the - right SPD-O/SPD-I entry or the relevant cache entry, for - BYPASS/DISCARD traffic - - Note: In Section 4.1, transport mode SAs have been defined to not - carry fragments (IPv4 or IPv6). Note also that in Section 4.4.1, two - special values, ANY and OPAQUE, were defined for selectors and that - ANY includes OPAQUE. The term "non-trivial" is used to mean that the - selector has a value other than OPAQUE or ANY. - - Note: The term "non-initial fragment" is used here to indicate a - fragment that does not contain all the selector values that may be - needed for access control. As observed in Section 4.4.1, depending - on the Next Layer Protocol, in addition to Ports, the ICMP message - - - -Kent & Seo Standards Track [Page 66] - -RFC 4301 Security Architecture for IP December 2005 - - - type/code or Mobility Header type could be missing from non-initial - fragments. Also, for IPv6, even the first fragment might NOT contain - the Next Layer Protocol or Ports (or ICMP message type/code, or - Mobility Header type) depending on the kind and number of extension - headers present. If a non-initial fragment contains the Port (or - ICMP type and code or Mobility Header type) but not the Next Layer - Protocol, then unless there is an SPD entry for the relevant - Local/Remote addresses with ANY for Next Layer Protocol and Port (or - ICMP type and code or Mobility Header type), the fragment would not - contain all the selector information needed for access control. - - To address the above issues, three approaches have been defined: - - o Tunnel mode SAs that carry initial and non-initial fragments - (See Section 7.1.) - o Separate tunnel mode SAs for non-initial fragments (See - Section 7.2.) - o Stateful fragment checking (See Section 7.3.) - -7.1. Tunnel Mode SAs that Carry Initial and Non-Initial Fragments - - All implementations MUST support tunnel mode SAs that are configured - to pass traffic without regard to port field (or ICMP type/code or - Mobility Header type) values. If the SA will carry traffic for - specified protocols, the selector set for the SA MUST specify the - port fields (or ICMP type/code or Mobility Header type) as ANY. An - SA defined in this fashion will carry all traffic including initial - and non-initial fragments for the indicated Local/Remote addresses - and specified Next Layer protocol(s). If the SA will carry traffic - without regard to a specific protocol value (i.e., ANY is specified - as the (Next Layer) protocol selector value), then the port field - values are undefined and MUST be set to ANY as well. (As noted in - 4.4.1, ANY includes OPAQUE as well as all specific values.) - -7.2. Separate Tunnel Mode SAs for Non-Initial Fragments - - An implementation MAY support tunnel mode SAs that will carry only - non-initial fragments, separate from non-fragmented packets and - initial fragments. The OPAQUE value will be used to specify port (or - ICMP type/code or Mobility Header type) field selectors for an SA to - carry such fragments. Receivers MUST perform a minimum offset check - on IPv4 (non-initial) fragments to protect against overlapping - fragment attacks when SAs of this type are employed. Because such - checks cannot be performed on IPv6 non-initial fragments, users and - administrators are advised that carriage of such fragments may be - dangerous, and implementers may choose to NOT support such SAs for - IPv6 traffic. Also, an SA of this sort will carry all non-initial - fragments that match a specified Local/Remote address pair and - - - -Kent & Seo Standards Track [Page 67] - -RFC 4301 Security Architecture for IP December 2005 - - - protocol value, i.e., the fragments carried on this SA belong to - packets that if not fragmented, might have gone on separate SAs of - differing security. Therefore, users and administrators are advised - to protect such traffic using ESP (with integrity) and the - "strongest" integrity and encryption algorithms in use between both - peers. (Determination of the "strongest" algorithms requires - imposing an ordering of the available algorithms, a local - determination at the discretion of the initiator of the SA.) - - Specific port (or ICMP type/code or Mobility Header type) selector - values will be used to define SAs to carry initial fragments and - non-fragmented packets. This approach can be used if a user or - administrator wants to create one or more tunnel mode SAs between the - same Local/Remote addresses that discriminate based on port (or ICMP - type/code or Mobility Header type) fields. These SAs MUST have - non-trivial protocol selector values, otherwise approach #1 above - MUST be used. - - Note: In general, for the approach described in this section, one - needs only a single SA between two implementations to carry all - non-initial fragments. However, if one chooses to have multiple SAs - between the two implementations for QoS differentiation, then one - might also want multiple SAs to carry fragments-without-ports, one - for each supported QoS class. Since support for QoS via distinct SAs - is a local matter, not mandated by this document, the choice to have - multiple SAs to carry non-initial fragments should also be local. - -7.3. Stateful Fragment Checking - - An implementation MAY support some form of stateful fragment checking - for a tunnel mode SA with non-trivial port (or ICMP type/code or MH - type) field values (not ANY or OPAQUE). Implementations that will - transmit non-initial fragments on a tunnel mode SA that makes use of - non-trivial port (or ICMP type/code or MH type) selectors MUST notify - a peer via the IKE NOTIFY NON_FIRST_FRAGMENTS_ALSO payload. - - The peer MUST reject this proposal if it will not accept non-initial - fragments in this context. If an implementation does not - successfully negotiate transmission of non-initial fragments for such - an SA, it MUST NOT send such fragments over the SA. This standard - does not specify how peers will deal with such fragments, e.g., via - reassembly or other means, at either sender or receiver. However, a - receiver MUST discard non-initial fragments that arrive on an SA with - non-trivial port (or ICMP type/code or MH type) selector values - unless this feature has been negotiated. Also, the receiver MUST - discard non-initial fragments that do not comply with the security - policy applied to the overall packet. Discarding such packets is an - auditable event. Note that in network configurations where fragments - - - -Kent & Seo Standards Track [Page 68] - -RFC 4301 Security Architecture for IP December 2005 - - - of a packet might be sent or received via different security gateways - or BITW implementations, stateful strategies for tracking fragments - may fail. - -7.4. BYPASS/DISCARD Traffic - - All implementations MUST support DISCARDing of fragments using the - normal SPD packet classification mechanisms. All implementations - MUST support stateful fragment checking to accommodate BYPASS traffic - for which a non-trivial port range is specified. The concern is that - BYPASS of a cleartext, non-initial fragment arriving at an IPsec - implementation could undermine the security afforded IPsec-protected - traffic directed to the same destination. For example, consider an - IPsec implementation configured with an SPD entry that calls for - IPsec protection of traffic between a specific source/destination - address pair, and for a specific protocol and destination port, e.g., - TCP traffic on port 23 (Telnet). Assume that the implementation also - allows BYPASS of traffic from the same source/destination address - pair and protocol, but for a different destination port, e.g., port - 119 (NNTP). An attacker could send a non-initial fragment (with a - forged source address) that, if bypassed, could overlap with - IPsec-protected traffic from the same source and thus violate the - integrity of the IPsec-protected traffic. Requiring stateful - fragment checking for BYPASS entries with non-trivial port ranges - prevents attacks of this sort. As noted above, in network - configurations where fragments of a packet might be sent or received - via different security gateways or BITW implementations, stateful - strategies for tracking fragments may fail. - -8. Path MTU/DF Processing - - The application of AH or ESP to an outbound packet increases the size - of a packet and thus may cause a packet to exceed the PMTU for the SA - via which the packet will travel. An IPsec implementation also may - receive an unprotected ICMP PMTU message and, if it chooses to act - upon the message, the result will affect outbound traffic processing. - This section describes the processing required of an IPsec - implementation to deal with these two PMTU issues. - -8.1. DF Bit - - All IPsec implementations MUST support the option of copying the DF - bit from an outbound packet to the tunnel mode header that it emits, - when traffic is carried via a tunnel mode SA. This means that it - MUST be possible to configure the implementation's treatment of the - DF bit (set, clear, copy from inner header) for each SA. This - applies to SAs where both inner and outer headers are IPv4. - - - - -Kent & Seo Standards Track [Page 69] - -RFC 4301 Security Architecture for IP December 2005 - - -8.2. Path MTU (PMTU) Discovery - - This section discusses IPsec handling for unprotected Path MTU - Discovery messages. ICMP PMTU is used here to refer to an ICMP - message for: - - IPv4 (RFC 792 [Pos81b]): - - Type = 3 (Destination Unreachable) - - Code = 4 (Fragmentation needed and DF set) - - Next-Hop MTU in the low-order 16 bits of the - second word of the ICMP header (labeled "unused" - in RFC 792), with high-order 16 bits set to zero) - - IPv6 (RFC 2463 [CD98]): - - Type = 2 (Packet Too Big) - - Code = 0 (Fragmentation needed) - - Next-Hop MTU in the 32-bit MTU field of the ICMP6 - message - -8.2.1. Propagation of PMTU - - When an IPsec implementation receives an unauthenticated PMTU - message, and it is configured to process (vs. ignore) such messages, - it maps the message to the SA to which it corresponds. This mapping - is effected by extracting the header information from the payload of - the PMTU message and applying the procedure described in Section 5.2. - The PMTU determined by this message is used to update the SAD PMTU - field, taking into account the size of the AH or ESP header that will - be applied, any crypto synchronization data, and the overhead imposed - by an additional IP header, in the case of a tunnel mode SA. - - In a native host implementation, it is possible to maintain PMTU data - at the same granularity as for unprotected communication, so there is - no loss of functionality. Signaling of the PMTU information is - internal to the host. For all other IPsec implementation options, - the PMTU data must be propagated via a synthesized ICMP PMTU. In - these cases, the IPsec implementation SHOULD wait for outbound - traffic to be mapped to the SAD entry. When such traffic arrives, if - the traffic would exceed the updated PMTU value the traffic MUST be - handled as follows: - - Case 1: Original (cleartext) packet is IPv4 and has the DF - bit set. The implementation SHOULD discard the packet - and send a PMTU ICMP message. - - - - - - - -Kent & Seo Standards Track [Page 70] - -RFC 4301 Security Architecture for IP December 2005 - - - Case 2: Original (cleartext) packet is IPv4 and has the DF - bit clear. The implementation SHOULD fragment (before or - after encryption per its configuration) and then forward - the fragments. It SHOULD NOT send a PMTU ICMP message. - - Case 3: Original (cleartext) packet is IPv6. The implementation - SHOULD discard the packet and send a PMTU ICMP message. - -8.2.2. PMTU Aging - - In all IPsec implementations, the PMTU associated with an SA MUST be - "aged" and some mechanism is required to update the PMTU in a timely - manner, especially for discovering if the PMTU is smaller than - required by current network conditions. A given PMTU has to remain - in place long enough for a packet to get from the source of the SA to - the peer, and to propagate an ICMP error message if the current PMTU - is too big. - - Implementations SHOULD use the approach described in the Path MTU - Discovery document (RFC 1191 [MD90], Section 6.3), which suggests - periodically resetting the PMTU to the first-hop data-link MTU and - then letting the normal PMTU Discovery processes update the PMTU as - necessary. The period SHOULD be configurable. - -9. Auditing - - IPsec implementations are not required to support auditing. For the - most part, the granularity of auditing is a local matter. However, - several auditable events are identified in this document, and for - each of these events a minimum set of information that SHOULD be - included in an audit log is defined. Additional information also MAY - be included in the audit log for each of these events, and additional - events, not explicitly called out in this specification, also MAY - result in audit log entries. There is no requirement for the - receiver to transmit any message to the purported transmitter in - response to the detection of an auditable event, because of the - potential to induce denial of service via such action. - -10. Conformance Requirements - - All IPv4 IPsec implementations MUST comply with all requirements of - this document. All IPv6 implementations MUST comply with all - requirements of this document. - - - - - - - - -Kent & Seo Standards Track [Page 71] - -RFC 4301 Security Architecture for IP December 2005 - - -11. Security Considerations - - The focus of this document is security; hence security considerations - permeate this specification. - - IPsec imposes stringent constraints on bypass of IP header data in - both directions, across the IPsec barrier, especially when tunnel - mode SAs are employed. Some constraints are absolute, while others - are subject to local administrative controls, often on a per-SA - basis. For outbound traffic, these constraints are designed to limit - covert channel bandwidth. For inbound traffic, the constraints are - designed to prevent an adversary who has the ability to tamper with - one data stream (on the unprotected side of the IPsec barrier) from - adversely affecting other data streams (on the protected side of the - barrier). The discussion in Section 5 dealing with processing DSCP - values for tunnel mode SAs illustrates this concern. - - If an IPsec implementation is configured to pass ICMP error messages - over SAs based on the ICMP header values, without checking the header - information from the ICMP message payload, serious vulnerabilities - may arise. Consider a scenario in which several sites (A, B, and C) - are connected to one another via ESP-protected tunnels: A-B, A-C, and - B-C. Also assume that the traffic selectors for each tunnel specify - ANY for protocol and port fields and IP source/destination address - ranges that encompass the address range for the systems behind the - security gateways serving each site. This would allow a host at site - B to send an ICMP Destination Unreachable message to any host at site - A, that declares all hosts on the net at site C to be unreachable. - This is a very efficient DoS attack that could have been prevented if - the ICMP error messages were subjected to the checks that IPsec - provides, if the SPD is suitably configured, as described in Section - 6.2. - -12. IANA Considerations - - The IANA has assigned the value (3) for the asn1-modules registry and - has assigned the object identifier 1.3.6.1.5.8.3.1 for the SPD - module. See Appendix C, "ASN.1 for an SPD Entry". - -13. Differences from RFC 2401 - - This architecture document differs substantially from RFC 2401 - [RFC2401] in detail and in organization, but the fundamental notions - are unchanged. - - o The processing model has been revised to address new IPsec - scenarios, improve performance, and simplify implementation. This - includes a separation between forwarding (routing) and SPD - - - -Kent & Seo Standards Track [Page 72] - -RFC 4301 Security Architecture for IP December 2005 - - - selection, several SPD changes, and the addition of an outbound SPD - cache and an inbound SPD cache for bypassed or discarded traffic. - There is also a new database, the Peer Authorization Database - (PAD). This provides a link between an SA management protocol - (such as IKE) and the SPD. - - o There is no longer a requirement to support nested SAs or "SA - bundles". Instead this functionality can be achieved through SPD - and forwarding table configuration. An example of a configuration - has been added in Appendix E. - - o SPD entries were redefined to provide more flexibility. Each SPD - entry now consists of 1 to N sets of selectors, where each selector - set contains one protocol and a "list of ranges" can now be - specified for the Local IP address, Remote IP address, and whatever - fields (if any) are associated with the Next Layer Protocol (Local - Port, Remote Port, ICMP message type and code, and Mobility Header - type). An individual value for a selector is represented via a - trivial range and ANY is represented via a range than spans all - values for the selector. An example of an ASN.1 description is - included in Appendix C. - - o TOS (IPv4) and Traffic Class (IPv6) have been replaced by DSCP and - ECN. The tunnel section has been updated to explain how to handle - DSCP and ECN bits. - - o For tunnel mode SAs, an SG, BITS, or BITW implementation is now - allowed to fragment packets before applying IPsec. This applies - only to IPv4. For IPv6 packets, only the originator is allowed to - fragment them. - - o When security is desired between two intermediate systems along a - path or between an intermediate system and an end system, transport - mode may now be used between security gateways and between a - security gateway and a host. - - o This document clarifies that for all traffic that crosses the IPsec - boundary, including IPsec management traffic, the SPD or associated - caches must be consulted. - - o This document defines how to handle the situation of a security - gateway with multiple subscribers requiring separate IPsec - contexts. - - o A definition of reserved SPIs has been added. - - - - - - -Kent & Seo Standards Track [Page 73] - -RFC 4301 Security Architecture for IP December 2005 - - - o Text has been added explaining why ALL IP packets must be checked - -- IPsec includes minimal firewall functionality to support access - control at the IP layer. - - o The tunnel section has been updated to clarify how to handle the IP - options field and IPv6 extension headers when constructing the - outer header. - - o SA mapping for inbound traffic has been updated to be consistent - with the changes made in AH and ESP for support of unicast and - multicast SAs. - - o Guidance has been added regarding how to handle the covert channel - created in tunnel mode by copying the DSCP value to outer header. - - o Support for AH in both IPv4 and IPv6 is no longer required. - - o PMTU handling has been updated. The appendix on - PMTU/DF/Fragmentation has been deleted. - - o Three approaches have been added for handling plaintext fragments - on the protected side of the IPsec boundary. Appendix D documents - the rationale behind them. - - o Added revised text describing how to derive selector values for SAs - (from the SPD entry or from the packet, etc.) - - o Added a new table describing the relationship between selector - values in an SPD entry, the PFP flag, and resulting selector values - in the corresponding SAD entry. - - o Added Appendix B to describe decorrelation. - - o Added text describing how to handle an outbound packet that must be - discarded. - - o Added text describing how to handle a DISCARDED inbound packet, - i.e., one that does not match the SA upon which it arrived. - - o IPv6 mobility header has been added as a possible Next Layer - Protocol. IPv6 Mobility Header message type has been added as a - selector. - - o ICMP message type and code have been added as selectors. - - o The selector "data sensitivity level" has been removed to simplify - things. - - - - -Kent & Seo Standards Track [Page 74] - -RFC 4301 Security Architecture for IP December 2005 - - - o Updated text describing handling ICMP error messages. The appendix - on "Categorization of ICMP Messages" has been deleted. - - o The text for the selector name has been updated and clarified. - - o The "Next Layer Protocol" has been further explained and a default - list of protocols to skip when looking for the Next Layer Protocol - has been added. - - o The text has been amended to say that this document assumes use of - IKEv2 or an SA management protocol with comparable features. - - o Text has been added clarifying the algorithm for mapping inbound - IPsec datagrams to SAs in the presence of multicast SAs. - - o The appendix "Sequence Space Window Code Example" has been removed. - - o With respect to IP addresses and ports, the terms "Local" and - "Remote" are used for policy rules (replacing source and - destination). "Local" refers to the entity being protected by an - IPsec implementation, i.e., the "source" address/port of outbound - packets or the "destination" address/port of inbound packets. - "Remote" refers to a peer entity or peer entities. The terms - "source" and "destination" are still used for packet header fields. - -14. Acknowledgements - - The authors would like to acknowledge the contributions of Ran - Atkinson, who played a critical role in initial IPsec activities, and - who authored the first series of IPsec standards: RFCs 1825-1827; and - Charlie Lynn, who made significant contributions to the second series - of IPsec standards (RFCs 2401, 2402, and 2406) and to the current - versions, especially with regard to IPv6 issues. The authors also - would like to thank the members of the IPsec and MSEC working groups - who have contributed to the development of this protocol - specification. - - - - - - - - - - - - - - - -Kent & Seo Standards Track [Page 75] - -RFC 4301 Security Architecture for IP December 2005 - - -Appendix A: Glossary - - This section provides definitions for several key terms that are - employed in this document. Other documents provide additional - definitions and background information relevant to this technology, - e.g., [Shi00], [VK83], and [HA94]. Included in this glossary are - generic security service and security mechanism terms, plus - IPsec-specific terms. - - Access Control - A security service that prevents unauthorized use of a resource, - including the prevention of use of a resource in an unauthorized - manner. In the IPsec context, the resource to which access is - being controlled is often: - - o for a host, computing cycles or data - o for a security gateway, a network behind the gateway - or bandwidth on that network. - - Anti-replay - See "Integrity" below. - - Authentication - Used informally to refer to the combination of two nominally - distinct security services, data origin authentication and - connectionless integrity. See the definitions below for each of - these services. - - Availability - When viewed as a security service, addresses the security concerns - engendered by attacks against networks that deny or degrade - service. For example, in the IPsec context, the use of - anti-replay mechanisms in AH and ESP support availability. - - Confidentiality - The security service that protects data from unauthorized - disclosure. The primary confidentiality concern in most instances - is unauthorized disclosure of application-level data, but - disclosure of the external characteristics of communication also - can be a concern in some circumstances. Traffic flow - confidentiality is the service that addresses this latter concern - by concealing source and destination addresses, message length, or - frequency of communication. In the IPsec context, using ESP in - tunnel mode, especially at a security gateway, can provide some - level of traffic flow confidentiality. (See also "Traffic - Analysis" below.) - - - - - -Kent & Seo Standards Track [Page 76] - -RFC 4301 Security Architecture for IP December 2005 - - - Data Origin Authentication - A security service that verifies the identity of the claimed - source of data. This service is usually bundled with - connectionless integrity service. - - Encryption - A security mechanism used to transform data from an intelligible - form (plaintext) into an unintelligible form (ciphertext), to - provide confidentiality. The inverse transformation process is - designated "decryption". Often the term "encryption" is used to - generically refer to both processes. - - Integrity - A security service that ensures that modifications to data are - detectable. Integrity comes in various flavors to match - application requirements. IPsec supports two forms of integrity: - connectionless and a form of partial sequence integrity. - Connectionless integrity is a service that detects modification of - an individual IP datagram, without regard to the ordering of the - datagram in a stream of traffic. The form of partial sequence - integrity offered in IPsec is referred to as anti-replay - integrity, and it detects arrival of duplicate IP datagrams - (within a constrained window). This is in contrast to - connection-oriented integrity, which imposes more stringent - sequencing requirements on traffic, e.g., to be able to detect - lost or re-ordered messages. Although authentication and - integrity services often are cited separately, in practice they - are intimately connected and almost always offered in tandem. - - Protected vs. Unprotected - "Protected" refers to the systems or interfaces that are inside - the IPsec protection boundary, and "unprotected" refers to the - systems or interfaces that are outside the IPsec protection - boundary. IPsec provides a boundary through which traffic passes. - There is an asymmetry to this barrier, which is reflected in the - processing model. Outbound data, if not discarded or bypassed, is - protected via the application of AH or ESP and the addition of the - corresponding headers. Inbound data, if not discarded or - bypassed, is processed via the removal of AH or ESP headers. In - this document, inbound traffic enters an IPsec implementation from - the "unprotected" interface. Outbound traffic enters the - implementation via the "protected" interface, or is internally - generated by the implementation on the "protected" side of the - boundary and directed toward the "unprotected" interface. An - IPsec implementation may support more than one interface on either - or both sides of the boundary. The protected interface may be - - - - - -Kent & Seo Standards Track [Page 77] - -RFC 4301 Security Architecture for IP December 2005 - - - internal, e.g., in a host implementation of IPsec. The protected - interface may link to a socket layer interface presented by the - OS. - - Security Association (SA) - A simplex (uni-directional) logical connection, created for - security purposes. All traffic traversing an SA is provided the - same security processing. In IPsec, an SA is an Internet-layer - abstraction implemented through the use of AH or ESP. State data - associated with an SA is represented in the SA Database (SAD). - - Security Gateway - An intermediate system that acts as the communications interface - between two networks. The set of hosts (and networks) on the - external side of the security gateway is termed unprotected (they - are generally at least less protected than those "behind" the SG), - while the networks and hosts on the internal side are viewed as - protected. The internal subnets and hosts served by a security - gateway are presumed to be trusted by virtue of sharing a common, - local, security administration. In the IPsec context, a security - gateway is a point at which AH and/or ESP is implemented in order - to serve a set of internal hosts, providing security services for - these hosts when they communicate with external hosts also - employing IPsec (either directly or via another security gateway). - - Security Parameters Index (SPI) - An arbitrary 32-bit value that is used by a receiver to identify - the SA to which an incoming packet should be bound. For a unicast - SA, the SPI can be used by itself to specify an SA, or it may be - used in conjunction with the IPsec protocol type. Additional IP - address information is used to identify multicast SAs. The SPI is - carried in AH and ESP protocols to enable the receiving system to - select the SA under which a received packet will be processed. An - SPI has only local significance, as defined by the creator of the - SA (usually the receiver of the packet carrying the SPI); thus an - SPI is generally viewed as an opaque bit string. However, the - creator of an SA may choose to interpret the bits in an SPI to - facilitate local processing. - - Traffic Analysis - The analysis of network traffic flow for the purpose of deducing - information that is useful to an adversary. Examples of such - information are frequency of transmission, the identities of the - conversing parties, sizes of packets, and flow identifiers - [Sch94]. - - - - - - -Kent & Seo Standards Track [Page 78] - -RFC 4301 Security Architecture for IP December 2005 - - -Appendix B: Decorrelation - - This appendix is based on work done for caching of policies in the IP - Security Policy Working Group by Luis Sanchez, Matt Condell, and John - Zao. - - Two SPD entries are correlated if there is a non-null intersection - between the values of corresponding selectors in each entry. Caching - correlated SPD entries can lead to incorrect policy enforcement. A - solution to this problem, which still allows for caching, is to - remove the ambiguities by decorrelating the entries. That is, the - SPD entries must be rewritten so that for every pair of entries there - exists a selector for which there is a null intersection between the - values in both of the entries. Once the entries are decorrelated, - there is no longer any ordering requirement on them, since only one - entry will match any lookup. The next section describes - decorrelation in more detail and presents an algorithm that may be - used to implement decorrelation. - -B.1. Decorrelation Algorithm - - The basic decorrelation algorithm takes each entry in a correlated - SPD and divides it into a set of entries using a tree structure. - The nodes of the tree are the selectors that may overlap between the - policies. At each node, the algorithm creates a branch for each of - the values of the selector. It also creates one branch for the - complement of the union of all selector values. Policies are then - formed by traversing the tree from the root to each leaf. The - policies at the leaves are compared to the set of already - decorrelated policy rules. Each policy at a leaf is either - completely overridden by a policy in the already decorrelated set and - is discarded or is decorrelated with all the policies in the - decorrelated set and is added to it. - - The basic algorithm does not guarantee an optimal set of decorrelated - entries. That is, the entries may be broken up into smaller sets - than is necessary, though they will still provide all the necessary - policy information. Some extensions to the basic algorithm are - described later to improve this and improve the performance of the - algorithm. - - C A set of ordered, correlated entries (a correlated SPD). - Ci The ith entry in C. - U The set of decorrelated entries being built from C. - Ui The ith entry in U. - Sik The kth selection for policy Ci. - Ai The action for policy Ci. - - - - -Kent & Seo Standards Track [Page 79] - -RFC 4301 Security Architecture for IP December 2005 - - - A policy (SPD entry) P may be expressed as a sequence of selector - values and an action (BYPASS, DISCARD, or PROTECT): - - Ci = Si1 x Si2 x ... x Sik -> Ai - - 1) Put C1 in set U as U1 - - For each policy Cj (j > 1) in C - - 2) If Cj is decorrelated with every entry in U, then add it to U. - - 3) If Cj is correlated with one or more entries in U, create a tree - rooted at the policy Cj that partitions Cj into a set of decorrelated - entries. The algorithm starts with a root node where no selectors - have yet been chosen. - - A) Choose a selector in Cj, Sjn, that has not yet been chosen when - traversing the tree from the root to this node. If there are no - selectors not yet used, continue to the next unfinished branch - until all branches have been completed. When the tree is - completed, go to step D. - - T is the set of entries in U that are correlated with the entry - at this node. - - The entry at this node is the entry formed by the selector - values of each of the branches between the root and this node. - Any selector values that are not yet represented by branches - assume the corresponding selector value in Cj, since the values - in Cj represent the maximum value for each selector. - - B) Add a branch to the tree for each value of the selector Sjn that - appears in any of the entries in T. (If the value is a superset - of the value of Sjn in Cj, then use the value in Cj, since that - value represents the universal set.) Also add a branch for the - complement of the union of all the values of the selector Sjn - in T. When taking the complement, remember that the universal - set is the value of Sjn in Cj. A branch need not be created - for the null set. - - C) Repeat A and B until the tree is completed. - - D) The entry to each leaf now represents an entry that is a subset - of Cj. The entries at the leaves completely partition Cj in - such a way that each entry is either completely overridden by - an entry in U, or is decorrelated with the entries in U. - - Add all the decorrelated entries at the leaves of the tree to U. - - - -Kent & Seo Standards Track [Page 80] - -RFC 4301 Security Architecture for IP December 2005 - - - 4) Get next Cj and go to 2. - - 5) When all entries in C have been processed, then U will contain an - decorrelated version of C. - - There are several optimizations that can be made to this algorithm. - A few of them are presented here. - - It is possible to optimize, or at least improve, the amount of - branching that occurs by carefully choosing the order of the - selectors used for the next branch. For example, if a selector Sjn - can be chosen so that all the values for that selector in T are equal - to or a superset of the value of Sjn in Cj, then only a single branch - needs to be created (since the complement will be null). - - Branches of the tree do not have to proceed with the entire - decorrelation algorithm. For example, if a node represents an entry - that is decorrelated with all the entries in U, then there is no - reason to continue decorrelating that branch. Also, if a branch is - completely overridden by an entry in U, then there is no reason to - continue decorrelating the branch. - - An additional optimization is to check to see if a branch is - overridden by one of the CORRELATED entries in set C that has already - been decorrelated. That is, if the branch is part of decorrelating - Cj, then check to see if it was overridden by an entry Cm, m < j. - This is a valid check, since all the entries Cm are already expressed - in U. - - Along with checking if an entry is already decorrelated in step 2, - check if Cj is overridden by any entry in U. If it is, skip it since - it is not relevant. An entry x is overridden by another entry y if - every selector in x is equal to or a subset of the corresponding - selector in entry y. - - - - - - - - - - - - - - - - - -Kent & Seo Standards Track [Page 81] - -RFC 4301 Security Architecture for IP December 2005 - - -Appendix C: ASN.1 for an SPD Entry - - This appendix is included as an additional way to describe SPD - entries, as defined in Section 4.4.1. It uses ASN.1 syntax that has - been successfully compiled. This syntax is merely illustrative and - need not be employed in an implementation to achieve compliance. The - SPD description in Section 4.4.1 is normative. - - SPDModule - - {iso(1) org (3) dod (6) internet (1) security (5) mechanisms (5) - ipsec (8) asn1-modules (3) spd-module (1) } - - DEFINITIONS IMPLICIT TAGS ::= - - BEGIN - - IMPORTS - RDNSequence FROM PKIX1Explicit88 - { iso(1) identified-organization(3) - dod(6) internet(1) security(5) mechanisms(5) pkix(7) - id-mod(0) id-pkix1-explicit(18) } ; - - -- An SPD is a list of policies in decreasing order of preference - SPD ::= SEQUENCE OF SPDEntry - - SPDEntry ::= CHOICE { - iPsecEntry IPsecEntry, -- PROTECT traffic - bypassOrDiscard [0] BypassOrDiscardEntry } -- DISCARD/BYPASS - - IPsecEntry ::= SEQUENCE { -- Each entry consists of - name NameSets OPTIONAL, - pFPs PacketFlags, -- Populate from packet flags - -- Applies to ALL of the corresponding - -- traffic selectors in the SelectorLists - condition SelectorLists, -- Policy "condition" - processing Processing -- Policy "action" - } - - BypassOrDiscardEntry ::= SEQUENCE { - bypass BOOLEAN, -- TRUE BYPASS, FALSE DISCARD - condition InOutBound } - - InOutBound ::= CHOICE { - outbound [0] SelectorLists, - inbound [1] SelectorLists, - bothways [2] BothWays } - - - - -Kent & Seo Standards Track [Page 82] - -RFC 4301 Security Architecture for IP December 2005 - - - BothWays ::= SEQUENCE { - inbound SelectorLists, - outbound SelectorLists } - - NameSets ::= SEQUENCE { - passed SET OF Names-R, -- Matched to IKE ID by - -- responder - local SET OF Names-I } -- Used internally by IKE - -- initiator - - Names-R ::= CHOICE { -- IKEv2 IDs - dName RDNSequence, -- ID_DER_ASN1_DN - fqdn FQDN, -- ID_FQDN - rfc822 [0] RFC822Name, -- ID_RFC822_ADDR - keyID OCTET STRING } -- KEY_ID - - Names-I ::= OCTET STRING -- Used internally by IKE - -- initiator - - FQDN ::= IA5String - - RFC822Name ::= IA5String - - PacketFlags ::= BIT STRING { - -- if set, take selector value from packet - -- establishing SA - -- else use value in SPD entry - localAddr (0), - remoteAddr (1), - protocol (2), - localPort (3), - remotePort (4) } - - SelectorLists ::= SET OF SelectorList - - SelectorList ::= SEQUENCE { - localAddr AddrList, - remoteAddr AddrList, - protocol ProtocolChoice } - - Processing ::= SEQUENCE { - extSeqNum BOOLEAN, -- TRUE 64 bit counter, FALSE 32 bit - seqOverflow BOOLEAN, -- TRUE rekey, FALSE terminate & audit - fragCheck BOOLEAN, -- TRUE stateful fragment checking, - -- FALSE no stateful fragment checking - lifetime SALifetime, - spi ManualSPI, - algorithms ProcessingAlgs, - - - -Kent & Seo Standards Track [Page 83] - -RFC 4301 Security Architecture for IP December 2005 - - - tunnel TunnelOptions OPTIONAL } -- if absent, use - -- transport mode - - SALifetime ::= SEQUENCE { - seconds [0] INTEGER OPTIONAL, - bytes [1] INTEGER OPTIONAL } - - ManualSPI ::= SEQUENCE { - spi INTEGER, - keys KeyIDs } - - KeyIDs ::= SEQUENCE OF OCTET STRING - - ProcessingAlgs ::= CHOICE { - ah [0] IntegrityAlgs, -- AH - esp [1] ESPAlgs} -- ESP - - ESPAlgs ::= CHOICE { - integrity [0] IntegrityAlgs, -- integrity only - confidentiality [1] ConfidentialityAlgs, -- confidentiality - -- only - both [2] IntegrityConfidentialityAlgs, - combined [3] CombinedModeAlgs } - - IntegrityConfidentialityAlgs ::= SEQUENCE { - integrity IntegrityAlgs, - confidentiality ConfidentialityAlgs } - - -- Integrity Algorithms, ordered by decreasing preference - IntegrityAlgs ::= SEQUENCE OF IntegrityAlg - - -- Confidentiality Algorithms, ordered by decreasing preference - ConfidentialityAlgs ::= SEQUENCE OF ConfidentialityAlg - - -- Integrity Algorithms - IntegrityAlg ::= SEQUENCE { - algorithm IntegrityAlgType, - parameters ANY -- DEFINED BY algorithm -- OPTIONAL } - - IntegrityAlgType ::= INTEGER { - none (0), - auth-HMAC-MD5-96 (1), - auth-HMAC-SHA1-96 (2), - auth-DES-MAC (3), - auth-KPDK-MD5 (4), - auth-AES-XCBC-96 (5) - -- tbd (6..65535) - } - - - -Kent & Seo Standards Track [Page 84] - -RFC 4301 Security Architecture for IP December 2005 - - - -- Confidentiality Algorithms - ConfidentialityAlg ::= SEQUENCE { - algorithm ConfidentialityAlgType, - parameters ANY -- DEFINED BY algorithm -- OPTIONAL } - - ConfidentialityAlgType ::= INTEGER { - encr-DES-IV64 (1), - encr-DES (2), - encr-3DES (3), - encr-RC5 (4), - encr-IDEA (5), - encr-CAST (6), - encr-BLOWFISH (7), - encr-3IDEA (8), - encr-DES-IV32 (9), - encr-RC4 (10), - encr-NULL (11), - encr-AES-CBC (12), - encr-AES-CTR (13) - -- tbd (14..65535) - } - - CombinedModeAlgs ::= SEQUENCE OF CombinedModeAlg - - CombinedModeAlg ::= SEQUENCE { - algorithm CombinedModeType, - parameters ANY -- DEFINED BY algorithm} -- defined outside - -- of this document for AES modes. - - CombinedModeType ::= INTEGER { - comb-AES-CCM (1), - comb-AES-GCM (2) - -- tbd (3..65535) - } - - TunnelOptions ::= SEQUENCE { - dscp DSCP, - ecn BOOLEAN, -- TRUE Copy CE to inner header - df DF, - addresses TunnelAddresses } - - TunnelAddresses ::= CHOICE { - ipv4 IPv4Pair, - ipv6 [0] IPv6Pair } - - IPv4Pair ::= SEQUENCE { - local OCTET STRING (SIZE(4)), - remote OCTET STRING (SIZE(4)) } - - - -Kent & Seo Standards Track [Page 85] - -RFC 4301 Security Architecture for IP December 2005 - - - IPv6Pair ::= SEQUENCE { - local OCTET STRING (SIZE(16)), - remote OCTET STRING (SIZE(16)) } - - DSCP ::= SEQUENCE { - copy BOOLEAN, -- TRUE copy from inner header - -- FALSE do not copy - mapping OCTET STRING OPTIONAL} -- points to table - -- if no copy - - DF ::= INTEGER { - clear (0), - set (1), - copy (2) } - - ProtocolChoice::= CHOICE { - anyProt AnyProtocol, -- for ANY protocol - noNext [0] NoNextLayerProtocol, -- has no next layer - -- items - oneNext [1] OneNextLayerProtocol, -- has one next layer - -- item - twoNext [2] TwoNextLayerProtocol, -- has two next layer - -- items - fragment FragmentNoNext } -- has no next layer - -- info - - AnyProtocol ::= SEQUENCE { - id INTEGER (0), -- ANY protocol - nextLayer AnyNextLayers } - - AnyNextLayers ::= SEQUENCE { -- with either - first AnyNextLayer, -- ANY next layer selector - second AnyNextLayer } -- ANY next layer selector - - NoNextLayerProtocol ::= INTEGER (2..254) - - FragmentNoNext ::= INTEGER (44) -- Fragment identifier - - OneNextLayerProtocol ::= SEQUENCE { - id INTEGER (1..254), -- ICMP, MH, ICMPv6 - nextLayer NextLayerChoice } -- ICMP Type*256+Code - -- MH Type*256 - - TwoNextLayerProtocol ::= SEQUENCE { - id INTEGER (2..254), -- Protocol - local NextLayerChoice, -- Local and - remote NextLayerChoice } -- Remote ports - - - - -Kent & Seo Standards Track [Page 86] - -RFC 4301 Security Architecture for IP December 2005 - - - NextLayerChoice ::= CHOICE { - any AnyNextLayer, - opaque [0] OpaqueNextLayer, - range [1] NextLayerRange } - - -- Representation of ANY in next layer field - AnyNextLayer ::= SEQUENCE { - start INTEGER (0), - end INTEGER (65535) } - - -- Representation of OPAQUE in next layer field. - -- Matches IKE convention - OpaqueNextLayer ::= SEQUENCE { - start INTEGER (65535), - end INTEGER (0) } - - -- Range for a next layer field - NextLayerRange ::= SEQUENCE { - start INTEGER (0..65535), - end INTEGER (0..65535) } - - -- List of IP addresses - AddrList ::= SEQUENCE { - v4List IPv4List OPTIONAL, - v6List [0] IPv6List OPTIONAL } - - -- IPv4 address representations - IPv4List ::= SEQUENCE OF IPv4Range - - IPv4Range ::= SEQUENCE { -- close, but not quite right ... - ipv4Start OCTET STRING (SIZE (4)), - ipv4End OCTET STRING (SIZE (4)) } - - -- IPv6 address representations - IPv6List ::= SEQUENCE OF IPv6Range - - IPv6Range ::= SEQUENCE { -- close, but not quite right ... - ipv6Start OCTET STRING (SIZE (16)), - ipv6End OCTET STRING (SIZE (16)) } - - END - - - - - - - - - - -Kent & Seo Standards Track [Page 87] - -RFC 4301 Security Architecture for IP December 2005 - - -Appendix D: Fragment Handling Rationale - - There are three issues that must be resolved regarding processing of - (plaintext) fragments in IPsec: - - - mapping a non-initial, outbound fragment to the right SA - (or finding the right SPD entry) - - verifying that a received, non-initial fragment is authorized - for the SA via which it is received - - mapping outbound and inbound non-initial fragments to the - right SPD/cache entry, for BYPASS/DISCARD traffic - - The first and third issues arise because we need a deterministic - algorithm for mapping traffic to SAs (and SPD/cache entries). All - three issues are important because we want to make sure that - non-initial fragments that cross the IPsec boundary do not cause the - access control policies in place at the receiver (or transmitter) to - be violated. - -D.1. Transport Mode and Fragments - - First, we note that transport mode SAs have been defined to not carry - fragments. This is a carryover from RFC 2401, where transport mode - SAs always terminated at endpoints. This is a fundamental - requirement because, in the worst case, an IPv4 fragment to which - IPsec was applied might then be fragmented (as a ciphertext packet), - en route to the destination. IP fragment reassembly procedures at - the IPsec receiver would not be able to distinguish between pre-IPsec - fragments and fragments created after IPsec processing. - - For IPv6, only the sender is allowed to fragment a packet. As for - IPv4, an IPsec implementation is allowed to fragment tunnel mode - packets after IPsec processing, because it is the sender relative to - the (outer) tunnel header. However, unlike IPv4, it would be - feasible to carry a plaintext fragment on a transport mode SA, - because the fragment header in IPv6 would appear after the AH or ESP - header, and thus would not cause confusion at the receiver with - respect to reassembly. Specifically, the receiver would not attempt - reassembly for the fragment until after IPsec processing. To keep - things simple, this specification prohibits carriage of fragments on - transport mode SAs for IPv6 traffic. - - When only end systems used transport mode SAs, the prohibition on - carriage of fragments was not a problem, since we assumed that the - end system could be configured to not offer a fragment to IPsec. For - a native host implementation, this seems reasonable, and, as someone - already noted, RFC 2401 warned that a BITS implementation might have - to reassemble fragments before performing an SA lookup. (It would - - - -Kent & Seo Standards Track [Page 88] - -RFC 4301 Security Architecture for IP December 2005 - - - then apply AH or ESP and could re-fragment the packet after IPsec - processing.) Because a BITS implementation is assumed to be able to - have access to all traffic emanating from its host, even if the host - has multiple interfaces, this was deemed a reasonable mandate. - - In this specification, it is acceptable to use transport mode in - cases where the IPsec implementation is not the ultimate destination, - e.g., between two SGs. In principle, this creates a new opportunity - for outbound, plaintext fragments to be mapped to a transport mode SA - for IPsec processing. However, in these new contexts in which a - transport mode SA is now approved for use, it seems likely that we - can continue to prohibit transmission of fragments, as seen by IPsec, - i.e., packets that have an "outer header" with a non-zero fragment - offset field. For example, in an IP overlay network, packets being - sent over transport mode SAs are IP-in-IP tunneled and thus have the - necessary inner header to accommodate fragmentation prior to IPsec - processing. When carried via a transport mode SA, IPsec would not - examine the inner IP header for such traffic, and thus would not - consider the packet to be a fragment. - -D.2. Tunnel Mode and Fragments - - For tunnel mode SAs, it has always been the case that outbound - fragments might arrive for processing at an IPsec implementation. - The need to accommodate fragmented outbound packets can pose a - problem because a non-initial fragment generally will not contain the - port fields associated with a next layer protocol such as TCP, UDP, - or SCTP. Thus, depending on the SPD configuration for a given IPsec - implementation, plaintext fragments might or might not pose a - problem. - - For example, if the SPD requires that all traffic between two address - ranges is offered IPsec protection (no BYPASS or DISCARD SPD entries - apply to this address range), then it should be easy to carry - non-initial fragments on the SA defined for this address range, since - the SPD entry implies an intent to carry ALL traffic between the - address ranges. But, if there are multiple SPD entries that could - match a fragment, and if these entries reference different subsets of - port fields (vs. ANY), then it is not possible to map an outbound - non-initial fragment to the right entry, unambiguously. (If we choose - to allow carriage of fragments on transport mode SAs for IPv6, the - problems arises in that context as well.) - - This problem largely, though not exclusively, motivated the - definition of OPAQUE as a selector value for port fields in RFC 2401. - The other motivation for OPAQUE is the observation that port fields - might not be accessible due to the prior application of IPsec. For - example, if a host applied IPsec to its traffic and that traffic - - - -Kent & Seo Standards Track [Page 89] - -RFC 4301 Security Architecture for IP December 2005 - - - arrived at an SG, these fields would be encrypted. The algorithm - specified for locating the "next layer protocol" described in RFC - 2401 also motivated use of OPAQUE to accommodate an encrypted next - layer protocol field in such circumstances. Nonetheless, the primary - use of the OPAQUE value was to match traffic selector fields in - packets that did not contain port fields (non-initial fragments), or - packets in which the port fields were already encrypted (as a result - of nested application of IPsec). RFC 2401 was ambiguous in - discussing the use of OPAQUE vs. ANY, suggesting in some places that - ANY might be an alternative to OPAQUE. - - We gain additional access control capability by defining both ANY and - OPAQUE values. OPAQUE can be defined to match only fields that are - not accessible. We could define ANY as the complement of OPAQUE, - i.e., it would match all values but only for accessible port fields. - We have therefore simplified the procedure employed to locate the - next layer protocol in this document, so that we treat ESP and AH as - next layer protocols. As a result, the notion of an encrypted next - layer protocol field has vanished, and there is also no need to worry - about encrypted port fields either. And accordingly, OPAQUE will be - applicable only to non-initial fragments. - - Since we have adopted the definitions above for ANY and OPAQUE, we - need to clarify how these values work when the specified protocol - does not have port fields, and when ANY is used for the protocol - selector. Accordingly, if a specific protocol value is used as a - selector, and if that protocol has no port fields, then the port - field selectors are to be ignored and ANY MUST be specified as the - value for the port fields. (In this context, ICMP TYPE and CODE - values are lumped together as a single port field (for IKEv2 - negotiation), as is the IPv6 Mobility Header TYPE value.) If the - protocol selector is ANY, then this should be treated as equivalent - to specifying a protocol for which no port fields are defined, and - thus the port selectors should be ignored, and MUST be set to ANY. - -D.3. The Problem of Non-Initial Fragments - - For an SG implementation, it is obvious that fragments might arrive - from end systems behind the SG. A BITW implementation also may - encounter fragments from a host or gateway behind it. (As noted - earlier, native host implementations and BITS implementations - probably can avoid the problems described below.) In the worst case, - fragments from a packet might arrive at distinct BITW or SG - instantiations and thus preclude reassembly as a solution option. - Hence, in RFC 2401 we adopted a general requirement that fragments - must be accommodated in tunnel mode for all implementations. However, - - - - - -Kent & Seo Standards Track [Page 90] - -RFC 4301 Security Architecture for IP December 2005 - - - RFC 2401 did not provide a perfect solution. The use of OPAQUE as a - selector value for port fields (a SHOULD in RFC 2401) allowed an SA - to carry non-initial fragments. - - Using the features defined in RFC 2401, if one defined an SA between - two IPsec (SG or BITW) implementations using the OPAQUE value for - both port fields, then all non-initial fragments matching the - source/destination (S/D) address and protocol values for the SA would - be mapped to that SA. Initial fragments would NOT map to this SA, if - we adopt a strict definition of OPAQUE. However, RFC 2401 did not - provide detailed guidance on this and thus it may not have been - apparent that use of this feature would essentially create a - "non-initial fragment only" SA. - - In the course of discussing the "fragment-only" SA approach, it was - noted that some subtle problems, problems not considered in RFC 2401, - would have to be avoided. For example, an SA of this sort must be - configured to offer the "highest quality" security services for any - traffic between the indicated S/D addresses (for the specified - protocol). This is necessary to ensure that any traffic captured by - the fragment-only SA is not offered degraded security relative to - what it would have been offered if the packet were not fragmented. A - possible problem here is that we may not be able to identify the - "highest quality" security services defined for use between two IPsec - implementation, since the choice of security protocols, options, and - algorithms is a lattice, not a totally ordered set. (We might safely - say that BYPASS < AH < ESP w/integrity, but it gets complicated if we - have multiple ESP encryption or integrity algorithm options.) So, one - has to impose a total ordering on these security parameters to make - this work, but this can be done locally. - - However, this conservative strategy has a possible performance - downside. If most traffic traversing an IPsec implementation for a - given S/D address pair (and specified protocol) is bypassed, then a - fragment-only SA for that address pair might cause a dramatic - increase in the volume of traffic afforded crypto processing. If the - crypto implementation cannot support high traffic rates, this could - cause problems. (An IPsec implementation that is capable of line rate - or near line rate crypto performance would not be adversely affected - by this SA configuration approach. Nonetheless, the performance - impact is a potential concern, specific to implementation - capabilities.) - - Another concern is that non-initial fragments sent over a dedicated - SA might be used to effect overlapping reassembly attacks, when - combined with an apparently acceptable initial fragment. (This sort - of attack assumes creation of bogus fragments and is not a side - effect of normal fragmentation.) This concern is easily addressed in - - - -Kent & Seo Standards Track [Page 91] - -RFC 4301 Security Architecture for IP December 2005 - - - IPv4, by checking the fragment offset value to ensure that no - non-initial fragments have a small enough offset to overlap port - fields that should be contained in the initial fragment. Recall that - the IPv4 MTU minimum is 576 bytes, and the max IP header length is 60 - bytes, so any ports should be present in the initial fragment. If we - require all non-initial fragments to have an offset of, say, 128 or - greater, just to be on the safe side, this should prevent successful - attacks of this sort. If the intent is only to protect against this - sort of reassembly attack, this check need be implemented only by a - receiver. - - IPv6 also has a fragment offset, carried in the fragmentation - extension header. However, IPv6 extension headers are variable in - length and there is no analogous max header length value that we can - use to check non-initial fragments, to reject ones that might be used - for an attack of the sort noted above. A receiver would need to - maintain state analogous to reassembly state, to provide equivalent - protection. So, only for IPv4 is it feasible to impose a fragment - offset check that would reject attacks designed to circumvent port - field checks by IPsec (or firewalls) when passing non-initial - fragments. - - Another possible concern is that in some topologies and SPD - configurations this approach might result in an access control - surprise. The notion is that if we create an SA to carry ALL - (non-initial) fragments, then that SA would carry some traffic that - might otherwise arrive as plaintext via a separate path, e.g., a path - monitored by a proxy firewall. But, this concern arises only if the - other path allows initial fragments to traverse it without requiring - reassembly, presumably a bad idea for a proxy firewall. Nonetheless, - this does represent a potential problem in some topologies and under - certain assumptions with respect to SPD and (other) firewall rule - sets, and administrators need to be warned of this possibility. - - A less serious concern is that non-initial fragments sent over a - non-initial fragment-only SA might represent a DoS opportunity, in - that they could be sent when no valid, initial fragment will ever - arrive. This might be used to attack hosts behind an SG or BITW - device. However, the incremental risk posed by this sort of attack, - which can be mounted only by hosts behind an SG or BITW device, seems - small. - - If we interpret the ANY selector value as encompassing OPAQUE, then a - single SA with ANY values for both port fields would be able to - accommodate all traffic matching the S/D address and protocol traffic - selectors, an alternative to using the OPAQUE value. But, using ANY - - - - - -Kent & Seo Standards Track [Page 92] - -RFC 4301 Security Architecture for IP December 2005 - - - here precludes multiple, distinct SAs between the same IPsec - implementations for the same address pairs and protocol. So, it is - not an exactly equivalent alternative. - - Fundamentally, fragment handling problems arise only when more than - one SA is defined with the same S/D address and protocol selector - values, but with different port field selector values. - -D.4. BYPASS/DISCARD Traffic - - We also have to address the non-initial fragment processing issue for - BYPASS/DISCARD entries, independent of SA processing. This is - largely a local matter for two reasons: - - 1) We have no means for coordinating SPD entries for such - traffic between IPsec implementations since IKE is not - invoked. - 2) Many of these entries refer to traffic that is NOT - directed to or received from a location that is using - IPsec. So there is no peer IPsec implementation with - which to coordinate via any means. - - However, this document should provide guidance here, consistent with - our goal of offering a well-defined, access control function for all - traffic, relative to the IPsec boundary. To that end, this document - says that implementations MUST support fragment reassembly for - BYPASS/DISCARD traffic when port fields are specified. An - implementation also MUST permit a user or administrator to accept - such traffic or reject such traffic using the SPD conventions - described in Section 4.4.1. The concern is that BYPASS of a - cleartext, non-initial fragment arriving at an IPsec implementation - could undermine the security afforded IPsec-protected traffic - directed to the same destination. For example, consider an IPsec - implementation configured with an SPD entry that calls for - IPsec-protection of traffic between a specific source/destination - address pair, and for a specific protocol and destination port, e.g., - TCP traffic on port 23 (Telnet). Assume that the implementation also - allows BYPASS of traffic from the same source/destination address - pair and protocol, but for a different destination port, e.g., port - 119 (NNTP). An attacker could send a non-initial fragment (with a - forged source address) that, if bypassed, could overlap with - IPsec-protected traffic from the same source and thus violate the - integrity of the IPsec-protected traffic. Requiring stateful - fragment checking for BYPASS entries with non-trivial port ranges - prevents attacks of this sort. - - - - - - -Kent & Seo Standards Track [Page 93] - -RFC 4301 Security Architecture for IP December 2005 - - -D.5. Just say no to ports? - - It has been suggested that we could avoid the problems described - above by not allowing port field selectors to be used in tunnel mode. - But the discussion above shows this to be an unnecessarily stringent - approach, i.e., since no problems arise for the native OS and BITS - implementations. Moreover, some WG members have described scenarios - where use of tunnel mode SAs with (non-trivial) port field selectors - is appropriate. So the challenge is defining a strategy that can - deal with this problem in BITW and SG contexts. Also note that - BYPASS/DISCARD entries in the SPD that make use of ports pose the - same problems, irrespective of tunnel vs. transport mode notions. - - Some folks have suggested that a firewall behind an SG or BITW should - be left to enforce port-level access controls and the effects of - fragmentation. However, this seems to be an incongruous suggestion - in that elsewhere in IPsec (e.g., in IKE payloads) we are concerned - about firewalls that always discard fragments. If many firewalls - don't pass fragments in general, why should we expect them to deal - with fragments in this case? So, this analysis rejects the suggestion - of disallowing use of port field selectors with tunnel mode SAs. - -D.6. Other Suggested Solutions - - One suggestion is to reassemble fragments at the sending IPsec - implementation, and thus avoid the problem entirely. This approach - is invisible to a receiver and thus could be adopted as a purely - local implementation option. - - A more sophisticated version of this suggestion calls for - establishing and maintaining minimal state from each initial fragment - encountered, to allow non-initial fragments to be matched to the - right SAs or SPD/cache entries. This implies an extension to the - current processing model (and the old one). The IPsec implementation - would intercept all fragments; capture Source/Destination IP - addresses, protocol, packet ID, and port fields from initial - fragments; and then use this data to map non-initial fragments to SAs - that require port fields. If this approach is employed, the receiver - needs to employ an equivalent scheme, as it too must verify that - received fragments are consistent with SA selector values. A - non-initial fragment that arrives prior to an initial fragment could - be cached or discarded, awaiting arrival of the corresponding initial - fragment. - - A downside of both approaches noted above is that they will not - always work. When a BITW device or SG is configured in a topology - that might allow some fragments for a packet to be processed at - different SGs or BITW devices, then there is no guarantee that all - - - -Kent & Seo Standards Track [Page 94] - -RFC 4301 Security Architecture for IP December 2005 - - - fragments will ever arrive at the same IPsec device. This approach - also raises possible processing problems. If the sender caches - non-initial fragments until the corresponding initial fragment - arrives, buffering problems might arise, especially at high speeds. - If the non-initial fragments are discarded rather than cached, there - is no guarantee that traffic will ever pass, e.g., retransmission - will result in different packet IDs that cannot be matched with prior - transmissions. In any case, housekeeping procedures will be needed - to decide when to delete the fragment state data, adding some - complexity to the system. Nonetheless, this is a viable solution in - some topologies, and these are likely to be common topologies. - - The Working Group rejected an earlier version of the convention of - creating an SA to carry only non-initial fragments, something that - was supported implicitly under the RFC 2401 model via use of OPAQUE - port fields, but never clearly articulated in RFC 2401. The - (rejected) text called for each non-initial fragment to be treated as - protocol 44 (the IPv6 fragment header protocol ID) by the sender and - receiver. This approach has the potential to make IPv4 and IPv6 - fragment handling more uniform, but it does not fundamentally change - the problem, nor does it address the issue of fragment handling for - BYPASS/DISCARD traffic. Given the fragment overlap attack problem - that IPv6 poses, it does not seem that it is worth the effort to - adopt this strategy. - -D.7. Consistency - - Earlier, the WG agreed to allow an IPsec BITS, BITW, or SG to perform - fragmentation prior to IPsec processing. If this fragmentation is - performed after SA lookup at the sender, there is no "mapping to the - right SA" problem. But, the receiver still needs to be able to - verify that the non-initial fragments are consistent with the SA via - which they are received. Since the initial fragment might be lost en - route, the receiver encounters all of the potential problems noted - above. Thus, if we are to be consistent in our decisions, we need to - say how a receiver will deal with the non-initial fragments that - arrive. - -D.8. Conclusions - - There is no simple, uniform way to handle fragments in all contexts. - Different approaches work better in different contexts. Thus, this - document offers 3 choices -- one MUST and two MAYs. At some point in - the future, if the community gains experience with the two MAYs, they - may become SHOULDs or MUSTs or other approaches may be proposed. - - - - - - -Kent & Seo Standards Track [Page 95] - -RFC 4301 Security Architecture for IP December 2005 - - -Appendix E: Example of Supporting Nested SAs via SPD and Forwarding - Table Entries - - This appendix provides an example of how to configure the SPD and - forwarding tables to support a nested pair of SAs, consistent with - the new processing model. For simplicity, this example assumes just - one SPD-I. - - The goal in this example is to support a transport mode SA from A to - C, carried over a tunnel mode SA from A to B. For example, A might - be a laptop connected to the public Internet, B might be a firewall - that protects a corporate network, and C might be a server on the - corporate network that demands end-to-end authentication of A's - traffic. - - +---+ +---+ +---+ - | A |=====| B | | C | - | |------------| | - | |=====| | | | - +---+ +---+ +---+ - - A's SPD contains entries of the form: - - Next Layer - Rule Local Remote Protocol Action - ---- ----- ------ ---------- ----------------------- - 1 C A ESP BYPASS - 2 A C ICMP,ESP PROTECT(ESP,tunnel,integr+conf) - 3 A C ANY PROTECT(ESP,transport,integr-only) - 4 A B ICMP,IKE BYPASS - - A's unprotected-side forwarding table is set so that outbound packets - destined for C are looped back to the protected side. A's - protected-side forwarding table is set so that inbound ESP packets - are looped back to the unprotected side. A's forwarding tables - contain entries of the form: - - Unprotected-side forwarding table - - Rule Local Remote Protocol Action - ---- ----- ------ -------- --------------------------- - 1 A C ANY loop back to protected side - 2 A B ANY forward to B - - - - - - - - -Kent & Seo Standards Track [Page 96] - -RFC 4301 Security Architecture for IP December 2005 - - - Protected-side forwarding table - - Rule Local Remote Protocol Action - ---- ----- ------ -------- ----------------------------- - 1 A C ESP loop back to unprotected side - - An outbound TCP packet from A to C would match SPD rule 3 and have - transport mode ESP applied to it. The unprotected-side forwarding - table would then loop back the packet. The packet is compared - against SPD-I (see Figure 2), matches SPD rule 1, and so it is - BYPASSed. The packet is treated as an outbound packet and compared - against the SPD for a third time. This time it matches SPD rule 2, - so ESP is applied in tunnel mode. This time the forwarding table - doesn't loop back the packet, because the outer destination address - is B, so the packet goes out onto the wire. - - An inbound TCP packet from C to A is wrapped in two ESP headers; the - outer header (ESP in tunnel mode) shows B as the source, whereas the - inner header (ESP transport mode) shows C as the source. Upon - arrival at A, the packet would be mapped to an SA based on the SPI, - have the outer header removed, and be decrypted and - integrity-checked. Then it would be matched against the SAD - selectors for this SA, which would specify C as the source and A as - the destination, derived from SPD rule 2. The protected-side - forwarding function would then send it back to the unprotected side - based on the addresses and the next layer protocol (ESP), indicative - of nesting. It is compared against SPD-O (see Figure 3) and found to - match SPD rule 1, so it is BYPASSed. The packet is mapped to an SA - based on the SPI, integrity-checked, and compared against the SAD - selectors derived from SPD rule 3. The forwarding function then - passes it up to the next layer, because it isn't an ESP packet. - - - - - - - - - - - - - - - - - - - - -Kent & Seo Standards Track [Page 97] - -RFC 4301 Security Architecture for IP December 2005 - - -References - -Normative References - - [BBCDWW98] Blake, S., Black, D., Carlson, M., Davies, E., Wang, - Z., and W. Weiss, "An Architecture for Differentiated - Service", RFC 2475, December 1998. - - [Bra97] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Level", BCP 14, RFC 2119, March 1997. - - [CD98] Conta, A. and S. Deering, "Internet Control Message - Protocol (ICMPv6) for the Internet Protocol Version 6 - (IPv6) Specification", RFC 2463, December 1998. - - [DH98] Deering, S., and R. Hinden, "Internet Protocol, - Version 6 (IPv6) Specification", RFC 2460, December - 1998. - - [Eas05] 3rd Eastlake, D., "Cryptographic Algorithm - Implementation Requirements For Encapsulating Security - Payload (ESP) and Authentication Header (AH)", RFC - 4305, December 2005. - - [HarCar98] Harkins, D. and D. Carrel, "The Internet Key Exchange - (IKE)", RFC 2409, November 1998. - - [Kau05] Kaufman, C., Ed., "The Internet Key Exchange (IKEv2) - Protocol", RFC 4306, December 2005. - - [Ken05a] Kent, S., "IP Encapsulating Security Payload (ESP)", - RFC 4303, December 2005. - - [Ken05b] Kent, S., "IP Authentication Header", RFC 4302, - December 2005. - - [MD90] Mogul, J. and S. Deering, "Path MTU discovery", RFC - 1191, November 1990. - - [Mobip] Johnson, D., Perkins, C., and J. Arkko, "Mobility - Support in IPv6", RFC 3775, June 2004. - - [Pos81a] Postel, J., "Internet Protocol", STD 5, RFC 791, - September 1981. - - [Pos81b] Postel, J., "Internet Control Message Protocol", RFC - 792, September 1981. - - - - -Kent & Seo Standards Track [Page 98] - -RFC 4301 Security Architecture for IP December 2005 - - - [Sch05] Schiller, J., "Cryptographic Algorithms for use in the - Internet Key Exchange Version 2 (IKEv2)", RFC 4307, - December 2005. - - [WaKiHo97] Wahl, M., Kille, S., and T. Howes, "Lightweight - Directory Access Protocol (v3): UTF-8 String - Representation of Distinguished Names", RFC 2253, - December 1997. - -Informative References - - [CoSa04] Condell, M., and L. Sanchez, "On the Deterministic - Enforcement of Un-ordered Security Policies", BBN - Technical Memo 1346, March 2004. - - [FaLiHaMeTr00] Farinacci, D., Li, T., Hanks, S., Meyer, D., and P. - Traina, "Generic Routing Encapsulation (GRE)", RFC - 2784, March 2000. - - [Gro02] Grossman, D., "New Terminology and Clarifications for - Diffserv", RFC 3260, April 2002. - [HC03] Holbrook, H. and B. Cain, "Source Specific Multicast - for IP", Work in Progress, November 3, 2002. - - [HA94] Haller, N. and R. Atkinson, "On Internet - Authentication", RFC 1704, October 1994. - - [NiBlBaBL98] Nichols, K., Blake, S., Baker, F., and D. Black, - "Definition of the Differentiated Services Field (DS - Field) in the IPv4 and IPv6 Headers", RFC 2474, - December 1998. - - [Per96] Perkins, C., "IP Encapsulation within IP", RFC 2003, - October 1996. - - [RaFlBl01] Ramakrishnan, K., Floyd, S., and D. Black, "The - Addition of Explicit Congestion Notification (ECN) to - IP", RFC 3168, September 2001. - - [RFC2401] Kent, S. and R. Atkinson, "Security Architecture for - the Internet Protocol", RFC 2401, November 1998. - - [RFC2983] Black, D., "Differentiated Services and Tunnels", RFC - 2983, October 2000. - - [RFC3547] Baugher, M., Weis, B., Hardjono, T., and H. Harney, - "The Group Domain of Interpretation", RFC 3547, July - 2003. - - - -Kent & Seo Standards Track [Page 99] - -RFC 4301 Security Architecture for IP December 2005 - - - [RFC3740] Hardjono, T. and B. Weis, "The Multicast Group - Security Architecture", RFC 3740, March 2004. - - [RaCoCaDe04] Rajahalme, J., Conta, A., Carpenter, B., and S. - Deering, "IPv6 Flow Label Specification", RFC 3697, - March 2004. - - [Sch94] Schneier, B., Applied Cryptography, Section 8.6, John - Wiley & Sons, New York, NY, 1994. - - [Shi00] Shirey, R., "Internet Security Glossary", RFC 2828, - May 2000. - - [SMPT01] Shacham, A., Monsour, B., Pereira, R., and M. Thomas, - "IP Payload Compression Protocol (IPComp)", RFC 3173, - September 2001. - - [ToEgWa04] Touch, J., Eggert, L., and Y. Wang, "Use of IPsec - Transport Mode for Dynamic Routing", RFC 3884, - September 2004. - - [VK83] V.L. Voydock & S.T. Kent, "Security Mechanisms in - High-level Networks", ACM Computing Surveys, Vol. 15, - No. 2, June 1983. - -Authors' Addresses - - Stephen Kent - BBN Technologies - 10 Moulton Street - Cambridge, MA 02138 - USA - - Phone: +1 (617) 873-3988 - EMail: kent@bbn.com - - - Karen Seo - BBN Technologies - 10 Moulton Street - Cambridge, MA 02138 - USA - - Phone: +1 (617) 873-3152 - EMail: kseo@bbn.com - - - - - - -Kent & Seo Standards Track [Page 100] - -RFC 4301 Security Architecture for IP December 2005 - - -Full Copyright Statement - - Copyright (C) The Internet Society (2005). - - This document is subject to the rights, licenses and restrictions - contained in BCP 78, and except as set forth therein, the authors - retain all their rights. - - This document and the information contained herein are provided on an - "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS - OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET - ENGINEERING TASK FORCE DISCLAIM 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. - -Intellectual Property - - The IETF takes no position regarding the validity or scope of any - Intellectual Property Rights or other rights that might be claimed to - pertain to the implementation or use of the technology described in - this document or the extent to which any license under such rights - might or might not be available; nor does it represent that it has - made any independent effort to identify any such rights. Information - on the procedures with respect to rights in RFC documents can be - found in BCP 78 and BCP 79. - - Copies of IPR disclosures made to the IETF Secretariat and any - assurances of licenses to be made available, or the result of an - attempt made to obtain a general license or permission for the use of - such proprietary rights by implementers or users of this - specification can be obtained from the IETF on-line IPR repository at - http://www.ietf.org/ipr. - - The IETF invites any interested party to bring to its attention any - copyrights, patents or patent applications, or other proprietary - rights that may cover technology that may be required to implement - this standard. Please address the information to the IETF at ietf- - ipr@ietf.org. - -Acknowledgement - - Funding for the RFC Editor function is currently provided by the - Internet Society. - - - - - - - -Kent & Seo Standards Track [Page 101] - diff --git a/src/charon/doc/standards/rfc4306.txt b/src/charon/doc/standards/rfc4306.txt deleted file mode 100644 index fad6cea0e..000000000 --- a/src/charon/doc/standards/rfc4306.txt +++ /dev/null @@ -1,5547 +0,0 @@ - - - - - - -Network Working Group C. Kaufman, Ed. -Request for Comments: 4306 Microsoft -Obsoletes: 2407, 2408, 2409 December 2005 -Category: Standards Track - - - Internet Key Exchange (IKEv2) Protocol - -Status of This Memo - - This document specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" (STD 1) for the standardization state - and status of this protocol. Distribution of this memo is unlimited. - -Copyright Notice - - Copyright (C) The Internet Society (2005). - -Abstract - - This document describes version 2 of the Internet Key Exchange (IKE) - protocol. IKE is a component of IPsec used for performing mutual - authentication and establishing and maintaining security associations - (SAs). - - This version of the IKE specification combines the contents of what - were previously separate documents, including Internet Security - Association and Key Management Protocol (ISAKMP, RFC 2408), IKE (RFC - 2409), the Internet Domain of Interpretation (DOI, RFC 2407), Network - Address Translation (NAT) Traversal, Legacy authentication, and - remote address acquisition. - - Version 2 of IKE does not interoperate with version 1, but it has - enough of the header format in common that both versions can - unambiguously run over the same UDP port. - - - - - - - - - - - - - - -Kaufman Standards Track [Page 1] - -RFC 4306 IKEv2 December 2005 - - -Table of Contents - - 1. Introduction ....................................................3 - 1.1. Usage Scenarios ............................................5 - 1.2. The Initial Exchanges ......................................7 - 1.3. The CREATE_CHILD_SA Exchange ...............................9 - 1.4. The INFORMATIONAL Exchange ................................11 - 1.5. Informational Messages outside of an IKE_SA ...............12 - 2. IKE Protocol Details and Variations ............................12 - 2.1. Use of Retransmission Timers ..............................13 - 2.2. Use of Sequence Numbers for Message ID ....................14 - 2.3. Window Size for Overlapping Requests ......................14 - 2.4. State Synchronization and Connection Timeouts .............15 - 2.5. Version Numbers and Forward Compatibility .................17 - 2.6. Cookies ...................................................18 - 2.7. Cryptographic Algorithm Negotiation .......................21 - 2.8. Rekeying ..................................................22 - 2.9. Traffic Selector Negotiation ..............................24 - 2.10. Nonces ...................................................26 - 2.11. Address and Port Agility .................................26 - 2.12. Reuse of Diffie-Hellman Exponentials .....................27 - 2.13. Generating Keying Material ...............................27 - 2.14. Generating Keying Material for the IKE_SA ................28 - 2.15. Authentication of the IKE_SA .............................29 - 2.16. Extensible Authentication Protocol Methods ...............31 - 2.17. Generating Keying Material for CHILD_SAs .................33 - 2.18. Rekeying IKE_SAs Using a CREATE_CHILD_SA exchange ........34 - 2.19. Requesting an Internal Address on a Remote Network .......34 - 2.20. Requesting the Peer's Version ............................35 - 2.21. Error Handling ...........................................36 - 2.22. IPComp ...................................................37 - 2.23. NAT Traversal ............................................38 - 2.24. Explicit Congestion Notification (ECN) ...................40 - 3. Header and Payload Formats .....................................41 - 3.1. The IKE Header ............................................41 - 3.2. Generic Payload Header ....................................44 - 3.3. Security Association Payload ..............................46 - 3.4. Key Exchange Payload ......................................56 - 3.5. Identification Payloads ...................................56 - 3.6. Certificate Payload .......................................59 - 3.7. Certificate Request Payload ...............................61 - 3.8. Authentication Payload ....................................63 - 3.9. Nonce Payload .............................................64 - 3.10. Notify Payload ...........................................64 - 3.11. Delete Payload ...........................................72 - 3.12. Vendor ID Payload ........................................73 - 3.13. Traffic Selector Payload .................................74 - 3.14. Encrypted Payload ........................................77 - - - -Kaufman Standards Track [Page 2] - -RFC 4306 IKEv2 December 2005 - - - 3.15. Configuration Payload ....................................79 - 3.16. Extensible Authentication Protocol (EAP) Payload .........84 - 4. Conformance Requirements .......................................85 - 5. Security Considerations ........................................88 - 6. IANA Considerations ............................................90 - 7. Acknowledgements ...............................................91 - 8. References .....................................................91 - 8.1. Normative References ......................................91 - 8.2. Informative References ....................................92 - Appendix A: Summary of Changes from IKEv1 .........................96 - Appendix B: Diffie-Hellman Groups .................................97 - B.1. Group 1 - 768 Bit MODP ....................................97 - B.2. Group 2 - 1024 Bit MODP ...................................97 - -1. Introduction - - IP Security (IPsec) provides confidentiality, data integrity, access - control, and data source authentication to IP datagrams. These - services are provided by maintaining shared state between the source - and the sink of an IP datagram. This state defines, among other - things, the specific services provided to the datagram, which - cryptographic algorithms will be used to provide the services, and - the keys used as input to the cryptographic algorithms. - - Establishing this shared state in a manual fashion does not scale - well. Therefore, a protocol to establish this state dynamically is - needed. This memo describes such a protocol -- the Internet Key - Exchange (IKE). This is version 2 of IKE. Version 1 of IKE was - defined in RFCs 2407, 2408, and 2409 [Pip98, MSST98, HC98]. This - single document is intended to replace all three of those RFCs. - - Definitions of the primitive terms in this document (such as Security - Association or SA) can be found in [RFC4301]. - - Keywords "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT" and - "MAY" that appear in this document are to be interpreted as described - in [Bra97]. - - The term "Expert Review" is to be interpreted as defined in - [RFC2434]. - - IKE performs mutual authentication between two parties and - establishes an IKE security association (SA) that includes shared - secret information that can be used to efficiently establish SAs for - Encapsulating Security Payload (ESP) [RFC4303] and/or Authentication - Header (AH) [RFC4302] and a set of cryptographic algorithms to be - used by the SAs to protect the traffic that they carry. In this - document, the term "suite" or "cryptographic suite" refers to a - - - -Kaufman Standards Track [Page 3] - -RFC 4306 IKEv2 December 2005 - - - complete set of algorithms used to protect an SA. An initiator - proposes one or more suites by listing supported algorithms that can - be combined into suites in a mix-and-match fashion. IKE can also - negotiate use of IP Compression (IPComp) [IPCOMP] in connection with - an ESP and/or AH SA. We call the IKE SA an "IKE_SA". The SAs for - ESP and/or AH that get set up through that IKE_SA we call - "CHILD_SAs". - - All IKE communications consist of pairs of messages: a request and a - response. The pair is called an "exchange". We call the first - messages establishing an IKE_SA IKE_SA_INIT and IKE_AUTH exchanges - and subsequent IKE exchanges CREATE_CHILD_SA or INFORMATIONAL - exchanges. In the common case, there is a single IKE_SA_INIT - exchange and a single IKE_AUTH exchange (a total of four messages) to - establish the IKE_SA and the first CHILD_SA. In exceptional cases, - there may be more than one of each of these exchanges. In all cases, - all IKE_SA_INIT exchanges MUST complete before any other exchange - type, then all IKE_AUTH exchanges MUST complete, and following that - any number of CREATE_CHILD_SA and INFORMATIONAL exchanges may occur - in any order. In some scenarios, only a single CHILD_SA is needed - between the IPsec endpoints, and therefore there would be no - additional exchanges. Subsequent exchanges MAY be used to establish - additional CHILD_SAs between the same authenticated pair of endpoints - and to perform housekeeping functions. - - IKE message flow always consists of a request followed by a response. - It is the responsibility of the requester to ensure reliability. If - the response is not received within a timeout interval, the requester - needs to retransmit the request (or abandon the connection). - - The first request/response of an IKE session (IKE_SA_INIT) negotiates - security parameters for the IKE_SA, sends nonces, and sends Diffie- - Hellman values. - - The second request/response (IKE_AUTH) transmits identities, proves - knowledge of the secrets corresponding to the two identities, and - sets up an SA for the first (and often only) AH and/or ESP CHILD_SA. - - The types of subsequent exchanges are CREATE_CHILD_SA (which creates - a CHILD_SA) and INFORMATIONAL (which deletes an SA, reports error - conditions, or does other housekeeping). Every request requires a - response. An INFORMATIONAL request with no payloads (other than the - empty Encrypted payload required by the syntax) is commonly used as a - check for liveness. These subsequent exchanges cannot be used until - the initial exchanges have completed. - - - - - - -Kaufman Standards Track [Page 4] - -RFC 4306 IKEv2 December 2005 - - - In the description that follows, we assume that no errors occur. - Modifications to the flow should errors occur are described in - section 2.21. - -1.1. Usage Scenarios - - IKE is expected to be used to negotiate ESP and/or AH SAs in a number - of different scenarios, each with its own special requirements. - -1.1.1. Security Gateway to Security Gateway Tunnel - - +-+-+-+-+-+ +-+-+-+-+-+ - ! ! IPsec ! ! - Protected !Tunnel ! tunnel !Tunnel ! Protected - Subnet <-->!Endpoint !<---------->!Endpoint !<--> Subnet - ! ! ! ! - +-+-+-+-+-+ +-+-+-+-+-+ - - Figure 1: Security Gateway to Security Gateway Tunnel - - In this scenario, neither endpoint of the IP connection implements - IPsec, but network nodes between them protect traffic for part of the - way. Protection is transparent to the endpoints, and depends on - ordinary routing to send packets through the tunnel endpoints for - processing. Each endpoint would announce the set of addresses - "behind" it, and packets would be sent in tunnel mode where the inner - IP header would contain the IP addresses of the actual endpoints. - -1.1.2. Endpoint-to-Endpoint Transport - - +-+-+-+-+-+ +-+-+-+-+-+ - ! ! IPsec transport ! ! - !Protected! or tunnel mode SA !Protected! - !Endpoint !<---------------------------------------->!Endpoint ! - ! ! ! ! - +-+-+-+-+-+ +-+-+-+-+-+ - - Figure 2: Endpoint to Endpoint - - In this scenario, both endpoints of the IP connection implement - IPsec, as required of hosts in [RFC4301]. Transport mode will - commonly be used with no inner IP header. If there is an inner IP - header, the inner addresses will be the same as the outer addresses. - A single pair of addresses will be negotiated for packets to be - protected by this SA. These endpoints MAY implement application - layer access controls based on the IPsec authenticated identities of - the participants. This scenario enables the end-to-end security that - has been a guiding principle for the Internet since [RFC1958], - - - -Kaufman Standards Track [Page 5] - -RFC 4306 IKEv2 December 2005 - - - [RFC2775], and a method of limiting the inherent problems with - complexity in networks noted by [RFC3439]. Although this scenario - may not be fully applicable to the IPv4 Internet, it has been - deployed successfully in specific scenarios within intranets using - IKEv1. It should be more broadly enabled during the transition to - IPv6 and with the adoption of IKEv2. - - It is possible in this scenario that one or both of the protected - endpoints will be behind a network address translation (NAT) node, in - which case the tunneled packets will have to be UDP encapsulated so - that port numbers in the UDP headers can be used to identify - individual endpoints "behind" the NAT (see section 2.23). - -1.1.3. Endpoint to Security Gateway Tunnel - - +-+-+-+-+-+ +-+-+-+-+-+ - ! ! IPsec ! ! Protected - !Protected! tunnel !Tunnel ! Subnet - !Endpoint !<------------------------>!Endpoint !<--- and/or - ! ! ! ! Internet - +-+-+-+-+-+ +-+-+-+-+-+ - - Figure 3: Endpoint to Security Gateway Tunnel - - In this scenario, a protected endpoint (typically a portable roaming - computer) connects back to its corporate network through an IPsec- - protected tunnel. It might use this tunnel only to access - information on the corporate network, or it might tunnel all of its - traffic back through the corporate network in order to take advantage - of protection provided by a corporate firewall against Internet-based - attacks. In either case, the protected endpoint will want an IP - address associated with the security gateway so that packets returned - to it will go to the security gateway and be tunneled back. This IP - address may be static or may be dynamically allocated by the security - gateway. In support of the latter case, IKEv2 includes a mechanism - for the initiator to request an IP address owned by the security - gateway for use for the duration of its SA. - - In this scenario, packets will use tunnel mode. On each packet from - the protected endpoint, the outer IP header will contain the source - IP address associated with its current location (i.e., the address - that will get traffic routed to the endpoint directly), while the - inner IP header will contain the source IP address assigned by the - security gateway (i.e., the address that will get traffic routed to - the security gateway for forwarding to the endpoint). The outer - destination address will always be that of the security gateway, - while the inner destination address will be the ultimate destination - for the packet. - - - -Kaufman Standards Track [Page 6] - -RFC 4306 IKEv2 December 2005 - - - In this scenario, it is possible that the protected endpoint will be - behind a NAT. In that case, the IP address as seen by the security - gateway will not be the same as the IP address sent by the protected - endpoint, and packets will have to be UDP encapsulated in order to be - routed properly. - -1.1.4. Other Scenarios - - Other scenarios are possible, as are nested combinations of the - above. One notable example combines aspects of 1.1.1 and 1.1.3. A - subnet may make all external accesses through a remote security - gateway using an IPsec tunnel, where the addresses on the subnet are - routed to the security gateway by the rest of the Internet. An - example would be someone's home network being virtually on the - Internet with static IP addresses even though connectivity is - provided by an ISP that assigns a single dynamically assigned IP - address to the user's security gateway (where the static IP addresses - and an IPsec relay are provided by a third party located elsewhere). - -1.2. The Initial Exchanges - - Communication using IKE always begins with IKE_SA_INIT and IKE_AUTH - exchanges (known in IKEv1 as Phase 1). These initial exchanges - normally consist of four messages, though in some scenarios that - number can grow. All communications using IKE consist of - request/response pairs. We'll describe the base exchange first, - followed by variations. The first pair of messages (IKE_SA_INIT) - negotiate cryptographic algorithms, exchange nonces, and do a - Diffie-Hellman exchange [DH]. - - The second pair of messages (IKE_AUTH) authenticate the previous - messages, exchange identities and certificates, and establish the - first CHILD_SA. Parts of these messages are encrypted and integrity - protected with keys established through the IKE_SA_INIT exchange, so - the identities are hidden from eavesdroppers and all fields in all - the messages are authenticated. - - In the following descriptions, the payloads contained in the message - are indicated by names as listed below. - - Notation Payload - - AUTH Authentication - CERT Certificate - CERTREQ Certificate Request - CP Configuration - D Delete - E Encrypted - - - -Kaufman Standards Track [Page 7] - -RFC 4306 IKEv2 December 2005 - - - EAP Extensible Authentication - HDR IKE Header - IDi Identification - Initiator - IDr Identification - Responder - KE Key Exchange - Ni, Nr Nonce - N Notify - SA Security Association - TSi Traffic Selector - Initiator - TSr Traffic Selector - Responder - V Vendor ID - - The details of the contents of each payload are described in section - 3. Payloads that may optionally appear will be shown in brackets, - such as [CERTREQ], indicate that optionally a certificate request - payload can be included. - - The initial exchanges are as follows: - - Initiator Responder - ----------- ----------- - HDR, SAi1, KEi, Ni --> - - HDR contains the Security Parameter Indexes (SPIs), version numbers, - and flags of various sorts. The SAi1 payload states the - cryptographic algorithms the initiator supports for the IKE_SA. The - KE payload sends the initiator's Diffie-Hellman value. Ni is the - initiator's nonce. - - <-- HDR, SAr1, KEr, Nr, [CERTREQ] - - The responder chooses a cryptographic suite from the initiator's - offered choices and expresses that choice in the SAr1 payload, - completes the Diffie-Hellman exchange with the KEr payload, and sends - its nonce in the Nr payload. - - At this point in the negotiation, each party can generate SKEYSEED, - from which all keys are derived for that IKE_SA. All but the headers - of all the messages that follow are encrypted and integrity - protected. The keys used for the encryption and integrity protection - are derived from SKEYSEED and are known as SK_e (encryption) and SK_a - (authentication, a.k.a. integrity protection). A separate SK_e and - SK_a is computed for each direction. In addition to the keys SK_e - and SK_a derived from the DH value for protection of the IKE_SA, - another quantity SK_d is derived and used for derivation of further - keying material for CHILD_SAs. The notation SK { ... } indicates - that these payloads are encrypted and integrity protected using that - direction's SK_e and SK_a. - - - -Kaufman Standards Track [Page 8] - -RFC 4306 IKEv2 December 2005 - - - HDR, SK {IDi, [CERT,] [CERTREQ,] [IDr,] - AUTH, SAi2, TSi, TSr} --> - - The initiator asserts its identity with the IDi payload, proves - knowledge of the secret corresponding to IDi and integrity protects - the contents of the first message using the AUTH payload (see section - 2.15). It might also send its certificate(s) in CERT payload(s) and - a list of its trust anchors in CERTREQ payload(s). If any CERT - payloads are included, the first certificate provided MUST contain - the public key used to verify the AUTH field. The optional payload - IDr enables the initiator to specify which of the responder's - identities it wants to talk to. This is useful when the machine on - which the responder is running is hosting multiple identities at the - same IP address. The initiator begins negotiation of a CHILD_SA - using the SAi2 payload. The final fields (starting with SAi2) are - described in the description of the CREATE_CHILD_SA exchange. - - <-- HDR, SK {IDr, [CERT,] AUTH, - SAr2, TSi, TSr} - - The responder asserts its identity with the IDr payload, optionally - sends one or more certificates (again with the certificate containing - the public key used to verify AUTH listed first), authenticates its - identity and protects the integrity of the second message with the - AUTH payload, and completes negotiation of a CHILD_SA with the - additional fields described below in the CREATE_CHILD_SA exchange. - - The recipients of messages 3 and 4 MUST verify that all signatures - and MACs are computed correctly and that the names in the ID payloads - correspond to the keys used to generate the AUTH payload. - -1.3. The CREATE_CHILD_SA Exchange - - This exchange consists of a single request/response pair, and was - referred to as a phase 2 exchange in IKEv1. It MAY be initiated by - either end of the IKE_SA after the initial exchanges are completed. - - All messages following the initial exchange are cryptographically - protected using the cryptographic algorithms and keys negotiated in - the first two messages of the IKE exchange. These subsequent - messages use the syntax of the Encrypted Payload described in section - 3.14. All subsequent messages included an Encrypted Payload, even if - they are referred to in the text as "empty". - - Either endpoint may initiate a CREATE_CHILD_SA exchange, so in this - section the term "initiator" refers to the endpoint initiating this - exchange. - - - - -Kaufman Standards Track [Page 9] - -RFC 4306 IKEv2 December 2005 - - - A CHILD_SA is created by sending a CREATE_CHILD_SA request. The - CREATE_CHILD_SA request MAY optionally contain a KE payload for an - additional Diffie-Hellman exchange to enable stronger guarantees of - forward secrecy for the CHILD_SA. The keying material for the - CHILD_SA is a function of SK_d established during the establishment - of the IKE_SA, the nonces exchanged during the CREATE_CHILD_SA - exchange, and the Diffie-Hellman value (if KE payloads are included - in the CREATE_CHILD_SA exchange). - - In the CHILD_SA created as part of the initial exchange, a second KE - payload and nonce MUST NOT be sent. The nonces from the initial - exchange are used in computing the keys for the CHILD_SA. - - The CREATE_CHILD_SA request contains: - - Initiator Responder - ----------- ----------- - HDR, SK {[N], SA, Ni, [KEi], - [TSi, TSr]} --> - - The initiator sends SA offer(s) in the SA payload, a nonce in the Ni - payload, optionally a Diffie-Hellman value in the KEi payload, and - the proposed traffic selectors in the TSi and TSr payloads. If this - CREATE_CHILD_SA exchange is rekeying an existing SA other than the - IKE_SA, the leading N payload of type REKEY_SA MUST identify the SA - being rekeyed. If this CREATE_CHILD_SA exchange is not rekeying an - existing SA, the N payload MUST be omitted. If the SA offers include - different Diffie-Hellman groups, KEi MUST be an element of the group - the initiator expects the responder to accept. If it guesses wrong, - the CREATE_CHILD_SA exchange will fail, and it will have to retry - with a different KEi. - - The message following the header is encrypted and the message - including the header is integrity protected using the cryptographic - algorithms negotiated for the IKE_SA. - - The CREATE_CHILD_SA response contains: - - <-- HDR, SK {SA, Nr, [KEr], - [TSi, TSr]} - - The responder replies (using the same Message ID to respond) with the - accepted offer in an SA payload, and a Diffie-Hellman value in the - KEr payload if KEi was included in the request and the selected - cryptographic suite includes that group. If the responder chooses a - cryptographic suite with a different group, it MUST reject the - request. The initiator SHOULD repeat the request, but now with a KEi - payload from the group the responder selected. - - - -Kaufman Standards Track [Page 10] - -RFC 4306 IKEv2 December 2005 - - - The traffic selectors for traffic to be sent on that SA are specified - in the TS payloads, which may be a subset of what the initiator of - the CHILD_SA proposed. Traffic selectors are omitted if this - CREATE_CHILD_SA request is being used to change the key of the - IKE_SA. - -1.4. The INFORMATIONAL Exchange - - At various points during the operation of an IKE_SA, peers may desire - to convey control messages to each other regarding errors or - notifications of certain events. To accomplish this, IKE defines an - INFORMATIONAL exchange. INFORMATIONAL exchanges MUST ONLY occur - after the initial exchanges and are cryptographically protected with - the negotiated keys. - - Control messages that pertain to an IKE_SA MUST be sent under that - IKE_SA. Control messages that pertain to CHILD_SAs MUST be sent - under the protection of the IKE_SA which generated them (or its - successor if the IKE_SA was replaced for the purpose of rekeying). - - Messages in an INFORMATIONAL exchange contain zero or more - Notification, Delete, and Configuration payloads. The Recipient of - an INFORMATIONAL exchange request MUST send some response (else the - Sender will assume the message was lost in the network and will - retransmit it). That response MAY be a message with no payloads. - The request message in an INFORMATIONAL exchange MAY also contain no - payloads. This is the expected way an endpoint can ask the other - endpoint to verify that it is alive. - - ESP and AH SAs always exist in pairs, with one SA in each direction. - When an SA is closed, both members of the pair MUST be closed. When - SAs are nested, as when data (and IP headers if in tunnel mode) are - encapsulated first with IPComp, then with ESP, and finally with AH - between the same pair of endpoints, all of the SAs MUST be deleted - together. Each endpoint MUST close its incoming SAs and allow the - other endpoint to close the other SA in each pair. To delete an SA, - an INFORMATIONAL exchange with one or more delete payloads is sent - listing the SPIs (as they would be expected in the headers of inbound - packets) of the SAs to be deleted. The recipient MUST close the - designated SAs. Normally, the reply in the INFORMATIONAL exchange - will contain delete payloads for the paired SAs going in the other - direction. There is one exception. If by chance both ends of a set - of SAs independently decide to close them, each may send a delete - payload and the two requests may cross in the network. If a node - receives a delete request for SAs for which it has already issued a - delete request, it MUST delete the outgoing SAs while processing the - request and the incoming SAs while processing the response. In that - - - - -Kaufman Standards Track [Page 11] - -RFC 4306 IKEv2 December 2005 - - - case, the responses MUST NOT include delete payloads for the deleted - SAs, since that would result in duplicate deletion and could in - theory delete the wrong SA. - - A node SHOULD regard half-closed connections as anomalous and audit - their existence should they persist. Note that this specification - nowhere specifies time periods, so it is up to individual endpoints - to decide how long to wait. A node MAY refuse to accept incoming - data on half-closed connections but MUST NOT unilaterally close them - and reuse the SPIs. If connection state becomes sufficiently messed - up, a node MAY close the IKE_SA; doing so will implicitly close all - SAs negotiated under it. It can then rebuild the SAs it needs on a - clean base under a new IKE_SA. - - The INFORMATIONAL exchange is defined as: - - Initiator Responder - ----------- ----------- - HDR, SK {[N,] [D,] [CP,] ...} --> - <-- HDR, SK {[N,] [D,] [CP], ...} - - The processing of an INFORMATIONAL exchange is determined by its - component payloads. - -1.5. Informational Messages outside of an IKE_SA - - If an encrypted IKE packet arrives on port 500 or 4500 with an - unrecognized SPI, it could be because the receiving node has recently - crashed and lost state or because of some other system malfunction or - attack. If the receiving node has an active IKE_SA to the IP address - from whence the packet came, it MAY send a notification of the - wayward packet over that IKE_SA in an INFORMATIONAL exchange. If it - does not have such an IKE_SA, it MAY send an Informational message - without cryptographic protection to the source IP address. Such a - message is not part of an informational exchange, and the receiving - node MUST NOT respond to it. Doing so could cause a message loop. - -2. IKE Protocol Details and Variations - - IKE normally listens and sends on UDP port 500, though IKE messages - may also be received on UDP port 4500 with a slightly different - format (see section 2.23). Since UDP is a datagram (unreliable) - protocol, IKE includes in its definition recovery from transmission - errors, including packet loss, packet replay, and packet forgery. - IKE is designed to function so long as (1) at least one of a series - of retransmitted packets reaches its destination before timing out; - and (2) the channel is not so full of forged and replayed packets so - - - - -Kaufman Standards Track [Page 12] - -RFC 4306 IKEv2 December 2005 - - - as to exhaust the network or CPU capacities of either endpoint. Even - in the absence of those minimum performance requirements, IKE is - designed to fail cleanly (as though the network were broken). - - Although IKEv2 messages are intended to be short, they contain - structures with no hard upper bound on size (in particular, X.509 - certificates), and IKEv2 itself does not have a mechanism for - fragmenting large messages. IP defines a mechanism for fragmentation - of oversize UDP messages, but implementations vary in the maximum - message size supported. Furthermore, use of IP fragmentation opens - an implementation to denial of service attacks [KPS03]. Finally, - some NAT and/or firewall implementations may block IP fragments. - - All IKEv2 implementations MUST be able to send, receive, and process - IKE messages that are up to 1280 bytes long, and they SHOULD be able - to send, receive, and process messages that are up to 3000 bytes - long. IKEv2 implementations SHOULD be aware of the maximum UDP - message size supported and MAY shorten messages by leaving out some - certificates or cryptographic suite proposals if that will keep - messages below the maximum. Use of the "Hash and URL" formats rather - than including certificates in exchanges where possible can avoid - most problems. Implementations and configuration should keep in - mind, however, that if the URL lookups are possible only after the - IPsec SA is established, recursion issues could prevent this - technique from working. - -2.1. Use of Retransmission Timers - - All messages in IKE exist in pairs: a request and a response. The - setup of an IKE_SA normally consists of two request/response pairs. - Once the IKE_SA is set up, either end of the security association may - initiate requests at any time, and there can be many requests and - responses "in flight" at any given moment. But each message is - labeled as either a request or a response, and for each - request/response pair one end of the security association is the - initiator and the other is the responder. - - For every pair of IKE messages, the initiator is responsible for - retransmission in the event of a timeout. The responder MUST never - retransmit a response unless it receives a retransmission of the - request. In that event, the responder MUST ignore the retransmitted - request except insofar as it triggers a retransmission of the - response. The initiator MUST remember each request until it receives - the corresponding response. The responder MUST remember each - response until it receives a request whose sequence number is larger - than the sequence number in the response plus its window size (see - section 2.3). - - - - -Kaufman Standards Track [Page 13] - -RFC 4306 IKEv2 December 2005 - - - IKE is a reliable protocol, in the sense that the initiator MUST - retransmit a request until either it receives a corresponding reply - OR it deems the IKE security association to have failed and it - discards all state associated with the IKE_SA and any CHILD_SAs - negotiated using that IKE_SA. - -2.2. Use of Sequence Numbers for Message ID - - Every IKE message contains a Message ID as part of its fixed header. - This Message ID is used to match up requests and responses, and to - identify retransmissions of messages. - - The Message ID is a 32-bit quantity, which is zero for the first IKE - request in each direction. The IKE_SA initial setup messages will - always be numbered 0 and 1. Each endpoint in the IKE Security - Association maintains two "current" Message IDs: the next one to be - used for a request it initiates and the next one it expects to see in - a request from the other end. These counters increment as requests - are generated and received. Responses always contain the same - message ID as the corresponding request. That means that after the - initial exchange, each integer n may appear as the message ID in four - distinct messages: the nth request from the original IKE initiator, - the corresponding response, the nth request from the original IKE - responder, and the corresponding response. If the two ends make very - different numbers of requests, the Message IDs in the two directions - can be very different. There is no ambiguity in the messages, - however, because the (I)nitiator and (R)esponse bits in the message - header specify which of the four messages a particular one is. - - Note that Message IDs are cryptographically protected and provide - protection against message replays. In the unlikely event that - Message IDs grow too large to fit in 32 bits, the IKE_SA MUST be - closed. Rekeying an IKE_SA resets the sequence numbers. - -2.3. Window Size for Overlapping Requests - - In order to maximize IKE throughput, an IKE endpoint MAY issue - multiple requests before getting a response to any of them if the - other endpoint has indicated its ability to handle such requests. - For simplicity, an IKE implementation MAY choose to process requests - strictly in order and/or wait for a response to one request before - issuing another. Certain rules must be followed to ensure - interoperability between implementations using different strategies. - - After an IKE_SA is set up, either end can initiate one or more - requests. These requests may pass one another over the network. An - IKE endpoint MUST be prepared to accept and process a request while - - - - -Kaufman Standards Track [Page 14] - -RFC 4306 IKEv2 December 2005 - - - it has a request outstanding in order to avoid a deadlock in this - situation. An IKE endpoint SHOULD be prepared to accept and process - multiple requests while it has a request outstanding. - - An IKE endpoint MUST wait for a response to each of its messages - before sending a subsequent message unless it has received a - SET_WINDOW_SIZE Notify message from its peer informing it that the - peer is prepared to maintain state for multiple outstanding messages - in order to allow greater throughput. - - An IKE endpoint MUST NOT exceed the peer's stated window size for - transmitted IKE requests. In other words, if the responder stated - its window size is N, then when the initiator needs to make a request - X, it MUST wait until it has received responses to all requests up - through request X-N. An IKE endpoint MUST keep a copy of (or be able - to regenerate exactly) each request it has sent until it receives the - corresponding response. An IKE endpoint MUST keep a copy of (or be - able to regenerate exactly) the number of previous responses equal to - its declared window size in case its response was lost and the - initiator requests its retransmission by retransmitting the request. - - An IKE endpoint supporting a window size greater than one SHOULD be - capable of processing incoming requests out of order to maximize - performance in the event of network failures or packet reordering. - -2.4. State Synchronization and Connection Timeouts - - An IKE endpoint is allowed to forget all of its state associated with - an IKE_SA and the collection of corresponding CHILD_SAs at any time. - This is the anticipated behavior in the event of an endpoint crash - and restart. It is important when an endpoint either fails or - reinitializes its state that the other endpoint detect those - conditions and not continue to waste network bandwidth by sending - packets over discarded SAs and having them fall into a black hole. - - Since IKE is designed to operate in spite of Denial of Service (DoS) - attacks from the network, an endpoint MUST NOT conclude that the - other endpoint has failed based on any routing information (e.g., - ICMP messages) or IKE messages that arrive without cryptographic - protection (e.g., Notify messages complaining about unknown SPIs). - An endpoint MUST conclude that the other endpoint has failed only - when repeated attempts to contact it have gone unanswered for a - timeout period or when a cryptographically protected INITIAL_CONTACT - notification is received on a different IKE_SA to the same - authenticated identity. An endpoint SHOULD suspect that the other - endpoint has failed based on routing information and initiate a - request to see whether the other endpoint is alive. To check whether - the other side is alive, IKE specifies an empty INFORMATIONAL message - - - -Kaufman Standards Track [Page 15] - -RFC 4306 IKEv2 December 2005 - - - that (like all IKE requests) requires an acknowledgement (note that - within the context of an IKE_SA, an "empty" message consists of an - IKE header followed by an Encrypted payload that contains no - payloads). If a cryptographically protected message has been - received from the other side recently, unprotected notifications MAY - be ignored. Implementations MUST limit the rate at which they take - actions based on unprotected messages. - - Numbers of retries and lengths of timeouts are not covered in this - specification because they do not affect interoperability. It is - suggested that messages be retransmitted at least a dozen times over - a period of at least several minutes before giving up on an SA, but - different environments may require different rules. To be a good - network citizen, retranmission times MUST increase exponentially to - avoid flooding the network and making an existing congestion - situation worse. If there has only been outgoing traffic on all of - the SAs associated with an IKE_SA, it is essential to confirm - liveness of the other endpoint to avoid black holes. If no - cryptographically protected messages have been received on an IKE_SA - or any of its CHILD_SAs recently, the system needs to perform a - liveness check in order to prevent sending messages to a dead peer. - Receipt of a fresh cryptographically protected message on an IKE_SA - or any of its CHILD_SAs ensures liveness of the IKE_SA and all of its - CHILD_SAs. Note that this places requirements on the failure modes - of an IKE endpoint. An implementation MUST NOT continue sending on - any SA if some failure prevents it from receiving on all of the - associated SAs. If CHILD_SAs can fail independently from one another - without the associated IKE_SA being able to send a delete message, - then they MUST be negotiated by separate IKE_SAs. - - There is a Denial of Service attack on the initiator of an IKE_SA - that can be avoided if the initiator takes the proper care. Since - the first two messages of an SA setup are not cryptographically - protected, an attacker could respond to the initiator's message - before the genuine responder and poison the connection setup attempt. - To prevent this, the initiator MAY be willing to accept multiple - responses to its first message, treat each as potentially legitimate, - respond to it, and then discard all the invalid half-open connections - when it receives a valid cryptographically protected response to any - one of its requests. Once a cryptographically valid response is - received, all subsequent responses should be ignored whether or not - they are cryptographically valid. - - Note that with these rules, there is no reason to negotiate and agree - upon an SA lifetime. If IKE presumes the partner is dead, based on - repeated lack of acknowledgement to an IKE message, then the IKE SA - and all CHILD_SAs set up through that IKE_SA are deleted. - - - - -Kaufman Standards Track [Page 16] - -RFC 4306 IKEv2 December 2005 - - - An IKE endpoint may at any time delete inactive CHILD_SAs to recover - resources used to hold their state. If an IKE endpoint chooses to - delete CHILD_SAs, it MUST send Delete payloads to the other end - notifying it of the deletion. It MAY similarly time out the IKE_SA. - Closing the IKE_SA implicitly closes all associated CHILD_SAs. In - this case, an IKE endpoint SHOULD send a Delete payload indicating - that it has closed the IKE_SA. - -2.5. Version Numbers and Forward Compatibility - - This document describes version 2.0 of IKE, meaning the major version - number is 2 and the minor version number is zero. It is likely that - some implementations will want to support both version 1.0 and - version 2.0, and in the future, other versions. - - The major version number should be incremented only if the packet - formats or required actions have changed so dramatically that an - older version node would not be able to interoperate with a newer - version node if it simply ignored the fields it did not understand - and took the actions specified in the older specification. The minor - version number indicates new capabilities, and MUST be ignored by a - node with a smaller minor version number, but used for informational - purposes by the node with the larger minor version number. For - example, it might indicate the ability to process a newly defined - notification message. The node with the larger minor version number - would simply note that its correspondent would not be able to - understand that message and therefore would not send it. - - If an endpoint receives a message with a higher major version number, - it MUST drop the message and SHOULD send an unauthenticated - notification message containing the highest version number it - supports. If an endpoint supports major version n, and major version - m, it MUST support all versions between n and m. If it receives a - message with a major version that it supports, it MUST respond with - that version number. In order to prevent two nodes from being - tricked into corresponding with a lower major version number than the - maximum that they both support, IKE has a flag that indicates that - the node is capable of speaking a higher major version number. - - Thus, the major version number in the IKE header indicates the - version number of the message, not the highest version number that - the transmitter supports. If the initiator is capable of speaking - versions n, n+1, and n+2, and the responder is capable of speaking - versions n and n+1, then they will negotiate speaking n+1, where the - initiator will set the flag indicating its ability to speak a higher - version. If they mistakenly (perhaps through an active attacker - - - - - -Kaufman Standards Track [Page 17] - -RFC 4306 IKEv2 December 2005 - - - sending error messages) negotiate to version n, then both will notice - that the other side can support a higher version number, and they - MUST break the connection and reconnect using version n+1. - - Note that IKEv1 does not follow these rules, because there is no way - in v1 of noting that you are capable of speaking a higher version - number. So an active attacker can trick two v2-capable nodes into - speaking v1. When a v2-capable node negotiates down to v1, it SHOULD - note that fact in its logs. - - Also for forward compatibility, all fields marked RESERVED MUST be - set to zero by a version 2.0 implementation and their content MUST be - ignored by a version 2.0 implementation ("Be conservative in what you - send and liberal in what you receive"). In this way, future versions - of the protocol can use those fields in a way that is guaranteed to - be ignored by implementations that do not understand them. - Similarly, payload types that are not defined are reserved for future - use; implementations of version 2.0 MUST skip over those payloads and - ignore their contents. - - IKEv2 adds a "critical" flag to each payload header for further - flexibility for forward compatibility. If the critical flag is set - and the payload type is unrecognized, the message MUST be rejected - and the response to the IKE request containing that payload MUST - include a Notify payload UNSUPPORTED_CRITICAL_PAYLOAD, indicating an - unsupported critical payload was included. If the critical flag is - not set and the payload type is unsupported, that payload MUST be - ignored. - - Although new payload types may be added in the future and may appear - interleaved with the fields defined in this specification, - implementations MUST send the payloads defined in this specification - in the order shown in the figures in section 2 and implementations - SHOULD reject as invalid a message with those payloads in any other - order. - -2.6. Cookies - - The term "cookies" originates with Karn and Simpson [RFC2522] in - Photuris, an early proposal for key management with IPsec, and it has - persisted. The Internet Security Association and Key Management - Protocol (ISAKMP) [MSST98] fixed message header includes two eight- - octet fields titled "cookies", and that syntax is used by both IKEv1 - and IKEv2 though in IKEv2 they are referred to as the IKE SPI and - there is a new separate field in a Notify payload holding the cookie. - The initial two eight-octet fields in the header are used as a - connection identifier at the beginning of IKE packets. Each endpoint - - - - -Kaufman Standards Track [Page 18] - -RFC 4306 IKEv2 December 2005 - - - chooses one of the two SPIs and SHOULD choose them so as to be unique - identifiers of an IKE_SA. An SPI value of zero is special and - indicates that the remote SPI value is not yet known by the sender. - - Unlike ESP and AH where only the recipient's SPI appears in the - header of a message, in IKE the sender's SPI is also sent in every - message. Since the SPI chosen by the original initiator of the - IKE_SA is always sent first, an endpoint with multiple IKE_SAs open - that wants to find the appropriate IKE_SA using the SPI it assigned - must look at the I(nitiator) Flag bit in the header to determine - whether it assigned the first or the second eight octets. - - In the first message of an initial IKE exchange, the initiator will - not know the responder's SPI value and will therefore set that field - to zero. - - An expected attack against IKE is state and CPU exhaustion, where the - target is flooded with session initiation requests from forged IP - addresses. This attack can be made less effective if an - implementation of a responder uses minimal CPU and commits no state - to an SA until it knows the initiator can receive packets at the - address from which it claims to be sending them. To accomplish this, - a responder SHOULD -- when it detects a large number of half-open - IKE_SAs -- reject initial IKE messages unless they contain a Notify - payload of type COOKIE. It SHOULD instead send an unprotected IKE - message as a response and include COOKIE Notify payload with the - cookie data to be returned. Initiators who receive such responses - MUST retry the IKE_SA_INIT with a Notify payload of type COOKIE - containing the responder supplied cookie data as the first payload - and all other payloads unchanged. The initial exchange will then be - as follows: - - Initiator Responder - ----------- ----------- - HDR(A,0), SAi1, KEi, Ni --> - - <-- HDR(A,0), N(COOKIE) - - HDR(A,0), N(COOKIE), SAi1, KEi, Ni --> - - <-- HDR(A,B), SAr1, KEr, Nr, [CERTREQ] - - HDR(A,B), SK {IDi, [CERT,] [CERTREQ,] [IDr,] - AUTH, SAi2, TSi, TSr} --> - - <-- HDR(A,B), SK {IDr, [CERT,] AUTH, - SAr2, TSi, TSr} - - - - -Kaufman Standards Track [Page 19] - -RFC 4306 IKEv2 December 2005 - - - The first two messages do not affect any initiator or responder state - except for communicating the cookie. In particular, the message - sequence numbers in the first four messages will all be zero and the - message sequence numbers in the last two messages will be one. 'A' is - the SPI assigned by the initiator, while 'B' is the SPI assigned by - the responder. - - An IKE implementation SHOULD implement its responder cookie - generation in such a way as to not require any saved state to - recognize its valid cookie when the second IKE_SA_INIT message - arrives. The exact algorithms and syntax they use to generate - cookies do not affect interoperability and hence are not specified - here. The following is an example of how an endpoint could use - cookies to implement limited DOS protection. - - A good way to do this is to set the responder cookie to be: - - Cookie = <VersionIDofSecret> | Hash(Ni | IPi | SPIi | <secret>) - - where <secret> is a randomly generated secret known only to the - responder and periodically changed and | indicates concatenation. - <VersionIDofSecret> should be changed whenever <secret> is - regenerated. The cookie can be recomputed when the IKE_SA_INIT - arrives the second time and compared to the cookie in the received - message. If it matches, the responder knows that the cookie was - generated since the last change to <secret> and that IPi must be the - same as the source address it saw the first time. Incorporating SPIi - into the calculation ensures that if multiple IKE_SAs are being set - up in parallel they will all get different cookies (assuming the - initiator chooses unique SPIi's). Incorporating Ni into the hash - ensures that an attacker who sees only message 2 can't successfully - forge a message 3. - - If a new value for <secret> is chosen while there are connections in - the process of being initialized, an IKE_SA_INIT might be returned - with other than the current <VersionIDofSecret>. The responder in - that case MAY reject the message by sending another response with a - new cookie or it MAY keep the old value of <secret> around for a - short time and accept cookies computed from either one. The - responder SHOULD NOT accept cookies indefinitely after <secret> is - changed, since that would defeat part of the denial of service - protection. The responder SHOULD change the value of <secret> - frequently, especially if under attack. - - - - - - - - -Kaufman Standards Track [Page 20] - -RFC 4306 IKEv2 December 2005 - - -2.7. Cryptographic Algorithm Negotiation - - The payload type known as "SA" indicates a proposal for a set of - choices of IPsec protocols (IKE, ESP, and/or AH) for the SA as well - as cryptographic algorithms associated with each protocol. - - An SA payload consists of one or more proposals. Each proposal - includes one or more protocols (usually one). Each protocol contains - one or more transforms -- each specifying a cryptographic algorithm. - Each transform contains zero or more attributes (attributes are - needed only if the transform identifier does not completely specify - the cryptographic algorithm). - - This hierarchical structure was designed to efficiently encode - proposals for cryptographic suites when the number of supported - suites is large because multiple values are acceptable for multiple - transforms. The responder MUST choose a single suite, which MAY be - any subset of the SA proposal following the rules below: - - Each proposal contains one or more protocols. If a proposal is - accepted, the SA response MUST contain the same protocols in the - same order as the proposal. The responder MUST accept a single - proposal or reject them all and return an error. (Example: if a - single proposal contains ESP and AH and that proposal is accepted, - both ESP and AH MUST be accepted. If ESP and AH are included in - separate proposals, the responder MUST accept only one of them). - - Each IPsec protocol proposal contains one or more transforms. - Each transform contains a transform type. The accepted - cryptographic suite MUST contain exactly one transform of each - type included in the proposal. For example: if an ESP proposal - includes transforms ENCR_3DES, ENCR_AES w/keysize 128, ENCR_AES - w/keysize 256, AUTH_HMAC_MD5, and AUTH_HMAC_SHA, the accepted - suite MUST contain one of the ENCR_ transforms and one of the - AUTH_ transforms. Thus, six combinations are acceptable. - - Since the initiator sends its Diffie-Hellman value in the - IKE_SA_INIT, it must guess the Diffie-Hellman group that the - responder will select from its list of supported groups. If the - initiator guesses wrong, the responder will respond with a Notify - payload of type INVALID_KE_PAYLOAD indicating the selected group. In - this case, the initiator MUST retry the IKE_SA_INIT with the - corrected Diffie-Hellman group. The initiator MUST again propose its - full set of acceptable cryptographic suites because the rejection - message was unauthenticated and otherwise an active attacker could - trick the endpoints into negotiating a weaker suite than a stronger - one that they both prefer. - - - - -Kaufman Standards Track [Page 21] - -RFC 4306 IKEv2 December 2005 - - -2.8. Rekeying - - IKE, ESP, and AH security associations use secret keys that SHOULD be - used only for a limited amount of time and to protect a limited - amount of data. This limits the lifetime of the entire security - association. When the lifetime of a security association expires, - the security association MUST NOT be used. If there is demand, new - security associations MAY be established. Reestablishment of - security associations to take the place of ones that expire is - referred to as "rekeying". - - To allow for minimal IPsec implementations, the ability to rekey SAs - without restarting the entire IKE_SA is optional. An implementation - MAY refuse all CREATE_CHILD_SA requests within an IKE_SA. If an SA - has expired or is about to expire and rekeying attempts using the - mechanisms described here fail, an implementation MUST close the - IKE_SA and any associated CHILD_SAs and then MAY start new ones. - Implementations SHOULD support in-place rekeying of SAs, since doing - so offers better performance and is likely to reduce the number of - packets lost during the transition. - - To rekey a CHILD_SA within an existing IKE_SA, create a new, - equivalent SA (see section 2.17 below), and when the new one is - established, delete the old one. To rekey an IKE_SA, establish a new - equivalent IKE_SA (see section 2.18 below) with the peer to whom the - old IKE_SA is shared using a CREATE_CHILD_SA within the existing - IKE_SA. An IKE_SA so created inherits all of the original IKE_SA's - CHILD_SAs. Use the new IKE_SA for all control messages needed to - maintain the CHILD_SAs created by the old IKE_SA, and delete the old - IKE_SA. The Delete payload to delete itself MUST be the last request - sent over an IKE_SA. - - SAs SHOULD be rekeyed proactively, i.e., the new SA should be - established before the old one expires and becomes unusable. Enough - time should elapse between the time the new SA is established and the - old one becomes unusable so that traffic can be switched over to the - new SA. - - A difference between IKEv1 and IKEv2 is that in IKEv1 SA lifetimes - were negotiated. In IKEv2, each end of the SA is responsible for - enforcing its own lifetime policy on the SA and rekeying the SA when - necessary. If the two ends have different lifetime policies, the end - with the shorter lifetime will end up always being the one to request - the rekeying. If an SA bundle has been inactive for a long time and - if an endpoint would not initiate the SA in the absence of traffic, - the endpoint MAY choose to close the SA instead of rekeying it when - its lifetime expires. It SHOULD do so if there has been no traffic - since the last time the SA was rekeyed. - - - -Kaufman Standards Track [Page 22] - -RFC 4306 IKEv2 December 2005 - - - If the two ends have the same lifetime policies, it is possible that - both will initiate a rekeying at the same time (which will result in - redundant SAs). To reduce the probability of this happening, the - timing of rekeying requests SHOULD be jittered (delayed by a random - amount of time after the need for rekeying is noticed). - - This form of rekeying may temporarily result in multiple similar SAs - between the same pairs of nodes. When there are two SAs eligible to - receive packets, a node MUST accept incoming packets through either - SA. If redundant SAs are created though such a collision, the SA - created with the lowest of the four nonces used in the two exchanges - SHOULD be closed by the endpoint that created it. - - Note that IKEv2 deliberately allows parallel SAs with the same - traffic selectors between common endpoints. One of the purposes of - this is to support traffic quality of service (QoS) differences among - the SAs (see [RFC2474], [RFC2475], and section 4.1 of [RFC2983]). - Hence unlike IKEv1, the combination of the endpoints and the traffic - selectors may not uniquely identify an SA between those endpoints, so - the IKEv1 rekeying heuristic of deleting SAs on the basis of - duplicate traffic selectors SHOULD NOT be used. - - The node that initiated the surviving rekeyed SA SHOULD delete the - replaced SA after the new one is established. - - There are timing windows -- particularly in the presence of lost - packets -- where endpoints may not agree on the state of an SA. The - responder to a CREATE_CHILD_SA MUST be prepared to accept messages on - an SA before sending its response to the creation request, so there - is no ambiguity for the initiator. The initiator MAY begin sending - on an SA as soon as it processes the response. The initiator, - however, cannot receive on a newly created SA until it receives and - processes the response to its CREATE_CHILD_SA request. How, then, is - the responder to know when it is OK to send on the newly created SA? - - From a technical correctness and interoperability perspective, the - responder MAY begin sending on an SA as soon as it sends its response - to the CREATE_CHILD_SA request. In some situations, however, this - could result in packets unnecessarily being dropped, so an - implementation MAY want to defer such sending. - - The responder can be assured that the initiator is prepared to - receive messages on an SA if either (1) it has received a - cryptographically valid message on the new SA, or (2) the new SA - rekeys an existing SA and it receives an IKE request to close the - replaced SA. When rekeying an SA, the responder SHOULD continue to - send messages on the old SA until one of those events occurs. When - establishing a new SA, the responder MAY defer sending messages on a - - - -Kaufman Standards Track [Page 23] - -RFC 4306 IKEv2 December 2005 - - - new SA until either it receives one or a timeout has occurred. If an - initiator receives a message on an SA for which it has not received a - response to its CREATE_CHILD_SA request, it SHOULD interpret that as - a likely packet loss and retransmit the CREATE_CHILD_SA request. An - initiator MAY send a dummy message on a newly created SA if it has no - messages queued in order to assure the responder that the initiator - is ready to receive messages. - -2.9. Traffic Selector Negotiation - - When an IP packet is received by an RFC4301-compliant IPsec subsystem - and matches a "protect" selector in its Security Policy Database - (SPD), the subsystem MUST protect that packet with IPsec. When no SA - exists yet, it is the task of IKE to create it. Maintenance of a - system's SPD is outside the scope of IKE (see [PFKEY] for an example - protocol), though some implementations might update their SPD in - connection with the running of IKE (for an example scenario, see - section 1.1.3). - - Traffic Selector (TS) payloads allow endpoints to communicate some of - the information from their SPD to their peers. TS payloads specify - the selection criteria for packets that will be forwarded over the - newly set up SA. This can serve as a consistency check in some - scenarios to assure that the SPDs are consistent. In others, it - guides the dynamic update of the SPD. - - Two TS payloads appear in each of the messages in the exchange that - creates a CHILD_SA pair. Each TS payload contains one or more - Traffic Selectors. Each Traffic Selector consists of an address - range (IPv4 or IPv6), a port range, and an IP protocol ID. In - support of the scenario described in section 1.1.3, an initiator may - request that the responder assign an IP address and tell the - initiator what it is. - - IKEv2 allows the responder to choose a subset of the traffic proposed - by the initiator. This could happen when the configurations of the - two endpoints are being updated but only one end has received the new - information. Since the two endpoints may be configured by different - people, the incompatibility may persist for an extended period even - in the absence of errors. It also allows for intentionally different - configurations, as when one end is configured to tunnel all addresses - and depends on the other end to have the up-to-date list. - - The first of the two TS payloads is known as TSi (Traffic Selector- - initiator). The second is known as TSr (Traffic Selector-responder). - TSi specifies the source address of traffic forwarded from (or the - destination address of traffic forwarded to) the initiator of the - CHILD_SA pair. TSr specifies the destination address of the traffic - - - -Kaufman Standards Track [Page 24] - -RFC 4306 IKEv2 December 2005 - - - forwarded to (or the source address of the traffic forwarded from) - the responder of the CHILD_SA pair. For example, if the original - initiator request the creation of a CHILD_SA pair, and wishes to - tunnel all traffic from subnet 192.0.1.* on the initiator's side to - subnet 192.0.2.* on the responder's side, the initiator would include - a single traffic selector in each TS payload. TSi would specify the - address range (192.0.1.0 - 192.0.1.255) and TSr would specify the - address range (192.0.2.0 - 192.0.2.255). Assuming that proposal was - acceptable to the responder, it would send identical TS payloads - back. (Note: The IP address range 192.0.2.* has been reserved for - use in examples in RFCs and similar documents. This document needed - two such ranges, and so also used 192.0.1.*. This should not be - confused with any actual address.) - - The responder is allowed to narrow the choices by selecting a subset - of the traffic, for instance by eliminating or narrowing the range of - one or more members of the set of traffic selectors, provided the set - does not become the NULL set. - - It is possible for the responder's policy to contain multiple smaller - ranges, all encompassed by the initiator's traffic selector, and with - the responder's policy being that each of those ranges should be sent - over a different SA. Continuing the example above, the responder - might have a policy of being willing to tunnel those addresses to and - from the initiator, but might require that each address pair be on a - separately negotiated CHILD_SA. If the initiator generated its - request in response to an incoming packet from 192.0.1.43 to - 192.0.2.123, there would be no way for the responder to determine - which pair of addresses should be included in this tunnel, and it - would have to make a guess or reject the request with a status of - SINGLE_PAIR_REQUIRED. - - To enable the responder to choose the appropriate range in this case, - if the initiator has requested the SA due to a data packet, the - initiator SHOULD include as the first traffic selector in each of TSi - and TSr a very specific traffic selector including the addresses in - the packet triggering the request. In the example, the initiator - would include in TSi two traffic selectors: the first containing the - address range (192.0.1.43 - 192.0.1.43) and the source port and IP - protocol from the packet and the second containing (192.0.1.0 - - 192.0.1.255) with all ports and IP protocols. The initiator would - similarly include two traffic selectors in TSr. - - If the responder's policy does not allow it to accept the entire set - of traffic selectors in the initiator's request, but does allow him - to accept the first selector of TSi and TSr, then the responder MUST - narrow the traffic selectors to a subset that includes the - - - - -Kaufman Standards Track [Page 25] - -RFC 4306 IKEv2 December 2005 - - - initiator's first choices. In this example, the responder might - respond with TSi being (192.0.1.43 - 192.0.1.43) with all ports and - IP protocols. - - If the initiator creates the CHILD_SA pair not in response to an - arriving packet, but rather, say, upon startup, then there may be no - specific addresses the initiator prefers for the initial tunnel over - any other. In that case, the first values in TSi and TSr MAY be - ranges rather than specific values, and the responder chooses a - subset of the initiator's TSi and TSr that are acceptable. If more - than one subset is acceptable but their union is not, the responder - MUST accept some subset and MAY include a Notify payload of type - ADDITIONAL_TS_POSSIBLE to indicate that the initiator might want to - try again. This case will occur only when the initiator and - responder are configured differently from one another. If the - initiator and responder agree on the granularity of tunnels, the - initiator will never request a tunnel wider than the responder will - accept. Such misconfigurations SHOULD be recorded in error logs. - -2.10. Nonces - - The IKE_SA_INIT messages each contain a nonce. These nonces are used - as inputs to cryptographic functions. The CREATE_CHILD_SA request - and the CREATE_CHILD_SA response also contain nonces. These nonces - are used to add freshness to the key derivation technique used to - obtain keys for CHILD_SA, and to ensure creation of strong pseudo- - random bits from the Diffie-Hellman key. Nonces used in IKEv2 MUST - be randomly chosen, MUST be at least 128 bits in size, and MUST be at - least half the key size of the negotiated prf. ("prf" refers to - "pseudo-random function", one of the cryptographic algorithms - negotiated in the IKE exchange.) If the same random number source is - used for both keys and nonces, care must be taken to ensure that the - latter use does not compromise the former. - -2.11. Address and Port Agility - - IKE runs over UDP ports 500 and 4500, and implicitly sets up ESP and - AH associations for the same IP addresses it runs over. The IP - addresses and ports in the outer header are, however, not themselves - cryptographically protected, and IKE is designed to work even through - Network Address Translation (NAT) boxes. An implementation MUST - accept incoming requests even if the source port is not 500 or 4500, - and MUST respond to the address and port from which the request was - received. It MUST specify the address and port at which the request - was received as the source address and port in the response. IKE - functions identically over IPv4 or IPv6. - - - - - -Kaufman Standards Track [Page 26] - -RFC 4306 IKEv2 December 2005 - - -2.12. Reuse of Diffie-Hellman Exponentials - - IKE generates keying material using an ephemeral Diffie-Hellman - exchange in order to gain the property of "perfect forward secrecy". - This means that once a connection is closed and its corresponding - keys are forgotten, even someone who has recorded all of the data - from the connection and gets access to all of the long-term keys of - the two endpoints cannot reconstruct the keys used to protect the - conversation without doing a brute force search of the session key - space. - - Achieving perfect forward secrecy requires that when a connection is - closed, each endpoint MUST forget not only the keys used by the - connection but also any information that could be used to recompute - those keys. In particular, it MUST forget the secrets used in the - Diffie-Hellman calculation and any state that may persist in the - state of a pseudo-random number generator that could be used to - recompute the Diffie-Hellman secrets. - - Since the computing of Diffie-Hellman exponentials is computationally - expensive, an endpoint may find it advantageous to reuse those - exponentials for multiple connection setups. There are several - reasonable strategies for doing this. An endpoint could choose a new - exponential only periodically though this could result in less-than- - perfect forward secrecy if some connection lasts for less than the - lifetime of the exponential. Or it could keep track of which - exponential was used for each connection and delete the information - associated with the exponential only when some corresponding - connection was closed. This would allow the exponential to be reused - without losing perfect forward secrecy at the cost of maintaining - more state. - - Decisions as to whether and when to reuse Diffie-Hellman exponentials - is a private decision in the sense that it will not affect - interoperability. An implementation that reuses exponentials MAY - choose to remember the exponential used by the other endpoint on past - exchanges and if one is reused to avoid the second half of the - calculation. - -2.13. Generating Keying Material - - In the context of the IKE_SA, four cryptographic algorithms are - negotiated: an encryption algorithm, an integrity protection - algorithm, a Diffie-Hellman group, and a pseudo-random function - (prf). The pseudo-random function is used for the construction of - keying material for all of the cryptographic algorithms used in both - the IKE_SA and the CHILD_SAs. - - - - -Kaufman Standards Track [Page 27] - -RFC 4306 IKEv2 December 2005 - - - We assume that each encryption algorithm and integrity protection - algorithm uses a fixed-size key and that any randomly chosen value of - that fixed size can serve as an appropriate key. For algorithms that - accept a variable length key, a fixed key size MUST be specified as - part of the cryptographic transform negotiated. For algorithms for - which not all values are valid keys (such as DES or 3DES with key - parity), the algorithm by which keys are derived from arbitrary - values MUST be specified by the cryptographic transform. For - integrity protection functions based on Hashed Message Authentication - Code (HMAC), the fixed key size is the size of the output of the - underlying hash function. When the prf function takes a variable - length key, variable length data, and produces a fixed-length output - (e.g., when using HMAC), the formulas in this document apply. When - the key for the prf function has fixed length, the data provided as a - key is truncated or padded with zeros as necessary unless exceptional - processing is explained following the formula. - - Keying material will always be derived as the output of the - negotiated prf algorithm. Since the amount of keying material needed - may be greater than the size of the output of the prf algorithm, we - will use the prf iteratively. We will use the terminology prf+ to - describe the function that outputs a pseudo-random stream based on - the inputs to a prf as follows: (where | indicates concatenation) - - prf+ (K,S) = T1 | T2 | T3 | T4 | ... - - where: - T1 = prf (K, S | 0x01) - T2 = prf (K, T1 | S | 0x02) - T3 = prf (K, T2 | S | 0x03) - T4 = prf (K, T3 | S | 0x04) - - continuing as needed to compute all required keys. The keys are - taken from the output string without regard to boundaries (e.g., if - the required keys are a 256-bit Advanced Encryption Standard (AES) - key and a 160-bit HMAC key, and the prf function generates 160 bits, - the AES key will come from T1 and the beginning of T2, while the HMAC - key will come from the rest of T2 and the beginning of T3). - - The constant concatenated to the end of each string feeding the prf - is a single octet. prf+ in this document is not defined beyond 255 - times the size of the prf output. - -2.14. Generating Keying Material for the IKE_SA - - The shared keys are computed as follows. A quantity called SKEYSEED - is calculated from the nonces exchanged during the IKE_SA_INIT - exchange and the Diffie-Hellman shared secret established during that - - - -Kaufman Standards Track [Page 28] - -RFC 4306 IKEv2 December 2005 - - - exchange. SKEYSEED is used to calculate seven other secrets: SK_d - used for deriving new keys for the CHILD_SAs established with this - IKE_SA; SK_ai and SK_ar used as a key to the integrity protection - algorithm for authenticating the component messages of subsequent - exchanges; SK_ei and SK_er used for encrypting (and of course - decrypting) all subsequent exchanges; and SK_pi and SK_pr, which are - used when generating an AUTH payload. - - SKEYSEED and its derivatives are computed as follows: - - SKEYSEED = prf(Ni | Nr, g^ir) - - {SK_d | SK_ai | SK_ar | SK_ei | SK_er | SK_pi | SK_pr } = prf+ - (SKEYSEED, Ni | Nr | SPIi | SPIr ) - - (indicating that the quantities SK_d, SK_ai, SK_ar, SK_ei, SK_er, - SK_pi, and SK_pr are taken in order from the generated bits of the - prf+). g^ir is the shared secret from the ephemeral Diffie-Hellman - exchange. g^ir is represented as a string of octets in big endian - order padded with zeros if necessary to make it the length of the - modulus. Ni and Nr are the nonces, stripped of any headers. If the - negotiated prf takes a fixed-length key and the lengths of Ni and Nr - do not add up to that length, half the bits must come from Ni and - half from Nr, taking the first bits of each. - - The two directions of traffic flow use different keys. The keys used - to protect messages from the original initiator are SK_ai and SK_ei. - The keys used to protect messages in the other direction are SK_ar - and SK_er. Each algorithm takes a fixed number of bits of keying - material, which is specified as part of the algorithm. For integrity - algorithms based on a keyed hash, the key size is always equal to the - length of the output of the underlying hash function. - -2.15. Authentication of the IKE_SA - - When not using extensible authentication (see section 2.16), the - peers are authenticated by having each sign (or MAC using a shared - secret as the key) a block of data. For the responder, the octets to - be signed start with the first octet of the first SPI in the header - of the second message and end with the last octet of the last payload - in the second message. Appended to this (for purposes of computing - the signature) are the initiator's nonce Ni (just the value, not the - payload containing it), and the value prf(SK_pr,IDr') where IDr' is - the responder's ID payload excluding the fixed header. Note that - neither the nonce Ni nor the value prf(SK_pr,IDr') are transmitted. - Similarly, the initiator signs the first message, starting with the - first octet of the first SPI in the header and ending with the last - octet of the last payload. Appended to this (for purposes of - - - -Kaufman Standards Track [Page 29] - -RFC 4306 IKEv2 December 2005 - - - computing the signature) are the responder's nonce Nr, and the value - prf(SK_pi,IDi'). In the above calculation, IDi' and IDr' are the - entire ID payloads excluding the fixed header. It is critical to the - security of the exchange that each side sign the other side's nonce. - - Note that all of the payloads are included under the signature, - including any payload types not defined in this document. If the - first message of the exchange is sent twice (the second time with a - responder cookie and/or a different Diffie-Hellman group), it is the - second version of the message that is signed. - - Optionally, messages 3 and 4 MAY include a certificate, or - certificate chain providing evidence that the key used to compute a - digital signature belongs to the name in the ID payload. The - signature or MAC will be computed using algorithms dictated by the - type of key used by the signer, and specified by the Auth Method - field in the Authentication payload. There is no requirement that - the initiator and responder sign with the same cryptographic - algorithms. The choice of cryptographic algorithms depends on the - type of key each has. In particular, the initiator may be using a - shared key while the responder may have a public signature key and - certificate. It will commonly be the case (but it is not required) - that if a shared secret is used for authentication that the same key - is used in both directions. Note that it is a common but typically - insecure practice to have a shared key derived solely from a user- - chosen password without incorporating another source of randomness. - - This is typically insecure because user-chosen passwords are unlikely - to have sufficient unpredictability to resist dictionary attacks and - these attacks are not prevented in this authentication method. - (Applications using password-based authentication for bootstrapping - and IKE_SA should use the authentication method in section 2.16, - which is designed to prevent off-line dictionary attacks.) The pre- - shared key SHOULD contain as much unpredictability as the strongest - key being negotiated. In the case of a pre-shared key, the AUTH - value is computed as: - - AUTH = prf(prf(Shared Secret,"Key Pad for IKEv2"), <msg octets>) - - where the string "Key Pad for IKEv2" is 17 ASCII characters without - null termination. The shared secret can be variable length. The pad - string is added so that if the shared secret is derived from a - password, the IKE implementation need not store the password in - cleartext, but rather can store the value prf(Shared Secret,"Key Pad - for IKEv2"), which could not be used as a password equivalent for - protocols other than IKEv2. As noted above, deriving the shared - secret from a password is not secure. This construction is used - because it is anticipated that people will do it anyway. The - - - -Kaufman Standards Track [Page 30] - -RFC 4306 IKEv2 December 2005 - - - management interface by which the Shared Secret is provided MUST - accept ASCII strings of at least 64 octets and MUST NOT add a null - terminator before using them as shared secrets. It MUST also accept - a HEX encoding of the Shared Secret. The management interface MAY - accept other encodings if the algorithm for translating the encoding - to a binary string is specified. If the negotiated prf takes a - fixed-size key, the shared secret MUST be of that fixed size. - -2.16. Extensible Authentication Protocol Methods - - In addition to authentication using public key signatures and shared - secrets, IKE supports authentication using methods defined in RFC - 3748 [EAP]. Typically, these methods are asymmetric (designed for a - user authenticating to a server), and they may not be mutual. For - this reason, these protocols are typically used to authenticate the - initiator to the responder and MUST be used in conjunction with a - public key signature based authentication of the responder to the - initiator. These methods are often associated with mechanisms - referred to as "Legacy Authentication" mechanisms. - - While this memo references [EAP] with the intent that new methods can - be added in the future without updating this specification, some - simpler variations are documented here and in section 3.16. [EAP] - defines an authentication protocol requiring a variable number of - messages. Extensible Authentication is implemented in IKE as - additional IKE_AUTH exchanges that MUST be completed in order to - initialize the IKE_SA. - - An initiator indicates a desire to use extensible authentication by - leaving out the AUTH payload from message 3. By including an IDi - payload but not an AUTH payload, the initiator has declared an - identity but has not proven it. If the responder is willing to use - an extensible authentication method, it will place an Extensible - Authentication Protocol (EAP) payload in message 4 and defer sending - SAr2, TSi, and TSr until initiator authentication is complete in a - subsequent IKE_AUTH exchange. In the case of a minimal extensible - authentication, the initial SA establishment will appear as follows: - - - - - - - - - - - - - - -Kaufman Standards Track [Page 31] - -RFC 4306 IKEv2 December 2005 - - - Initiator Responder - ----------- ----------- - HDR, SAi1, KEi, Ni --> - - <-- HDR, SAr1, KEr, Nr, [CERTREQ] - - HDR, SK {IDi, [CERTREQ,] [IDr,] - SAi2, TSi, TSr} --> - - <-- HDR, SK {IDr, [CERT,] AUTH, - EAP } - - HDR, SK {EAP} --> - - <-- HDR, SK {EAP (success)} - - HDR, SK {AUTH} --> - - <-- HDR, SK {AUTH, SAr2, TSi, TSr } - - For EAP methods that create a shared key as a side effect of - authentication, that shared key MUST be used by both the initiator - and responder to generate AUTH payloads in messages 7 and 8 using the - syntax for shared secrets specified in section 2.15. The shared key - from EAP is the field from the EAP specification named MSK. The - shared key generated during an IKE exchange MUST NOT be used for any - other purpose. - - EAP methods that do not establish a shared key SHOULD NOT be used, as - they are subject to a number of man-in-the-middle attacks [EAPMITM] - if these EAP methods are used in other protocols that do not use a - server-authenticated tunnel. Please see the Security Considerations - section for more details. If EAP methods that do not generate a - shared key are used, the AUTH payloads in messages 7 and 8 MUST be - generated using SK_pi and SK_pr, respectively. - - The initiator of an IKE_SA using EAP SHOULD be capable of extending - the initial protocol exchange to at least ten IKE_AUTH exchanges in - the event the responder sends notification messages and/or retries - the authentication prompt. Once the protocol exchange defined by the - chosen EAP authentication method has successfully terminated, the - responder MUST send an EAP payload containing the Success message. - Similarly, if the authentication method has failed, the responder - MUST send an EAP payload containing the Failure message. The - responder MAY at any time terminate the IKE exchange by sending an - EAP payload containing the Failure message. - - - - - -Kaufman Standards Track [Page 32] - -RFC 4306 IKEv2 December 2005 - - - Following such an extended exchange, the EAP AUTH payloads MUST be - included in the two messages following the one containing the EAP - Success message. - -2.17. Generating Keying Material for CHILD_SAs - - A single CHILD_SA is created by the IKE_AUTH exchange, and additional - CHILD_SAs can optionally be created in CREATE_CHILD_SA exchanges. - Keying material for them is generated as follows: - - KEYMAT = prf+(SK_d, Ni | Nr) - - Where Ni and Nr are the nonces from the IKE_SA_INIT exchange if this - request is the first CHILD_SA created or the fresh Ni and Nr from the - CREATE_CHILD_SA exchange if this is a subsequent creation. - - For CREATE_CHILD_SA exchanges including an optional Diffie-Hellman - exchange, the keying material is defined as: - - KEYMAT = prf+(SK_d, g^ir (new) | Ni | Nr ) - - where g^ir (new) is the shared secret from the ephemeral Diffie- - Hellman exchange of this CREATE_CHILD_SA exchange (represented as an - octet string in big endian order padded with zeros in the high-order - bits if necessary to make it the length of the modulus). - - A single CHILD_SA negotiation may result in multiple security - associations. ESP and AH SAs exist in pairs (one in each direction), - and four SAs could be created in a single CHILD_SA negotiation if a - combination of ESP and AH is being negotiated. - - Keying material MUST be taken from the expanded KEYMAT in the - following order: - - All keys for SAs carrying data from the initiator to the responder - are taken before SAs going in the reverse direction. - - If multiple IPsec protocols are negotiated, keying material is - taken in the order in which the protocol headers will appear in - the encapsulated packet. - - If a single protocol has both encryption and authentication keys, - the encryption key is taken from the first octets of KEYMAT and - the authentication key is taken from the next octets. - - Each cryptographic algorithm takes a fixed number of bits of keying - material specified as part of the algorithm. - - - - -Kaufman Standards Track [Page 33] - -RFC 4306 IKEv2 December 2005 - - -2.18. Rekeying IKE_SAs Using a CREATE_CHILD_SA exchange - - The CREATE_CHILD_SA exchange can be used to rekey an existing IKE_SA - (see section 2.8). New initiator and responder SPIs are supplied in - the SPI fields. The TS payloads are omitted when rekeying an IKE_SA. - SKEYSEED for the new IKE_SA is computed using SK_d from the existing - IKE_SA as follows: - - SKEYSEED = prf(SK_d (old), [g^ir (new)] | Ni | Nr) - - where g^ir (new) is the shared secret from the ephemeral Diffie- - Hellman exchange of this CREATE_CHILD_SA exchange (represented as an - octet string in big endian order padded with zeros if necessary to - make it the length of the modulus) and Ni and Nr are the two nonces - stripped of any headers. - - The new IKE_SA MUST reset its message counters to 0. - - SK_d, SK_ai, SK_ar, SK_ei, and SK_er are computed from SKEYSEED as - specified in section 2.14. - -2.19. Requesting an Internal Address on a Remote Network - - Most commonly occurring in the endpoint-to-security-gateway scenario, - an endpoint may need an IP address in the network protected by the - security gateway and may need to have that address dynamically - assigned. A request for such a temporary address can be included in - any request to create a CHILD_SA (including the implicit request in - message 3) by including a CP payload. - - This function provides address allocation to an IPsec Remote Access - Client (IRAC) trying to tunnel into a network protected by an IPsec - Remote Access Server (IRAS). Since the IKE_AUTH exchange creates an - IKE_SA and a CHILD_SA, the IRAC MUST request the IRAS-controlled - address (and optionally other information concerning the protected - network) in the IKE_AUTH exchange. The IRAS may procure an address - for the IRAC from any number of sources such as a DHCP/BOOTP server - or its own address pool. - - Initiator Responder - ----------------------------- --------------------------- - HDR, SK {IDi, [CERT,] [CERTREQ,] - [IDr,] AUTH, CP(CFG_REQUEST), - SAi2, TSi, TSr} --> - - <-- HDR, SK {IDr, [CERT,] AUTH, - CP(CFG_REPLY), SAr2, - TSi, TSr} - - - -Kaufman Standards Track [Page 34] - -RFC 4306 IKEv2 December 2005 - - - In all cases, the CP payload MUST be inserted before the SA payload. - In variations of the protocol where there are multiple IKE_AUTH - exchanges, the CP payloads MUST be inserted in the messages - containing the SA payloads. - - CP(CFG_REQUEST) MUST contain at least an INTERNAL_ADDRESS attribute - (either IPv4 or IPv6) but MAY contain any number of additional - attributes the initiator wants returned in the response. - - For example, message from initiator to responder: - CP(CFG_REQUEST)= - INTERNAL_ADDRESS(0.0.0.0) - INTERNAL_NETMASK(0.0.0.0) - INTERNAL_DNS(0.0.0.0) - TSi = (0, 0-65535,0.0.0.0-255.255.255.255) - TSr = (0, 0-65535,0.0.0.0-255.255.255.255) - - NOTE: Traffic Selectors contain (protocol, port range, address - range). - - Message from responder to initiator: - - CP(CFG_REPLY)= - INTERNAL_ADDRESS(192.0.2.202) - INTERNAL_NETMASK(255.255.255.0) - INTERNAL_SUBNET(192.0.2.0/255.255.255.0) - TSi = (0, 0-65535,192.0.2.202-192.0.2.202) - TSr = (0, 0-65535,192.0.2.0-192.0.2.255) - - All returned values will be implementation dependent. As can be seen - in the above example, the IRAS MAY also send other attributes that - were not included in CP(CFG_REQUEST) and MAY ignore the non-mandatory - attributes that it does not support. - - The responder MUST NOT send a CFG_REPLY without having first received - a CP(CFG_REQUEST) from the initiator, because we do not want the IRAS - to perform an unnecessary configuration lookup if the IRAC cannot - process the REPLY. In the case where the IRAS's configuration - requires that CP be used for a given identity IDi, but IRAC has - failed to send a CP(CFG_REQUEST), IRAS MUST fail the request, and - terminate the IKE exchange with a FAILED_CP_REQUIRED error. - -2.20. Requesting the Peer's Version - - An IKE peer wishing to inquire about the other peer's IKE software - version information MAY use the method below. This is an example of - a configuration request within an INFORMATIONAL exchange, after the - IKE_SA and first CHILD_SA have been created. - - - -Kaufman Standards Track [Page 35] - -RFC 4306 IKEv2 December 2005 - - - An IKE implementation MAY decline to give out version information - prior to authentication or even after authentication to prevent - trolling in case some implementation is known to have some security - weakness. In that case, it MUST either return an empty string or no - CP payload if CP is not supported. - - Initiator Responder - ----------------------------- -------------------------- - HDR, SK{CP(CFG_REQUEST)} --> - <-- HDR, SK{CP(CFG_REPLY)} - - CP(CFG_REQUEST)= - APPLICATION_VERSION("") - - CP(CFG_REPLY) APPLICATION_VERSION("foobar v1.3beta, (c) Foo Bar - Inc.") - -2.21. Error Handling - - There are many kinds of errors that can occur during IKE processing. - If a request is received that is badly formatted or unacceptable for - reasons of policy (e.g., no matching cryptographic algorithms), the - response MUST contain a Notify payload indicating the error. If an - error occurs outside the context of an IKE request (e.g., the node is - getting ESP messages on a nonexistent SPI), the node SHOULD initiate - an INFORMATIONAL exchange with a Notify payload describing the - problem. - - Errors that occur before a cryptographically protected IKE_SA is - established must be handled very carefully. There is a trade-off - between wanting to be helpful in diagnosing a problem and responding - to it and wanting to avoid being a dupe in a denial of service attack - based on forged messages. - - If a node receives a message on UDP port 500 or 4500 outside the - context of an IKE_SA known to it (and not a request to start one), it - may be the result of a recent crash of the node. If the message is - marked as a response, the node MAY audit the suspicious event but - MUST NOT respond. If the message is marked as a request, the node - MAY audit the suspicious event and MAY send a response. If a - response is sent, the response MUST be sent to the IP address and - port from whence it came with the same IKE SPIs and the Message ID - copied. The response MUST NOT be cryptographically protected and - MUST contain a Notify payload indicating INVALID_IKE_SPI. - - A node receiving such an unprotected Notify payload MUST NOT respond - and MUST NOT change the state of any existing SAs. The message might - be a forgery or might be a response the genuine correspondent was - - - -Kaufman Standards Track [Page 36] - -RFC 4306 IKEv2 December 2005 - - - tricked into sending. A node SHOULD treat such a message (and also a - network message like ICMP destination unreachable) as a hint that - there might be problems with SAs to that IP address and SHOULD - initiate a liveness test for any such IKE_SA. An implementation - SHOULD limit the frequency of such tests to avoid being tricked into - participating in a denial of service attack. - - A node receiving a suspicious message from an IP address with which - it has an IKE_SA MAY send an IKE Notify payload in an IKE - INFORMATIONAL exchange over that SA. The recipient MUST NOT change - the state of any SA's as a result but SHOULD audit the event to aid - in diagnosing malfunctions. A node MUST limit the rate at which it - will send messages in response to unprotected messages. - -2.22. IPComp - - Use of IP compression [IPCOMP] can be negotiated as part of the setup - of a CHILD_SA. While IP compression involves an extra header in each - packet and a compression parameter index (CPI), the virtual - "compression association" has no life outside the ESP or AH SA that - contains it. Compression associations disappear when the - corresponding ESP or AH SA goes away. It is not explicitly mentioned - in any DELETE payload. - - Negotiation of IP compression is separate from the negotiation of - cryptographic parameters associated with a CHILD_SA. A node - requesting a CHILD_SA MAY advertise its support for one or more - compression algorithms through one or more Notify payloads of type - IPCOMP_SUPPORTED. The response MAY indicate acceptance of a single - compression algorithm with a Notify payload of type IPCOMP_SUPPORTED. - These payloads MUST NOT occur in messages that do not contain SA - payloads. - - Although there has been discussion of allowing multiple compression - algorithms to be accepted and to have different compression - algorithms available for the two directions of a CHILD_SA, - implementations of this specification MUST NOT accept an IPComp - algorithm that was not proposed, MUST NOT accept more than one, and - MUST NOT compress using an algorithm other than one proposed and - accepted in the setup of the CHILD_SA. - - A side effect of separating the negotiation of IPComp from - cryptographic parameters is that it is not possible to propose - multiple cryptographic suites and propose IP compression with some of - them but not others. - - - - - - -Kaufman Standards Track [Page 37] - -RFC 4306 IKEv2 December 2005 - - -2.23. NAT Traversal - - Network Address Translation (NAT) gateways are a controversial - subject. This section briefly describes what they are and how they - are likely to act on IKE traffic. Many people believe that NATs are - evil and that we should not design our protocols so as to make them - work better. IKEv2 does specify some unintuitive processing rules in - order that NATs are more likely to work. - - NATs exist primarily because of the shortage of IPv4 addresses, - though there are other rationales. IP nodes that are "behind" a NAT - have IP addresses that are not globally unique, but rather are - assigned from some space that is unique within the network behind the - NAT but that are likely to be reused by nodes behind other NATs. - Generally, nodes behind NATs can communicate with other nodes behind - the same NAT and with nodes with globally unique addresses, but not - with nodes behind other NATs. There are exceptions to that rule. - When those nodes make connections to nodes on the real Internet, the - NAT gateway "translates" the IP source address to an address that - will be routed back to the gateway. Messages to the gateway from the - Internet have their destination addresses "translated" to the - internal address that will route the packet to the correct endnode. - - NATs are designed to be "transparent" to endnodes. Neither software - on the node behind the NAT nor the node on the Internet requires - modification to communicate through the NAT. Achieving this - transparency is more difficult with some protocols than with others. - Protocols that include IP addresses of the endpoints within the - payloads of the packet will fail unless the NAT gateway understands - the protocol and modifies the internal references as well as those in - the headers. Such knowledge is inherently unreliable, is a network - layer violation, and often results in subtle problems. - - Opening an IPsec connection through a NAT introduces special - problems. If the connection runs in transport mode, changing the IP - addresses on packets will cause the checksums to fail and the NAT - cannot correct the checksums because they are cryptographically - protected. Even in tunnel mode, there are routing problems because - transparently translating the addresses of AH and ESP packets - requires special logic in the NAT and that logic is heuristic and - unreliable in nature. For that reason, IKEv2 can negotiate UDP - encapsulation of IKE and ESP packets. This encoding is slightly less - efficient but is easier for NATs to process. In addition, firewalls - may be configured to pass IPsec traffic over UDP but not ESP/AH or - vice versa. - - - - - - -Kaufman Standards Track [Page 38] - -RFC 4306 IKEv2 December 2005 - - - It is a common practice of NATs to translate TCP and UDP port numbers - as well as addresses and use the port numbers of inbound packets to - decide which internal node should get a given packet. For this - reason, even though IKE packets MUST be sent from and to UDP port - 500, they MUST be accepted coming from any port and responses MUST be - sent to the port from whence they came. This is because the ports - may be modified as the packets pass through NATs. Similarly, IP - addresses of the IKE endpoints are generally not included in the IKE - payloads because the payloads are cryptographically protected and - could not be transparently modified by NATs. - - Port 4500 is reserved for UDP-encapsulated ESP and IKE. When working - through a NAT, it is generally better to pass IKE packets over port - 4500 because some older NATs handle IKE traffic on port 500 cleverly - in an attempt to transparently establish IPsec connections between - endpoints that don't handle NAT traversal themselves. Such NATs may - interfere with the straightforward NAT traversal envisioned by this - document, so an IPsec endpoint that discovers a NAT between it and - its correspondent MUST send all subsequent traffic to and from port - 4500, which NATs should not treat specially (as they might with port - 500). - - The specific requirements for supporting NAT traversal [RFC3715] are - listed below. Support for NAT traversal is optional. In this - section only, requirements listed as MUST apply only to - implementations supporting NAT traversal. - - IKE MUST listen on port 4500 as well as port 500. IKE MUST - respond to the IP address and port from which packets arrived. - - Both IKE initiator and responder MUST include in their IKE_SA_INIT - packets Notify payloads of type NAT_DETECTION_SOURCE_IP and - NAT_DETECTION_DESTINATION_IP. Those payloads can be used to - detect if there is NAT between the hosts, and which end is behind - the NAT. The location of the payloads in the IKE_SA_INIT packets - are just after the Ni and Nr payloads (before the optional CERTREQ - payload). - - If none of the NAT_DETECTION_SOURCE_IP payload(s) received matches - the hash of the source IP and port found from the IP header of the - packet containing the payload, it means that the other end is - behind NAT (i.e., someone along the route changed the source - address of the original packet to match the address of the NAT - box). In this case, this end should allow dynamic update of the - other ends IP address, as described later. - - - - - - -Kaufman Standards Track [Page 39] - -RFC 4306 IKEv2 December 2005 - - - If the NAT_DETECTION_DESTINATION_IP payload received does not - match the hash of the destination IP and port found from the IP - header of the packet containing the payload, it means that this - end is behind a NAT. In this case, this end SHOULD start sending - keepalive packets as explained in [Hutt05]. - - The IKE initiator MUST check these payloads if present and if they - do not match the addresses in the outer packet MUST tunnel all - future IKE and ESP packets associated with this IKE_SA over UDP - port 4500. - - To tunnel IKE packets over UDP port 4500, the IKE header has four - octets of zero prepended and the result immediately follows the - UDP header. To tunnel ESP packets over UDP port 4500, the ESP - header immediately follows the UDP header. Since the first four - bytes of the ESP header contain the SPI, and the SPI cannot - validly be zero, it is always possible to distinguish ESP and IKE - messages. - - The original source and destination IP address required for the - transport mode TCP and UDP packet checksum fixup (see [Hutt05]) - are obtained from the Traffic Selectors associated with the - exchange. In the case of NAT traversal, the Traffic Selectors - MUST contain exactly one IP address, which is then used as the - original IP address. - - There are cases where a NAT box decides to remove mappings that - are still alive (for example, the keepalive interval is too long, - or the NAT box is rebooted). To recover in these cases, hosts - that are not behind a NAT SHOULD send all packets (including - retransmission packets) to the IP address and port from the last - valid authenticated packet from the other end (i.e., dynamically - update the address). A host behind a NAT SHOULD NOT do this - because it opens a DoS attack possibility. Any authenticated IKE - packet or any authenticated UDP-encapsulated ESP packet can be - used to detect that the IP address or the port has changed. - - Note that similar but probably not identical actions will likely - be needed to make IKE work with Mobile IP, but such processing is - not addressed by this document. - -2.24. Explicit Congestion Notification (ECN) - - When IPsec tunnels behave as originally specified in [RFC2401], ECN - usage is not appropriate for the outer IP headers because tunnel - decapsulation processing discards ECN congestion indications to the - detriment of the network. ECN support for IPsec tunnels for IKEv1- - based IPsec requires multiple operating modes and negotiation (see - - - -Kaufman Standards Track [Page 40] - -RFC 4306 IKEv2 December 2005 - - - [RFC3168]). IKEv2 simplifies this situation by requiring that ECN be - usable in the outer IP headers of all tunnel-mode IPsec SAs created - by IKEv2. Specifically, tunnel encapsulators and decapsulators for - all tunnel-mode SAs created by IKEv2 MUST support the ECN full- - functionality option for tunnels specified in [RFC3168] and MUST - implement the tunnel encapsulation and decapsulation processing - specified in [RFC4301] to prevent discarding of ECN congestion - indications. - -3. Header and Payload Formats - -3.1. The IKE Header - - IKE messages use UDP ports 500 and/or 4500, with one IKE message per - UDP datagram. Information from the beginning of the packet through - the UDP header is largely ignored except that the IP addresses and - UDP ports from the headers are reversed and used for return packets. - When sent on UDP port 500, IKE messages begin immediately following - the UDP header. When sent on UDP port 4500, IKE messages have - prepended four octets of zero. These four octets of zero are not - part of the IKE message and are not included in any of the length - fields or checksums defined by IKE. Each IKE message begins with the - IKE header, denoted HDR in this memo. Following the header are one - or more IKE payloads each identified by a "Next Payload" field in the - preceding payload. Payloads are processed in the order in which they - appear in an IKE message by invoking the appropriate processing - routine according to the "Next Payload" field in the IKE header and - subsequently according to the "Next Payload" field in the IKE payload - itself until a "Next Payload" field of zero indicates that no - payloads follow. If a payload of type "Encrypted" is found, that - payload is decrypted and its contents parsed as additional payloads. - An Encrypted payload MUST be the last payload in a packet and an - Encrypted payload MUST NOT contain another Encrypted payload. - - The Recipient SPI in the header identifies an instance of an IKE - security association. It is therefore possible for a single instance - of IKE to multiplex distinct sessions with multiple peers. - - All multi-octet fields representing integers are laid out in big - endian order (aka most significant byte first, or network byte - order). - - The format of the IKE header is shown in Figure 4. - - - - - - - - -Kaufman Standards Track [Page 41] - -RFC 4306 IKEv2 December 2005 - - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! IKE_SA Initiator's SPI ! - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! IKE_SA Responder's SPI ! - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload ! MjVer ! MnVer ! Exchange Type ! Flags ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Message ID ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 4: IKE Header Format - - o Initiator's SPI (8 octets) - A value chosen by the - initiator to identify a unique IKE security association. This - value MUST NOT be zero. - - o Responder's SPI (8 octets) - A value chosen by the - responder to identify a unique IKE security association. This - value MUST be zero in the first message of an IKE Initial - Exchange (including repeats of that message including a - cookie) and MUST NOT be zero in any other message. - - o Next Payload (1 octet) - Indicates the type of payload that - immediately follows the header. The format and value of each - payload are defined below. - - o Major Version (4 bits) - Indicates the major version of the IKE - protocol in use. Implementations based on this version of IKE - MUST set the Major Version to 2. Implementations based on - previous versions of IKE and ISAKMP MUST set the Major Version - to 1. Implementations based on this version of IKE MUST reject - or ignore messages containing a version number greater than - 2. - - o Minor Version (4 bits) - Indicates the minor version of the - IKE protocol in use. Implementations based on this version of - IKE MUST set the Minor Version to 0. They MUST ignore the - minor version number of received messages. - - o Exchange Type (1 octet) - Indicates the type of exchange being - used. This constrains the payloads sent in each message and - orderings of messages in an exchange. - - - -Kaufman Standards Track [Page 42] - -RFC 4306 IKEv2 December 2005 - - - Exchange Type Value - - RESERVED 0-33 - IKE_SA_INIT 34 - IKE_AUTH 35 - CREATE_CHILD_SA 36 - INFORMATIONAL 37 - RESERVED TO IANA 38-239 - Reserved for private use 240-255 - - o Flags (1 octet) - Indicates specific options that are set - for the message. Presence of options are indicated by the - appropriate bit in the flags field being set. The bits are - defined LSB first, so bit 0 would be the least significant - bit of the Flags octet. In the description below, a bit - being 'set' means its value is '1', while 'cleared' means - its value is '0'. - - -- X(reserved) (bits 0-2) - These bits MUST be cleared - when sending and MUST be ignored on receipt. - - -- I(nitiator) (bit 3 of Flags) - This bit MUST be set in - messages sent by the original initiator of the IKE_SA - and MUST be cleared in messages sent by the original - responder. It is used by the recipient to determine - which eight octets of the SPI were generated by the - recipient. - - -- V(ersion) (bit 4 of Flags) - This bit indicates that - the transmitter is capable of speaking a higher major - version number of the protocol than the one indicated - in the major version number field. Implementations of - IKEv2 must clear this bit when sending and MUST ignore - it in incoming messages. - - -- R(esponse) (bit 5 of Flags) - This bit indicates that - this message is a response to a message containing - the same message ID. This bit MUST be cleared in all - request messages and MUST be set in all responses. - An IKE endpoint MUST NOT generate a response to a - message that is marked as being a response. - - -- X(reserved) (bits 6-7 of Flags) - These bits MUST be - cleared when sending and MUST be ignored on receipt. - - - - - - - -Kaufman Standards Track [Page 43] - -RFC 4306 IKEv2 December 2005 - - - o Message ID (4 octets) - Message identifier used to control - retransmission of lost packets and matching of requests and - responses. It is essential to the security of the protocol - because it is used to prevent message replay attacks. - See sections 2.1 and 2.2. - - o Length (4 octets) - Length of total message (header + payloads) - in octets. - -3.2. Generic Payload Header - - Each IKE payload defined in sections 3.3 through 3.16 begins with a - generic payload header, shown in Figure 5. Figures for each payload - below will include the generic payload header, but for brevity the - description of each field will be omitted. - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload !C! RESERVED ! Payload Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 5: Generic Payload Header - - The Generic Payload Header fields are defined as follows: - - o Next Payload (1 octet) - Identifier for the payload type of the - next payload in the message. If the current payload is the last - in the message, then this field will be 0. This field provides a - "chaining" capability whereby additional payloads can be added to - a message by appending it to the end of the message and setting - the "Next Payload" field of the preceding payload to indicate the - new payload's type. An Encrypted payload, which must always be - the last payload of a message, is an exception. It contains data - structures in the format of additional payloads. In the header of - an Encrypted payload, the Next Payload field is set to the payload - type of the first contained payload (instead of 0). - - Payload Type Values - - Next Payload Type Notation Value - - No Next Payload 0 - - RESERVED 1-32 - Security Association SA 33 - Key Exchange KE 34 - Identification - Initiator IDi 35 - - - -Kaufman Standards Track [Page 44] - -RFC 4306 IKEv2 December 2005 - - - Identification - Responder IDr 36 - Certificate CERT 37 - Certificate Request CERTREQ 38 - Authentication AUTH 39 - Nonce Ni, Nr 40 - Notify N 41 - Delete D 42 - Vendor ID V 43 - Traffic Selector - Initiator TSi 44 - Traffic Selector - Responder TSr 45 - Encrypted E 46 - Configuration CP 47 - Extensible Authentication EAP 48 - RESERVED TO IANA 49-127 - PRIVATE USE 128-255 - - Payload type values 1-32 should not be used so that there is no - overlap with the code assignments for IKEv1. Payload type values - 49-127 are reserved to IANA for future assignment in IKEv2 (see - section 6). Payload type values 128-255 are for private use among - mutually consenting parties. - - o Critical (1 bit) - MUST be set to zero if the sender wants the - recipient to skip this payload if it does not understand the - payload type code in the Next Payload field of the previous - payload. MUST be set to one if the sender wants the recipient to - reject this entire message if it does not understand the payload - type. MUST be ignored by the recipient if the recipient - understands the payload type code. MUST be set to zero for - payload types defined in this document. Note that the critical - bit applies to the current payload rather than the "next" payload - whose type code appears in the first octet. The reasoning behind - not setting the critical bit for payloads defined in this document - is that all implementations MUST understand all payload types - defined in this document and therefore must ignore the Critical - bit's value. Skipped payloads are expected to have valid Next - Payload and Payload Length fields. - - o RESERVED (7 bits) - MUST be sent as zero; MUST be ignored on - receipt. - - o Payload Length (2 octets) - Length in octets of the current - payload, including the generic payload header. - - - - - - - - -Kaufman Standards Track [Page 45] - -RFC 4306 IKEv2 December 2005 - - -3.3. Security Association Payload - - The Security Association Payload, denoted SA in this memo, is used to - negotiate attributes of a security association. Assembly of Security - Association Payloads requires great peace of mind. An SA payload MAY - contain multiple proposals. If there is more than one, they MUST be - ordered from most preferred to least preferred. Each proposal may - contain multiple IPsec protocols (where a protocol is IKE, ESP, or - AH), each protocol MAY contain multiple transforms, and each - transform MAY contain multiple attributes. When parsing an SA, an - implementation MUST check that the total Payload Length is consistent - with the payload's internal lengths and counts. Proposals, - Transforms, and Attributes each have their own variable length - encodings. They are nested such that the Payload Length of an SA - includes the combined contents of the SA, Proposal, Transform, and - Attribute information. The length of a Proposal includes the lengths - of all Transforms and Attributes it contains. The length of a - Transform includes the lengths of all Attributes it contains. - - The syntax of Security Associations, Proposals, Transforms, and - Attributes is based on ISAKMP; however, the semantics are somewhat - different. The reason for the complexity and the hierarchy is to - allow for multiple possible combinations of algorithms to be encoded - in a single SA. Sometimes there is a choice of multiple algorithms, - whereas other times there is a combination of algorithms. For - example, an initiator might want to propose using (AH w/MD5 and ESP - w/3DES) OR (ESP w/MD5 and 3DES). - - One of the reasons the semantics of the SA payload has changed from - ISAKMP and IKEv1 is to make the encodings more compact in common - cases. - - The Proposal structure contains within it a Proposal # and an IPsec - protocol ID. Each structure MUST have the same Proposal # as the - previous one or be one (1) greater. The first Proposal MUST have a - Proposal # of one (1). If two successive structures have the same - Proposal number, it means that the proposal consists of the first - structure AND the second. So a proposal of AH AND ESP would have two - proposal structures, one for AH and one for ESP and both would have - Proposal #1. A proposal of AH OR ESP would have two proposal - structures, one for AH with Proposal #1 and one for ESP with Proposal - #2. - - Each Proposal/Protocol structure is followed by one or more transform - structures. The number of different transforms is generally - determined by the Protocol. AH generally has a single transform: an - integrity check algorithm. ESP generally has two: an encryption - algorithm and an integrity check algorithm. IKE generally has four - - - -Kaufman Standards Track [Page 46] - -RFC 4306 IKEv2 December 2005 - - - transforms: a Diffie-Hellman group, an integrity check algorithm, a - prf algorithm, and an encryption algorithm. If an algorithm that - combines encryption and integrity protection is proposed, it MUST be - proposed as an encryption algorithm and an integrity protection - algorithm MUST NOT be proposed. For each Protocol, the set of - permissible transforms is assigned transform ID numbers, which appear - in the header of each transform. - - If there are multiple transforms with the same Transform Type, the - proposal is an OR of those transforms. If there are multiple - Transforms with different Transform Types, the proposal is an AND of - the different groups. For example, to propose ESP with (3DES or - IDEA) and (HMAC_MD5 or HMAC_SHA), the ESP proposal would contain two - Transform Type 1 candidates (one for 3DES and one for IDEA) and two - Transform Type 2 candidates (one for HMAC_MD5 and one for HMAC_SHA). - This effectively proposes four combinations of algorithms. If the - initiator wanted to propose only a subset of those, for example (3DES - and HMAC_MD5) or (IDEA and HMAC_SHA), there is no way to encode that - as multiple transforms within a single Proposal. Instead, the - initiator would have to construct two different Proposals, each with - two transforms. - - A given transform MAY have one or more Attributes. Attributes are - necessary when the transform can be used in more than one way, as - when an encryption algorithm has a variable key size. The transform - would specify the algorithm and the attribute would specify the key - size. Most transforms do not have attributes. A transform MUST NOT - have multiple attributes of the same type. To propose alternate - values for an attribute (for example, multiple key sizes for the AES - encryption algorithm), and implementation MUST include multiple - Transforms with the same Transform Type each with a single Attribute. - - Note that the semantics of Transforms and Attributes are quite - different from those in IKEv1. In IKEv1, a single Transform carried - multiple algorithms for a protocol with one carried in the Transform - and the others carried in the Attributes. - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload !C! RESERVED ! Payload Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ <Proposals> ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 6: Security Association Payload - - - -Kaufman Standards Track [Page 47] - -RFC 4306 IKEv2 December 2005 - - - o Proposals (variable) - One or more proposal substructures. - - The payload type for the Security Association Payload is thirty - three (33). - -3.3.1. Proposal Substructure - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! 0 (last) or 2 ! RESERVED ! Proposal Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Proposal # ! Protocol ID ! SPI Size !# of Transforms! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ~ SPI (variable) ~ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ <Transforms> ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 7: Proposal Substructure - - o 0 (last) or 2 (more) (1 octet) - Specifies whether this is the - last Proposal Substructure in the SA. This syntax is inherited - from ISAKMP, but is unnecessary because the last Proposal could - be identified from the length of the SA. The value (2) - corresponds to a Payload Type of Proposal in IKEv1, and the - first 4 octets of the Proposal structure are designed to look - somewhat like the header of a Payload. - - o RESERVED (1 octet) - MUST be sent as zero; MUST be ignored on - receipt. - - o Proposal Length (2 octets) - Length of this proposal, including - all transforms and attributes that follow. - - o Proposal # (1 octet) - When a proposal is made, the first - proposal in an SA payload MUST be #1, and subsequent proposals - MUST either be the same as the previous proposal (indicating an - AND of the two proposals) or one more than the previous - proposal (indicating an OR of the two proposals). When a - proposal is accepted, all of the proposal numbers in the SA - payload MUST be the same and MUST match the number on the - proposal sent that was accepted. - - - - - - -Kaufman Standards Track [Page 48] - -RFC 4306 IKEv2 December 2005 - - - o Protocol ID (1 octet) - Specifies the IPsec protocol identifier - for the current negotiation. The defined values are: - - Protocol Protocol ID - RESERVED 0 - IKE 1 - AH 2 - ESP 3 - RESERVED TO IANA 4-200 - PRIVATE USE 201-255 - - o SPI Size (1 octet) - For an initial IKE_SA negotiation, this - field MUST be zero; the SPI is obtained from the outer header. - During subsequent negotiations, it is equal to the size, in - octets, of the SPI of the corresponding protocol (8 for IKE, 4 - for ESP and AH). - - o # of Transforms (1 octet) - Specifies the number of transforms - in this proposal. - - o SPI (variable) - The sending entity's SPI. Even if the SPI Size - is not a multiple of 4 octets, there is no padding applied to - the payload. When the SPI Size field is zero, this field is - not present in the Security Association payload. - - o Transforms (variable) - One or more transform substructures. - -3.3.2. Transform Substructure - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! 0 (last) or 3 ! RESERVED ! Transform Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - !Transform Type ! RESERVED ! Transform ID ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ Transform Attributes ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 8: Transform Substructure - - o 0 (last) or 3 (more) (1 octet) - Specifies whether this is the - last Transform Substructure in the Proposal. This syntax is - inherited from ISAKMP, but is unnecessary because the last - Proposal could be identified from the length of the SA. The - - - - -Kaufman Standards Track [Page 49] - -RFC 4306 IKEv2 December 2005 - - - value (3) corresponds to a Payload Type of Transform in IKEv1, - and the first 4 octets of the Transform structure are designed - to look somewhat like the header of a Payload. - - o RESERVED - MUST be sent as zero; MUST be ignored on receipt. - - o Transform Length - The length (in octets) of the Transform - Substructure including Header and Attributes. - - o Transform Type (1 octet) - The type of transform being - specified in this transform. Different protocols support - different transform types. For some protocols, some of the - transforms may be optional. If a transform is optional and the - initiator wishes to propose that the transform be omitted, no - transform of the given type is included in the proposal. If - the initiator wishes to make use of the transform optional to - the responder, it includes a transform substructure with - transform ID = 0 as one of the options. - - o Transform ID (2 octets) - The specific instance of the - transform type being proposed. - - Transform Type Values - - Transform Used In - Type - RESERVED 0 - Encryption Algorithm (ENCR) 1 (IKE and ESP) - Pseudo-random Function (PRF) 2 (IKE) - Integrity Algorithm (INTEG) 3 (IKE, AH, optional in ESP) - Diffie-Hellman Group (D-H) 4 (IKE, optional in AH & ESP) - Extended Sequence Numbers (ESN) 5 (AH and ESP) - RESERVED TO IANA 6-240 - PRIVATE USE 241-255 - - For Transform Type 1 (Encryption Algorithm), defined Transform IDs - are: - - Name Number Defined In - RESERVED 0 - ENCR_DES_IV64 1 (RFC1827) - ENCR_DES 2 (RFC2405), [DES] - ENCR_3DES 3 (RFC2451) - ENCR_RC5 4 (RFC2451) - ENCR_IDEA 5 (RFC2451), [IDEA] - ENCR_CAST 6 (RFC2451) - ENCR_BLOWFISH 7 (RFC2451) - ENCR_3IDEA 8 (RFC2451) - - - -Kaufman Standards Track [Page 50] - -RFC 4306 IKEv2 December 2005 - - - ENCR_DES_IV32 9 - RESERVED 10 - ENCR_NULL 11 (RFC2410) - ENCR_AES_CBC 12 (RFC3602) - ENCR_AES_CTR 13 (RFC3664) - - values 14-1023 are reserved to IANA. Values 1024-65535 are - for private use among mutually consenting parties. - - For Transform Type 2 (Pseudo-random Function), defined Transform IDs - are: - - Name Number Defined In - RESERVED 0 - PRF_HMAC_MD5 1 (RFC2104), [MD5] - PRF_HMAC_SHA1 2 (RFC2104), [SHA] - PRF_HMAC_TIGER 3 (RFC2104) - PRF_AES128_XCBC 4 (RFC3664) - - values 5-1023 are reserved to IANA. Values 1024-65535 are for - private use among mutually consenting parties. - - For Transform Type 3 (Integrity Algorithm), defined Transform IDs - are: - - Name Number Defined In - NONE 0 - AUTH_HMAC_MD5_96 1 (RFC2403) - AUTH_HMAC_SHA1_96 2 (RFC2404) - AUTH_DES_MAC 3 - AUTH_KPDK_MD5 4 (RFC1826) - AUTH_AES_XCBC_96 5 (RFC3566) - - values 6-1023 are reserved to IANA. Values 1024-65535 are for - private use among mutually consenting parties. - - For Transform Type 4 (Diffie-Hellman Group), defined Transform IDs - are: - - Name Number - NONE 0 - Defined in Appendix B 1 - 2 - RESERVED 3 - 4 - Defined in [ADDGROUP] 5 - RESERVED TO IANA 6 - 13 - Defined in [ADDGROUP] 14 - 18 - RESERVED TO IANA 19 - 1023 - PRIVATE USE 1024-65535 - - - -Kaufman Standards Track [Page 51] - -RFC 4306 IKEv2 December 2005 - - - For Transform Type 5 (Extended Sequence Numbers), defined Transform - IDs are: - - Name Number - No Extended Sequence Numbers 0 - Extended Sequence Numbers 1 - RESERVED 2 - 65535 - -3.3.3. Valid Transform Types by Protocol - - The number and type of transforms that accompany an SA payload are - dependent on the protocol in the SA itself. An SA payload proposing - the establishment of an SA has the following mandatory and optional - transform types. A compliant implementation MUST understand all - mandatory and optional types for each protocol it supports (though it - need not accept proposals with unacceptable suites). A proposal MAY - omit the optional types if the only value for them it will accept is - NONE. - - Protocol Mandatory Types Optional Types - IKE ENCR, PRF, INTEG, D-H - ESP ENCR, ESN INTEG, D-H - AH INTEG, ESN D-H - -3.3.4. Mandatory Transform IDs - - The specification of suites that MUST and SHOULD be supported for - interoperability has been removed from this document because they are - likely to change more rapidly than this document evolves. - - An important lesson learned from IKEv1 is that no system should only - implement the mandatory algorithms and expect them to be the best - choice for all customers. For example, at the time that this - document was written, many IKEv1 implementers were starting to - migrate to AES in Cipher Block Chaining (CBC) mode for Virtual - Private Network (VPN) applications. Many IPsec systems based on - IKEv2 will implement AES, additional Diffie-Hellman groups, and - additional hash algorithms, and some IPsec customers already require - these algorithms in addition to the ones listed above. - - It is likely that IANA will add additional transforms in the future, - and some users may want to use private suites, especially for IKE - where implementations should be capable of supporting different - parameters, up to certain size limits. In support of this goal, all - implementations of IKEv2 SHOULD include a management facility that - allows specification (by a user or system administrator) of Diffie- - Hellman (DH) parameters (the generator, modulus, and exponent lengths - and values) for new DH groups. Implementations SHOULD provide a - - - -Kaufman Standards Track [Page 52] - -RFC 4306 IKEv2 December 2005 - - - management interface via which these parameters and the associated - transform IDs may be entered (by a user or system administrator), to - enable negotiating such groups. - - All implementations of IKEv2 MUST include a management facility that - enables a user or system administrator to specify the suites that are - acceptable for use with IKE. Upon receipt of a payload with a set of - transform IDs, the implementation MUST compare the transmitted - transform IDs against those locally configured via the management - controls, to verify that the proposed suite is acceptable based on - local policy. The implementation MUST reject SA proposals that are - not authorized by these IKE suite controls. Note that cryptographic - suites that MUST be implemented need not be configured as acceptable - to local policy. - -3.3.5. Transform Attributes - - Each transform in a Security Association payload may include - attributes that modify or complete the specification of the - transform. These attributes are type/value pairs and are defined - below. For example, if an encryption algorithm has a variable-length - key, the key length to be used may be specified as an attribute. - Attributes can have a value with a fixed two octet length or a - variable-length value. For the latter, the attribute is encoded as - type/length/value. - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - !A! Attribute Type ! AF=0 Attribute Length ! - !F! ! AF=1 Attribute Value ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! AF=0 Attribute Value ! - ! AF=1 Not Transmitted ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 9: Data Attributes - - o Attribute Type (2 octets) - Unique identifier for each type of - attribute (see below). - - The most significant bit of this field is the Attribute Format - bit (AF). It indicates whether the data attributes follow the - Type/Length/Value (TLV) format or a shortened Type/Value (TV) - format. If the AF bit is zero (0), then the Data Attributes - are of the Type/Length/Value (TLV) form. If the AF bit is a - one (1), then the Data Attributes are of the Type/Value form. - - - - -Kaufman Standards Track [Page 53] - -RFC 4306 IKEv2 December 2005 - - - o Attribute Length (2 octets) - Length in octets of the Attribute - Value. When the AF bit is a one (1), the Attribute Value is - only 2 octets and the Attribute Length field is not present. - - o Attribute Value (variable length) - Value of the Attribute - associated with the Attribute Type. If the AF bit is a zero - (0), this field has a variable length defined by the Attribute - Length field. If the AF bit is a one (1), the Attribute Value - has a length of 2 octets. - - Note that only a single attribute type (Key Length) is defined, and - it is fixed length. The variable-length encoding specification is - included only for future extensions. The only algorithms defined in - this document that accept attributes are the AES-based encryption, - integrity, and pseudo-random functions, which require a single - attribute specifying key width. - - Attributes described as basic MUST NOT be encoded using the - variable-length encoding. Variable-length attributes MUST NOT be - encoded as basic even if their value can fit into two octets. NOTE: - This is a change from IKEv1, where increased flexibility may have - simplified the composer of messages but certainly complicated the - parser. - - Attribute Type Value Attribute Format - -------------------------------------------------------------- - RESERVED 0-13 Key Length (in bits) - 14 TV RESERVED 15-17 - RESERVED TO IANA 18-16383 PRIVATE USE - 16384-32767 - - Values 0-13 and 15-17 were used in a similar context in IKEv1 and - should not be assigned except to matching values. Values 18-16383 - are reserved to IANA. Values 16384-32767 are for private use among - mutually consenting parties. - - - Key Length - - When using an Encryption Algorithm that has a variable-length key, - this attribute specifies the key length in bits (MUST use network - byte order). This attribute MUST NOT be used when the specified - Encryption Algorithm uses a fixed-length key. - - - - - - - - - -Kaufman Standards Track [Page 54] - -RFC 4306 IKEv2 December 2005 - - -3.3.6. Attribute Negotiation - - During security association negotiation, initiators present offers to - responders. Responders MUST select a single complete set of - parameters from the offers (or reject all offers if none are - acceptable). If there are multiple proposals, the responder MUST - choose a single proposal number and return all of the Proposal - substructures with that Proposal number. If there are multiple - Transforms with the same type, the responder MUST choose a single - one. Any attributes of a selected transform MUST be returned - unmodified. The initiator of an exchange MUST check that the - accepted offer is consistent with one of its proposals, and if not - that response MUST be rejected. - - Negotiating Diffie-Hellman groups presents some special challenges. - SA offers include proposed attributes and a Diffie-Hellman public - number (KE) in the same message. If in the initial exchange the - initiator offers to use one of several Diffie-Hellman groups, it - SHOULD pick the one the responder is most likely to accept and - include a KE corresponding to that group. If the guess turns out to - be wrong, the responder will indicate the correct group in the - response and the initiator SHOULD pick an element of that group for - its KE value when retrying the first message. It SHOULD, however, - continue to propose its full supported set of groups in order to - prevent a man-in-the-middle downgrade attack. - - Implementation Note: - - Certain negotiable attributes can have ranges or could have - multiple acceptable values. These include the key length of a - variable key length symmetric cipher. To further interoperability - and to support upgrading endpoints independently, implementers of - this protocol SHOULD accept values that they deem to supply - greater security. For instance, if a peer is configured to accept - a variable-length cipher with a key length of X bits and is - offered that cipher with a larger key length, the implementation - SHOULD accept the offer if it supports use of the longer key. - - Support of this capability allows an implementation to express a - concept of "at least" a certain level of security -- "a key length of - _at least_ X bits for cipher Y". - - - - - - - - - - -Kaufman Standards Track [Page 55] - -RFC 4306 IKEv2 December 2005 - - -3.4. Key Exchange Payload - - The Key Exchange Payload, denoted KE in this memo, is used to - exchange Diffie-Hellman public numbers as part of a Diffie-Hellman - key exchange. The Key Exchange Payload consists of the IKE generic - payload header followed by the Diffie-Hellman public value itself. - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload !C! RESERVED ! Payload Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! DH Group # ! RESERVED ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ Key Exchange Data ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 10: Key Exchange Payload Format - - A key exchange payload is constructed by copying one's Diffie-Hellman - public value into the "Key Exchange Data" portion of the payload. - The length of the Diffie-Hellman public value MUST be equal to the - length of the prime modulus over which the exponentiation was - performed, prepending zero bits to the value if necessary. - - The DH Group # identifies the Diffie-Hellman group in which the Key - Exchange Data was computed (see section 3.3.2). If the selected - proposal uses a different Diffie-Hellman group, the message MUST be - rejected with a Notify payload of type INVALID_KE_PAYLOAD. - - The payload type for the Key Exchange payload is thirty four (34). - -3.5. Identification Payloads - - The Identification Payloads, denoted IDi and IDr in this memo, allow - peers to assert an identity to one another. This identity may be - used for policy lookup, but does not necessarily have to match - anything in the CERT payload; both fields may be used by an - implementation to perform access control decisions. - - NOTE: In IKEv1, two ID payloads were used in each direction to hold - Traffic Selector (TS) information for data passing over the SA. In - IKEv2, this information is carried in TS payloads (see section 3.13). - - - - - - -Kaufman Standards Track [Page 56] - -RFC 4306 IKEv2 December 2005 - - - The Identification Payload consists of the IKE generic payload header - followed by identification fields as follows: - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload !C! RESERVED ! Payload Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ID Type ! RESERVED | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ Identification Data ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 11: Identification Payload Format - - o ID Type (1 octet) - Specifies the type of Identification being - used. - - o RESERVED - MUST be sent as zero; MUST be ignored on receipt. - - o Identification Data (variable length) - Value, as indicated by the - Identification Type. The length of the Identification Data is - computed from the size in the ID payload header. - - The payload types for the Identification Payload are thirty five (35) - for IDi and thirty six (36) for IDr. - - The following table lists the assigned values for the Identification - Type field, followed by a description of the Identification Data - which follows: - - ID Type Value - ------- ----- - RESERVED 0 - - ID_IPV4_ADDR 1 - - A single four (4) octet IPv4 address. - - ID_FQDN 2 - - A fully-qualified domain name string. An example of a - ID_FQDN is, "example.com". The string MUST not contain any - terminators (e.g., NULL, CR, etc.). - - - - - -Kaufman Standards Track [Page 57] - -RFC 4306 IKEv2 December 2005 - - - ID_RFC822_ADDR 3 - - A fully-qualified RFC822 email address string, An example of - a ID_RFC822_ADDR is, "jsmith@example.com". The string MUST - not contain any terminators. - - Reserved to IANA 4 - - ID_IPV6_ADDR 5 - - A single sixteen (16) octet IPv6 address. - - Reserved to IANA 6 - 8 - - ID_DER_ASN1_DN 9 - - The binary Distinguished Encoding Rules (DER) encoding of an - ASN.1 X.500 Distinguished Name [X.501]. - - ID_DER_ASN1_GN 10 - - The binary DER encoding of an ASN.1 X.500 GeneralName - [X.509]. - - ID_KEY_ID 11 - - An opaque octet stream which may be used to pass vendor- - specific information necessary to do certain proprietary - types of identification. - - Reserved to IANA 12-200 - - Reserved for private use 201-255 - - Two implementations will interoperate only if each can generate a - type of ID acceptable to the other. To assure maximum - interoperability, implementations MUST be configurable to send at - least one of ID_IPV4_ADDR, ID_FQDN, ID_RFC822_ADDR, or ID_KEY_ID, and - MUST be configurable to accept all of these types. Implementations - SHOULD be capable of generating and accepting all of these types. - IPv6-capable implementations MUST additionally be configurable to - accept ID_IPV6_ADDR. IPv6-only implementations MAY be configurable - to send only ID_IPV6_ADDR. - - - - - - - - -Kaufman Standards Track [Page 58] - -RFC 4306 IKEv2 December 2005 - - -3.6. Certificate Payload - - The Certificate Payload, denoted CERT in this memo, provides a means - to transport certificates or other authentication-related information - via IKE. Certificate payloads SHOULD be included in an exchange if - certificates are available to the sender unless the peer has - indicated an ability to retrieve this information from elsewhere - using an HTTP_CERT_LOOKUP_SUPPORTED Notify payload. Note that the - term "Certificate Payload" is somewhat misleading, because not all - authentication mechanisms use certificates and data other than - certificates may be passed in this payload. - - The Certificate Payload is defined as follows: - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload !C! RESERVED ! Payload Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Cert Encoding ! ! - +-+-+-+-+-+-+-+-+ ! - ~ Certificate Data ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 12: Certificate Payload Format - - o Certificate Encoding (1 octet) - This field indicates the type - of certificate or certificate-related information contained in - the Certificate Data field. - - Certificate Encoding Value - -------------------- ----- - RESERVED 0 - PKCS #7 wrapped X.509 certificate 1 - PGP Certificate 2 - DNS Signed Key 3 - X.509 Certificate - Signature 4 - Kerberos Token 6 - Certificate Revocation List (CRL) 7 - Authority Revocation List (ARL) 8 - SPKI Certificate 9 - X.509 Certificate - Attribute 10 - Raw RSA Key 11 - Hash and URL of X.509 certificate 12 - Hash and URL of X.509 bundle 13 - RESERVED to IANA 14 - 200 - PRIVATE USE 201 - 255 - - - -Kaufman Standards Track [Page 59] - -RFC 4306 IKEv2 December 2005 - - - o Certificate Data (variable length) - Actual encoding of - certificate data. The type of certificate is indicated by the - Certificate Encoding field. - - The payload type for the Certificate Payload is thirty seven (37). - - Specific syntax is for some of the certificate type codes above is - not defined in this document. The types whose syntax is defined in - this document are: - - X.509 Certificate - Signature (4) contains a DER encoded X.509 - certificate whose public key is used to validate the sender's AUTH - payload. - - Certificate Revocation List (7) contains a DER encoded X.509 - certificate revocation list. - - Raw RSA Key (11) contains a PKCS #1 encoded RSA key (see [RSA] and - [PKCS1]). - - Hash and URL encodings (12-13) allow IKE messages to remain short - by replacing long data structures with a 20 octet SHA-1 hash (see - [SHA]) of the replaced value followed by a variable-length URL - that resolves to the DER encoded data structure itself. This - improves efficiency when the endpoints have certificate data - cached and makes IKE less subject to denial of service attacks - that become easier to mount when IKE messages are large enough to - require IP fragmentation [KPS03]. - - Use the following ASN.1 definition for an X.509 bundle: - - CertBundle - { iso(1) identified-organization(3) dod(6) internet(1) - security(5) mechanisms(5) pkix(7) id-mod(0) - id-mod-cert-bundle(34) } - - DEFINITIONS EXPLICIT TAGS ::= - BEGIN - - IMPORTS - Certificate, CertificateList - FROM PKIX1Explicit88 - { iso(1) identified-organization(3) dod(6) - internet(1) security(5) mechanisms(5) pkix(7) - id-mod(0) id-pkix1-explicit(18) } ; - - - - - - -Kaufman Standards Track [Page 60] - -RFC 4306 IKEv2 December 2005 - - - CertificateOrCRL ::= CHOICE { - cert [0] Certificate, - crl [1] CertificateList } - - CertificateBundle ::= SEQUENCE OF CertificateOrCRL - - END - - Implementations MUST be capable of being configured to send and - accept up to four X.509 certificates in support of authentication, - and also MUST be capable of being configured to send and accept the - first two Hash and URL formats (with HTTP URLs). Implementations - SHOULD be capable of being configured to send and accept Raw RSA - keys. If multiple certificates are sent, the first certificate MUST - contain the public key used to sign the AUTH payload. The other - certificates may be sent in any order. - -3.7. Certificate Request Payload - - The Certificate Request Payload, denoted CERTREQ in this memo, - provides a means to request preferred certificates via IKE and can - appear in the IKE_INIT_SA response and/or the IKE_AUTH request. - Certificate Request payloads MAY be included in an exchange when the - sender needs to get the certificate of the receiver. If multiple CAs - are trusted and the cert encoding does not allow a list, then - multiple Certificate Request payloads SHOULD be transmitted. - - The Certificate Request Payload is defined as follows: - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload !C! RESERVED ! Payload Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Cert Encoding ! ! - +-+-+-+-+-+-+-+-+ ! - ~ Certification Authority ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 13: Certificate Request Payload Format - - o Certificate Encoding (1 octet) - Contains an encoding of the type - or format of certificate requested. Values are listed in section - 3.6. - - - - - - -Kaufman Standards Track [Page 61] - -RFC 4306 IKEv2 December 2005 - - - o Certification Authority (variable length) - Contains an encoding - of an acceptable certification authority for the type of - certificate requested. - - The payload type for the Certificate Request Payload is thirty eight - (38). - - The Certificate Encoding field has the same values as those defined - in section 3.6. The Certification Authority field contains an - indicator of trusted authorities for this certificate type. The - Certification Authority value is a concatenated list of SHA-1 hashes - of the public keys of trusted Certification Authorities (CAs). Each - is encoded as the SHA-1 hash of the Subject Public Key Info element - (see section 4.1.2.7 of [RFC3280]) from each Trust Anchor - certificate. The twenty-octet hashes are concatenated and included - with no other formatting. - - Note that the term "Certificate Request" is somewhat misleading, in - that values other than certificates are defined in a "Certificate" - payload and requests for those values can be present in a Certificate - Request Payload. The syntax of the Certificate Request payload in - such cases is not defined in this document. - - The Certificate Request Payload is processed by inspecting the "Cert - Encoding" field to determine whether the processor has any - certificates of this type. If so, the "Certification Authority" - field is inspected to determine if the processor has any certificates - that can be validated up to one of the specified certification - authorities. This can be a chain of certificates. - - If an end-entity certificate exists that satisfies the criteria - specified in the CERTREQ, a certificate or certificate chain SHOULD - be sent back to the certificate requestor if the recipient of the - CERTREQ: - - - is configured to use certificate authentication, - - - is allowed to send a CERT payload, - - - has matching CA trust policy governing the current negotiation, and - - - has at least one time-wise and usage appropriate end-entity - certificate chaining to a CA provided in the CERTREQ. - - Certificate revocation checking must be considered during the - chaining process used to select a certificate. Note that even if two - peers are configured to use two different CAs, cross-certification - relationships should be supported by appropriate selection logic. - - - -Kaufman Standards Track [Page 62] - -RFC 4306 IKEv2 December 2005 - - - The intent is not to prevent communication through the strict - adherence of selection of a certificate based on CERTREQ, when an - alternate certificate could be selected by the sender that would - still enable the recipient to successfully validate and trust it - through trust conveyed by cross-certification, CRLs, or other out- - of-band configured means. Thus, the processing of a CERTREQ should - be seen as a suggestion for a certificate to select, not a mandated - one. If no certificates exist, then the CERTREQ is ignored. This is - not an error condition of the protocol. There may be cases where - there is a preferred CA sent in the CERTREQ, but an alternate might - be acceptable (perhaps after prompting a human operator). - -3.8. Authentication Payload - - The Authentication Payload, denoted AUTH in this memo, contains data - used for authentication purposes. The syntax of the Authentication - data varies according to the Auth Method as specified below. - - The Authentication Payload is defined as follows: - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload !C! RESERVED ! Payload Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Auth Method ! RESERVED ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ Authentication Data ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 14: Authentication Payload Format - - o Auth Method (1 octet) - Specifies the method of authentication - used. Values defined are: - - RSA Digital Signature (1) - Computed as specified in section - 2.15 using an RSA private key over a PKCS#1 padded hash (see - [RSA] and [PKCS1]). - - Shared Key Message Integrity Code (2) - Computed as specified in - section 2.15 using the shared key associated with the identity - in the ID payload and the negotiated prf function - - DSS Digital Signature (3) - Computed as specified in section - 2.15 using a DSS private key (see [DSS]) over a SHA-1 hash. - - - - -Kaufman Standards Track [Page 63] - -RFC 4306 IKEv2 December 2005 - - - The values 0 and 4-200 are reserved to IANA. The values 201-255 - are available for private use. - - o Authentication Data (variable length) - see section 2.15. - - The payload type for the Authentication Payload is thirty nine (39). - -3.9. Nonce Payload - - The Nonce Payload, denoted Ni and Nr in this memo for the initiator's - and responder's nonce respectively, contains random data used to - guarantee liveness during an exchange and protect against replay - attacks. - - The Nonce Payload is defined as follows: - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload !C! RESERVED ! Payload Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ Nonce Data ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 15: Nonce Payload Format - - o Nonce Data (variable length) - Contains the random data generated - by the transmitting entity. - - The payload type for the Nonce Payload is forty (40). - - The size of a Nonce MUST be between 16 and 256 octets inclusive. - Nonce values MUST NOT be reused. - -3.10. Notify Payload - - The Notify Payload, denoted N in this document, is used to transmit - informational data, such as error conditions and state transitions, - to an IKE peer. A Notify Payload may appear in a response message - (usually specifying why a request was rejected), in an INFORMATIONAL - Exchange (to report an error not in an IKE request), or in any other - message to indicate sender capabilities or to modify the meaning of - the request. - - - - - - -Kaufman Standards Track [Page 64] - -RFC 4306 IKEv2 December 2005 - - - The Notify Payload is defined as follows: - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload !C! RESERVED ! Payload Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Protocol ID ! SPI Size ! Notify Message Type ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ Security Parameter Index (SPI) ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ Notification Data ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 16: Notify Payload Format - - o Protocol ID (1 octet) - If this notification concerns an existing - SA, this field indicates the type of that SA. For IKE_SA - notifications, this field MUST be one (1). For notifications - concerning IPsec SAs this field MUST contain either (2) to - indicate AH or (3) to indicate ESP. For notifications that do not - relate to an existing SA, this field MUST be sent as zero and MUST - be ignored on receipt. All other values for this field are - reserved to IANA for future assignment. - - o SPI Size (1 octet) - Length in octets of the SPI as defined by the - IPsec protocol ID or zero if no SPI is applicable. For a - notification concerning the IKE_SA, the SPI Size MUST be zero. - - o Notify Message Type (2 octets) - Specifies the type of - notification message. - - o SPI (variable length) - Security Parameter Index. - - o Notification Data (variable length) - Informational or error data - transmitted in addition to the Notify Message Type. Values for - this field are type specific (see below). - - The payload type for the Notify Payload is forty one (41). - - - - - - - - -Kaufman Standards Track [Page 65] - -RFC 4306 IKEv2 December 2005 - - -3.10.1. Notify Message Types - - Notification information can be error messages specifying why an SA - could not be established. It can also be status data that a process - managing an SA database wishes to communicate with a peer process. - The table below lists the Notification messages and their - corresponding values. The number of different error statuses was - greatly reduced from IKEv1 both for simplification and to avoid - giving configuration information to probers. - - Types in the range 0 - 16383 are intended for reporting errors. An - implementation receiving a Notify payload with one of these types - that it does not recognize in a response MUST assume that the - corresponding request has failed entirely. Unrecognized error types - in a request and status types in a request or response MUST be - ignored except that they SHOULD be logged. - - Notify payloads with status types MAY be added to any message and - MUST be ignored if not recognized. They are intended to indicate - capabilities, and as part of SA negotiation are used to negotiate - non-cryptographic parameters. - - NOTIFY MESSAGES - ERROR TYPES Value - ----------------------------- ----- - RESERVED 0 - - UNSUPPORTED_CRITICAL_PAYLOAD 1 - - Sent if the payload has the "critical" bit set and the - payload type is not recognized. Notification Data contains - the one-octet payload type. - - INVALID_IKE_SPI 4 - - Indicates an IKE message was received with an unrecognized - destination SPI. This usually indicates that the recipient - has rebooted and forgotten the existence of an IKE_SA. - - INVALID_MAJOR_VERSION 5 - - Indicates the recipient cannot handle the version of IKE - specified in the header. The closest version number that - the recipient can support will be in the reply header. - - INVALID_SYNTAX 7 - - Indicates the IKE message that was received was invalid - because some type, length, or value was out of range or - - - -Kaufman Standards Track [Page 66] - -RFC 4306 IKEv2 December 2005 - - - because the request was rejected for policy reasons. To - avoid a denial of service attack using forged messages, this - status may only be returned for and in an encrypted packet - if the message ID and cryptographic checksum were valid. To - avoid leaking information to someone probing a node, this - status MUST be sent in response to any error not covered by - one of the other status types. To aid debugging, more - detailed error information SHOULD be written to a console or - log. - - INVALID_MESSAGE_ID 9 - - Sent when an IKE message ID outside the supported window is - received. This Notify MUST NOT be sent in a response; the - invalid request MUST NOT be acknowledged. Instead, inform - the other side by initiating an INFORMATIONAL exchange with - Notification data containing the four octet invalid message - ID. Sending this notification is optional, and - notifications of this type MUST be rate limited. - - INVALID_SPI 11 - - MAY be sent in an IKE INFORMATIONAL exchange when a node - receives an ESP or AH packet with an invalid SPI. The - Notification Data contains the SPI of the invalid packet. - This usually indicates a node has rebooted and forgotten an - SA. If this Informational Message is sent outside the - context of an IKE_SA, it should be used by the recipient - only as a "hint" that something might be wrong (because it - could easily be forged). - - NO_PROPOSAL_CHOSEN 14 - - None of the proposed crypto suites was acceptable. - - INVALID_KE_PAYLOAD 17 - - The D-H Group # field in the KE payload is not the group # - selected by the responder for this exchange. There are two - octets of data associated with this notification: the - accepted D-H Group # in big endian order. - - AUTHENTICATION_FAILED 24 - - Sent in the response to an IKE_AUTH message when for some - reason the authentication failed. There is no associated - data. - - - - -Kaufman Standards Track [Page 67] - -RFC 4306 IKEv2 December 2005 - - - SINGLE_PAIR_REQUIRED 34 - - This error indicates that a CREATE_CHILD_SA request is - unacceptable because its sender is only willing to accept - traffic selectors specifying a single pair of addresses. The - requestor is expected to respond by requesting an SA for only - the specific traffic it is trying to forward. - - NO_ADDITIONAL_SAS 35 - - This error indicates that a CREATE_CHILD_SA request is - unacceptable because the responder is unwilling to accept any - more CHILD_SAs on this IKE_SA. Some minimal implementations may - only accept a single CHILD_SA setup in the context of an initial - IKE exchange and reject any subsequent attempts to add more. - - INTERNAL_ADDRESS_FAILURE 36 - - Indicates an error assigning an internal address (i.e., - INTERNAL_IP4_ADDRESS or INTERNAL_IP6_ADDRESS) during the - processing of a Configuration Payload by a responder. If this - error is generated within an IKE_AUTH exchange, no CHILD_SA will - be created. - - FAILED_CP_REQUIRED 37 - - Sent by responder in the case where CP(CFG_REQUEST) was expected - but not received, and so is a conflict with locally configured - policy. There is no associated data. - - TS_UNACCEPTABLE 38 - - Indicates that none of the addresses/protocols/ports in the - supplied traffic selectors is acceptable. - - INVALID_SELECTORS 39 - - MAY be sent in an IKE INFORMATIONAL exchange when a node - receives an ESP or AH packet whose selectors do not match - those of the SA on which it was delivered (and that caused - the packet to be dropped). The Notification Data contains - the start of the offending packet (as in ICMP messages) and - the SPI field of the notification is set to match the SPI of - the IPsec SA. - - RESERVED TO IANA - Error types 40 - 8191 - - Private Use - Errors 8192 - 16383 - - - -Kaufman Standards Track [Page 68] - -RFC 4306 IKEv2 December 2005 - - - NOTIFY MESSAGES - STATUS TYPES Value - ------------------------------ ----- - - INITIAL_CONTACT 16384 - - This notification asserts that this IKE_SA is the only - IKE_SA currently active between the authenticated - identities. It MAY be sent when an IKE_SA is established - after a crash, and the recipient MAY use this information to - delete any other IKE_SAs it has to the same authenticated - identity without waiting for a timeout. This notification - MUST NOT be sent by an entity that may be replicated (e.g., - a roaming user's credentials where the user is allowed to - connect to the corporate firewall from two remote systems at - the same time). - - SET_WINDOW_SIZE 16385 - - This notification asserts that the sending endpoint is - capable of keeping state for multiple outstanding exchanges, - permitting the recipient to send multiple requests before - getting a response to the first. The data associated with a - SET_WINDOW_SIZE notification MUST be 4 octets long and - contain the big endian representation of the number of - messages the sender promises to keep. Window size is always - one until the initial exchanges complete. - - ADDITIONAL_TS_POSSIBLE 16386 - - This notification asserts that the sending endpoint narrowed - the proposed traffic selectors but that other traffic - selectors would also have been acceptable, though only in a - separate SA (see section 2.9). There is no data associated - with this Notify type. It may be sent only as an additional - payload in a message including accepted TSs. - - IPCOMP_SUPPORTED 16387 - - This notification may be included only in a message - containing an SA payload negotiating a CHILD_SA and - indicates a willingness by its sender to use IPComp on this - SA. The data associated with this notification includes a - two-octet IPComp CPI followed by a one-octet transform ID - optionally followed by attributes whose length and format - are defined by that transform ID. A message proposing an SA - may contain multiple IPCOMP_SUPPORTED notifications to - indicate multiple supported algorithms. A message accepting - an SA may contain at most one. - - - -Kaufman Standards Track [Page 69] - -RFC 4306 IKEv2 December 2005 - - - The transform IDs currently defined are: - - NAME NUMBER DEFINED IN - ----------- ------ ----------- - RESERVED 0 - IPCOMP_OUI 1 - IPCOMP_DEFLATE 2 RFC 2394 - IPCOMP_LZS 3 RFC 2395 - IPCOMP_LZJH 4 RFC 3051 - - values 5-240 are reserved to IANA. Values 241-255 are - for private use among mutually consenting parties. - - NAT_DETECTION_SOURCE_IP 16388 - - This notification is used by its recipient to determine - whether the source is behind a NAT box. The data associated - with this notification is a SHA-1 digest of the SPIs (in the - order they appear in the header), IP address, and port on - which this packet was sent. There MAY be multiple Notify - payloads of this type in a message if the sender does not - know which of several network attachments will be used to - send the packet. The recipient of this notification MAY - compare the supplied value to a SHA-1 hash of the SPIs, - source IP address, and port, and if they don't match it - SHOULD enable NAT traversal (see section 2.23). - Alternately, it MAY reject the connection attempt if NAT - traversal is not supported. - - NAT_DETECTION_DESTINATION_IP 16389 - - This notification is used by its recipient to determine - whether it is behind a NAT box. The data associated with - this notification is a SHA-1 digest of the SPIs (in the - order they appear in the header), IP address, and port to - which this packet was sent. The recipient of this - notification MAY compare the supplied value to a hash of the - SPIs, destination IP address, and port, and if they don't - match it SHOULD invoke NAT traversal (see section 2.23). If - they don't match, it means that this end is behind a NAT and - this end SHOULD start sending keepalive packets as defined - in [Hutt05]. Alternately, it MAY reject the connection - attempt if NAT traversal is not supported. - - - - - - - - -Kaufman Standards Track [Page 70] - -RFC 4306 IKEv2 December 2005 - - - COOKIE 16390 - - This notification MAY be included in an IKE_SA_INIT - response. It indicates that the request should be retried - with a copy of this notification as the first payload. This - notification MUST be included in an IKE_SA_INIT request - retry if a COOKIE notification was included in the initial - response. The data associated with this notification MUST - be between 1 and 64 octets in length (inclusive). - - USE_TRANSPORT_MODE 16391 - - This notification MAY be included in a request message that - also includes an SA payload requesting a CHILD_SA. It - requests that the CHILD_SA use transport mode rather than - tunnel mode for the SA created. If the request is accepted, - the response MUST also include a notification of type - USE_TRANSPORT_MODE. If the responder declines the request, - the CHILD_SA will be established in tunnel mode. If this is - unacceptable to the initiator, the initiator MUST delete the - SA. Note: Except when using this option to negotiate - transport mode, all CHILD_SAs will use tunnel mode. - - Note: The ECN decapsulation modifications specified in - [RFC4301] MUST be performed for every tunnel mode SA created - by IKEv2. - - HTTP_CERT_LOOKUP_SUPPORTED 16392 - - This notification MAY be included in any message that can - include a CERTREQ payload and indicates that the sender is - capable of looking up certificates based on an HTTP-based - URL (and hence presumably would prefer to receive - certificate specifications in that format). - - REKEY_SA 16393 - - This notification MUST be included in a CREATE_CHILD_SA - exchange if the purpose of the exchange is to replace an - existing ESP or AH SA. The SPI field identifies the SA - being rekeyed. There is no data. - - ESP_TFC_PADDING_NOT_SUPPORTED 16394 - - This notification asserts that the sending endpoint will NOT - accept packets that contain Flow Confidentiality (TFC) - padding. - - - - -Kaufman Standards Track [Page 71] - -RFC 4306 IKEv2 December 2005 - - - NON_FIRST_FRAGMENTS_ALSO 16395 - - Used for fragmentation control. See [RFC4301] for - explanation. - - RESERVED TO IANA - STATUS TYPES 16396 - 40959 - - Private Use - STATUS TYPES 40960 - 65535 - -3.11. Delete Payload - - The Delete Payload, denoted D in this memo, contains a protocol- - specific security association identifier that the sender has removed - from its security association database and is, therefore, no longer - valid. Figure 17 shows the format of the Delete Payload. It is - possible to send multiple SPIs in a Delete payload; however, each SPI - MUST be for the same protocol. Mixing of protocol identifiers MUST - NOT be performed in a Delete payload. It is permitted, however, to - include multiple Delete payloads in a single INFORMATIONAL exchange - where each Delete payload lists SPIs for a different protocol. - - Deletion of the IKE_SA is indicated by a protocol ID of 1 (IKE) but - no SPIs. Deletion of a CHILD_SA, such as ESP or AH, will contain the - IPsec protocol ID of that protocol (2 for AH, 3 for ESP), and the SPI - is the SPI the sending endpoint would expect in inbound ESP or AH - packets. - - The Delete Payload is defined as follows: - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload !C! RESERVED ! Payload Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Protocol ID ! SPI Size ! # of SPIs ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ Security Parameter Index(es) (SPI) ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 17: Delete Payload Format - - o Protocol ID (1 octet) - Must be 1 for an IKE_SA, 2 for AH, or 3 - for ESP. - - - - - - -Kaufman Standards Track [Page 72] - -RFC 4306 IKEv2 December 2005 - - - o SPI Size (1 octet) - Length in octets of the SPI as defined by the - protocol ID. It MUST be zero for IKE (SPI is in message header) - or four for AH and ESP. - - o # of SPIs (2 octets) - The number of SPIs contained in the Delete - payload. The size of each SPI is defined by the SPI Size field. - - o Security Parameter Index(es) (variable length) - Identifies the - specific security association(s) to delete. The length of this - field is determined by the SPI Size and # of SPIs fields. - - The payload type for the Delete Payload is forty two (42). - -3.12. Vendor ID Payload - - The Vendor ID Payload, denoted V in this memo, contains a vendor - defined constant. The constant is used by vendors to identify and - recognize remote instances of their implementations. This mechanism - allows a vendor to experiment with new features while maintaining - backward compatibility. - - A Vendor ID payload MAY announce that the sender is capable to - accepting certain extensions to the protocol, or it MAY simply - identify the implementation as an aid in debugging. A Vendor ID - payload MUST NOT change the interpretation of any information defined - in this specification (i.e., the critical bit MUST be set to 0). - Multiple Vendor ID payloads MAY be sent. An implementation is NOT - REQUIRED to send any Vendor ID payload at all. - - A Vendor ID payload may be sent as part of any message. Reception of - a familiar Vendor ID payload allows an implementation to make use of - Private USE numbers described throughout this memo -- private - payloads, private exchanges, private notifications, etc. Unfamiliar - Vendor IDs MUST be ignored. - - Writers of Internet-Drafts who wish to extend this protocol MUST - define a Vendor ID payload to announce the ability to implement the - extension in the Internet-Draft. It is expected that Internet-Drafts - that gain acceptance and are standardized will be given "magic - numbers" out of the Future Use range by IANA, and the requirement to - use a Vendor ID will go away. - - - - - - - - - - -Kaufman Standards Track [Page 73] - -RFC 4306 IKEv2 December 2005 - - - The Vendor ID Payload fields are defined as follows: - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload !C! RESERVED ! Payload Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ Vendor ID (VID) ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 18: Vendor ID Payload Format - - o Vendor ID (variable length) - It is the responsibility of the - person choosing the Vendor ID to assure its uniqueness in spite of - the absence of any central registry for IDs. Good practice is to - include a company name, a person name, or some such. If you want - to show off, you might include the latitude and longitude and time - where you were when you chose the ID and some random input. A - message digest of a long unique string is preferable to the long - unique string itself. - - The payload type for the Vendor ID Payload is forty three (43). - -3.13. Traffic Selector Payload - - The Traffic Selector Payload, denoted TS in this memo, allows peers - to identify packet flows for processing by IPsec security services. - The Traffic Selector Payload consists of the IKE generic payload - header followed by individual traffic selectors as follows: - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload !C! RESERVED ! Payload Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Number of TSs ! RESERVED ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ <Traffic Selectors> ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 19: Traffic Selectors Payload Format - - o Number of TSs (1 octet) - Number of traffic selectors being - provided. - - - -Kaufman Standards Track [Page 74] - -RFC 4306 IKEv2 December 2005 - - - o RESERVED - This field MUST be sent as zero and MUST be ignored on - receipt. - - o Traffic Selectors (variable length) - One or more individual - traffic selectors. - - The length of the Traffic Selector payload includes the TS header and - all the traffic selectors. - - The payload type for the Traffic Selector payload is forty four (44) - for addresses at the initiator's end of the SA and forty five (45) - for addresses at the responder's end. - -3.13.1. Traffic Selector - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! TS Type !IP Protocol ID*| Selector Length | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Start Port* | End Port* | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ Starting Address* ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ Ending Address* ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 20: Traffic Selector - - * Note: All fields other than TS Type and Selector Length depend on - the TS Type. The fields shown are for TS Types 7 and 8, the only two - values currently defined. - - o TS Type (one octet) - Specifies the type of traffic selector. - - o IP protocol ID (1 octet) - Value specifying an associated IP - protocol ID (e.g., UDP/TCP/ICMP). A value of zero means that the - protocol ID is not relevant to this traffic selector -- the SA can - carry all protocols. - - o Selector Length - Specifies the length of this Traffic Selector - Substructure including the header. - - - - - -Kaufman Standards Track [Page 75] - -RFC 4306 IKEv2 December 2005 - - - o Start Port (2 octets) - Value specifying the smallest port number - allowed by this Traffic Selector. For protocols for which port is - undefined, or if all ports are allowed, this field MUST be zero. - For the ICMP protocol, the two one-octet fields Type and Code are - treated as a single 16-bit integer (with Type in the most - significant eight bits and Code in the least significant eight - bits) port number for the purposes of filtering based on this - field. - - o End Port (2 octets) - Value specifying the largest port number - allowed by this Traffic Selector. For protocols for which port is - undefined, or if all ports are allowed, this field MUST be 65535. - For the ICMP protocol, the two one-octet fields Type and Code are - treated as a single 16-bit integer (with Type in the most - significant eight bits and Code in the least significant eight - bits) port number for the purposed of filtering based on this - field. - - o Starting Address - The smallest address included in this Traffic - Selector (length determined by TS type). - - o Ending Address - The largest address included in this Traffic - Selector (length determined by TS type). - - Systems that are complying with [RFC4301] that wish to indicate "ANY" - ports MUST set the start port to 0 and the end port to 65535; note - that according to [RFC4301], "ANY" includes "OPAQUE". Systems - working with [RFC4301] that wish to indicate "OPAQUE" ports, but not - "ANY" ports, MUST set the start port to 65535 and the end port to 0. - - The following table lists the assigned values for the Traffic - Selector Type field and the corresponding Address Selector Data. - - TS Type Value - ------- ----- - RESERVED 0-6 - - TS_IPV4_ADDR_RANGE 7 - - A range of IPv4 addresses, represented by two four-octet - values. The first value is the beginning IPv4 address - (inclusive) and the second value is the ending IPv4 address - (inclusive). All addresses falling between the two - specified addresses are considered to be within the list. - - - - - - - -Kaufman Standards Track [Page 76] - -RFC 4306 IKEv2 December 2005 - - - TS_IPV6_ADDR_RANGE 8 - - A range of IPv6 addresses, represented by two sixteen-octet - values. The first value is the beginning IPv6 address - (inclusive) and the second value is the ending IPv6 address - (inclusive). All addresses falling between the two - specified addresses are considered to be within the list. - - RESERVED TO IANA 9-240 - PRIVATE USE 241-255 - -3.14. Encrypted Payload - - The Encrypted Payload, denoted SK{...} or E in this memo, contains - other payloads in encrypted form. The Encrypted Payload, if present - in a message, MUST be the last payload in the message. Often, it is - the only payload in the message. - - The algorithms for encryption and integrity protection are negotiated - during IKE_SA setup, and the keys are computed as specified in - sections 2.14 and 2.18. - - The encryption and integrity protection algorithms are modeled after - the ESP algorithms described in RFCs 2104 [KBC96], 4303 [RFC4303], - and 2451 [ESPCBC]. This document completely specifies the - cryptographic processing of IKE data, but those documents should be - consulted for design rationale. We require a block cipher with a - fixed block size and an integrity check algorithm that computes a - fixed-length checksum over a variable size message. - - The payload type for an Encrypted payload is forty six (46). The - Encrypted Payload consists of the IKE generic payload header followed - by individual fields as follows: - - - - - - - - - - - - - - - - - - -Kaufman Standards Track [Page 77] - -RFC 4306 IKEv2 December 2005 - - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload !C! RESERVED ! Payload Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Initialization Vector ! - ! (length is block size for encryption algorithm) ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ~ Encrypted IKE Payloads ~ - + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! Padding (0-255 octets) ! - +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+ - ! ! Pad Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ~ Integrity Checksum Data ~ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 21: Encrypted Payload Format - - o Next Payload - The payload type of the first embedded payload. - Note that this is an exception in the standard header format, - since the Encrypted payload is the last payload in the message and - therefore the Next Payload field would normally be zero. But - because the content of this payload is embedded payloads and there - was no natural place to put the type of the first one, that type - is placed here. - - o Payload Length - Includes the lengths of the header, IV, Encrypted - IKE Payloads, Padding, Pad Length, and Integrity Checksum Data. - - o Initialization Vector - A randomly chosen value whose length is - equal to the block length of the underlying encryption algorithm. - Recipients MUST accept any value. Senders SHOULD either pick this - value pseudo-randomly and independently for each message or use - the final ciphertext block of the previous message sent. Senders - MUST NOT use the same value for each message, use a sequence of - values with low hamming distance (e.g., a sequence number), or use - ciphertext from a received message. - - o IKE Payloads are as specified earlier in this section. This field - is encrypted with the negotiated cipher. - - o Padding MAY contain any value chosen by the sender, and MUST have - a length that makes the combination of the Payloads, the Padding, - and the Pad Length to be a multiple of the encryption block size. - This field is encrypted with the negotiated cipher. - - - - - -Kaufman Standards Track [Page 78] - -RFC 4306 IKEv2 December 2005 - - - o Pad Length is the length of the Padding field. The sender SHOULD - set the Pad Length to the minimum value that makes the combination - of the Payloads, the Padding, and the Pad Length a multiple of the - block size, but the recipient MUST accept any length that results - in proper alignment. This field is encrypted with the negotiated - cipher. - - o Integrity Checksum Data is the cryptographic checksum of the - entire message starting with the Fixed IKE Header through the Pad - Length. The checksum MUST be computed over the encrypted message. - Its length is determined by the integrity algorithm negotiated. - -3.15. Configuration Payload - - The Configuration payload, denoted CP in this document, is used to - exchange configuration information between IKE peers. The exchange - is for an IRAC to request an internal IP address from an IRAS and to - exchange other information of the sort that one would acquire with - Dynamic Host Configuration Protocol (DHCP) if the IRAC were directly - connected to a LAN. - - Configuration payloads are of type CFG_REQUEST/CFG_REPLY or - CFG_SET/CFG_ACK (see CFG Type in the payload description below). - CFG_REQUEST and CFG_SET payloads may optionally be added to any IKE - request. The IKE response MUST include either a corresponding - CFG_REPLY or CFG_ACK or a Notify payload with an error type - indicating why the request could not be honored. An exception is - that a minimal implementation MAY ignore all CFG_REQUEST and CFG_SET - payloads, so a response message without a corresponding CFG_REPLY or - CFG_ACK MUST be accepted as an indication that the request was not - supported. - - "CFG_REQUEST/CFG_REPLY" allows an IKE endpoint to request information - from its peer. If an attribute in the CFG_REQUEST Configuration - Payload is not zero-length, it is taken as a suggestion for that - attribute. The CFG_REPLY Configuration Payload MAY return that - value, or a new one. It MAY also add new attributes and not include - some requested ones. Requestors MUST ignore returned attributes that - they do not recognize. - - Some attributes MAY be multi-valued, in which case multiple attribute - values of the same type are sent and/or returned. Generally, all - values of an attribute are returned when the attribute is requested. - For some attributes (in this version of the specification only - internal addresses), multiple requests indicates a request that - multiple values be assigned. For these attributes, the number of - values returned SHOULD NOT exceed the number requested. - - - - -Kaufman Standards Track [Page 79] - -RFC 4306 IKEv2 December 2005 - - - If the data type requested in a CFG_REQUEST is not recognized or not - supported, the responder MUST NOT return an error type but rather - MUST either send a CFG_REPLY that MAY be empty or a reply not - containing a CFG_REPLY payload at all. Error returns are reserved - for cases where the request is recognized but cannot be performed as - requested or the request is badly formatted. - - "CFG_SET/CFG_ACK" allows an IKE endpoint to push configuration data - to its peer. In this case, the CFG_SET Configuration Payload - contains attributes the initiator wants its peer to alter. The - responder MUST return a Configuration Payload if it accepted any of - the configuration data and it MUST contain the attributes that the - responder accepted with zero-length data. Those attributes that it - did not accept MUST NOT be in the CFG_ACK Configuration Payload. If - no attributes were accepted, the responder MUST return either an - empty CFG_ACK payload or a response message without a CFG_ACK - payload. There are currently no defined uses for the CFG_SET/CFG_ACK - exchange, though they may be used in connection with extensions based - on Vendor IDs. An minimal implementation of this specification MAY - ignore CFG_SET payloads. - - Extensions via the CP payload SHOULD NOT be used for general purpose - management. Its main intent is to provide a bootstrap mechanism to - exchange information within IPsec from IRAS to IRAC. While it MAY be - useful to use such a method to exchange information between some - Security Gateways (SGW) or small networks, existing management - protocols such as DHCP [DHCP], RADIUS [RADIUS], SNMP, or LDAP [LDAP] - should be preferred for enterprise management as well as subsequent - information exchanges. - - The Configuration Payload is defined as follows: - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload !C! RESERVED ! Payload Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! CFG Type ! RESERVED ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ Configuration Attributes ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 22: Configuration Payload Format - - The payload type for the Configuration Payload is forty seven (47). - - - - -Kaufman Standards Track [Page 80] - -RFC 4306 IKEv2 December 2005 - - - o CFG Type (1 octet) - The type of exchange represented by the - Configuration Attributes. - - CFG Type Value - =========== ===== - RESERVED 0 - CFG_REQUEST 1 - CFG_REPLY 2 - CFG_SET 3 - CFG_ACK 4 - - values 5-127 are reserved to IANA. Values 128-255 are for private - use among mutually consenting parties. - - o RESERVED (3 octets) - MUST be sent as zero; MUST be ignored on - receipt. - - o Configuration Attributes (variable length) - These are type length - values specific to the Configuration Payload and are defined - below. There may be zero or more Configuration Attributes in this - payload. - -3.15.1. Configuration Attributes - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - !R| Attribute Type ! Length | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | | - ~ Value ~ - | | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 23: Configuration Attribute Format - - o Reserved (1 bit) - This bit MUST be set to zero and MUST be - ignored on receipt. - - o Attribute Type (15 bits) - A unique identifier for each of the - Configuration Attribute Types. - - o Length (2 octets) - Length in octets of Value. - - o Value (0 or more octets) - The variable-length value of this - Configuration Attribute. - - - - - -Kaufman Standards Track [Page 81] - -RFC 4306 IKEv2 December 2005 - - - The following attribute types have been defined: - - Multi- - Attribute Type Value Valued Length - ======================= ===== ====== ================== - RESERVED 0 - INTERNAL_IP4_ADDRESS 1 YES* 0 or 4 octets - INTERNAL_IP4_NETMASK 2 NO 0 or 4 octets - INTERNAL_IP4_DNS 3 YES 0 or 4 octets - INTERNAL_IP4_NBNS 4 YES 0 or 4 octets - INTERNAL_ADDRESS_EXPIRY 5 NO 0 or 4 octets - INTERNAL_IP4_DHCP 6 YES 0 or 4 octets - APPLICATION_VERSION 7 NO 0 or more - INTERNAL_IP6_ADDRESS 8 YES* 0 or 17 octets - RESERVED 9 - INTERNAL_IP6_DNS 10 YES 0 or 16 octets - INTERNAL_IP6_NBNS 11 YES 0 or 16 octets - INTERNAL_IP6_DHCP 12 YES 0 or 16 octets - INTERNAL_IP4_SUBNET 13 YES 0 or 8 octets - SUPPORTED_ATTRIBUTES 14 NO Multiple of 2 - INTERNAL_IP6_SUBNET 15 YES 17 octets - - * These attributes may be multi-valued on return only if multiple - values were requested. - - Types 16-16383 are reserved to IANA. Values 16384-32767 are for - private use among mutually consenting parties. - - o INTERNAL_IP4_ADDRESS, INTERNAL_IP6_ADDRESS - An address on the - internal network, sometimes called a red node address or - private address and MAY be a private address on the Internet. - In a request message, the address specified is a requested - address (or zero if no specific address is requested). If a - specific address is requested, it likely indicates that a - previous connection existed with this address and the requestor - would like to reuse that address. With IPv6, a requestor MAY - supply the low-order address bytes it wants to use. Multiple - internal addresses MAY be requested by requesting multiple - internal address attributes. The responder MAY only send up to - the number of addresses requested. The INTERNAL_IP6_ADDRESS is - made up of two fields: the first is a sixteen-octet IPv6 - address and the second is a one-octet prefix-length as defined - in [ADDRIPV6]. - - The requested address is valid until the expiry time defined - with the INTERNAL_ADDRESS EXPIRY attribute or there are no - IKE_SAs between the peers. - - - - -Kaufman Standards Track [Page 82] - -RFC 4306 IKEv2 December 2005 - - - o INTERNAL_IP4_NETMASK - The internal network's netmask. Only - one netmask is allowed in the request and reply messages (e.g., - 255.255.255.0), and it MUST be used only with an - INTERNAL_IP4_ADDRESS attribute. - - o INTERNAL_IP4_DNS, INTERNAL_IP6_DNS - Specifies an address of a - DNS server within the network. Multiple DNS servers MAY be - requested. The responder MAY respond with zero or more DNS - server attributes. - - o INTERNAL_IP4_NBNS, INTERNAL_IP6_NBNS - Specifies an address of - a NetBios Name Server (WINS) within the network. Multiple NBNS - servers MAY be requested. The responder MAY respond with zero - or more NBNS server attributes. - - o INTERNAL_ADDRESS_EXPIRY - Specifies the number of seconds that - the host can use the internal IP address. The host MUST renew - the IP address before this expiry time. Only one of these - attributes MAY be present in the reply. - - o INTERNAL_IP4_DHCP, INTERNAL_IP6_DHCP - Instructs the host to - send any internal DHCP requests to the address contained within - the attribute. Multiple DHCP servers MAY be requested. The - responder MAY respond with zero or more DHCP server attributes. - - o APPLICATION_VERSION - The version or application information of - the IPsec host. This is a string of printable ASCII characters - that is NOT null terminated. - - o INTERNAL_IP4_SUBNET - The protected sub-networks that this - edge-device protects. This attribute is made up of two fields: - the first is an IP address and the second is a netmask. - Multiple sub-networks MAY be requested. The responder MAY - respond with zero or more sub-network attributes. - - o SUPPORTED_ATTRIBUTES - When used within a Request, this - attribute MUST be zero-length and specifies a query to the - responder to reply back with all of the attributes that it - supports. The response contains an attribute that contains a - set of attribute identifiers each in 2 octets. The length - divided by 2 (octets) would state the number of supported - attributes contained in the response. - - - - - - - - - -Kaufman Standards Track [Page 83] - -RFC 4306 IKEv2 December 2005 - - - o INTERNAL_IP6_SUBNET - The protected sub-networks that this - edge-device protects. This attribute is made up of two fields: - the first is a sixteen-octet IPv6 address and the second is a - one-octet prefix-length as defined in [ADDRIPV6]. Multiple - sub-networks MAY be requested. The responder MAY respond with - zero or more sub-network attributes. - - Note that no recommendations are made in this document as to how - an implementation actually figures out what information to send in - a reply. That is, we do not recommend any specific method of an - IRAS determining which DNS server should be returned to a - requesting IRAC. - -3.16. Extensible Authentication Protocol (EAP) Payload - - The Extensible Authentication Protocol Payload, denoted EAP in this - memo, allows IKE_SAs to be authenticated using the protocol defined - in RFC 3748 [EAP] and subsequent extensions to that protocol. The - full set of acceptable values for the payload is defined elsewhere, - but a short summary of RFC 3748 is included here to make this - document stand alone in the common cases. - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload !C! RESERVED ! Payload Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! ! - ~ EAP Message ~ - ! ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Figure 24: EAP Payload Format - - The payload type for an EAP Payload is forty eight (48). - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Code ! Identifier ! Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Type ! Type_Data... - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+- - - Figure 25: EAP Message Format - - o Code (1 octet) indicates whether this message is a Request (1), - Response (2), Success (3), or Failure (4). - - - -Kaufman Standards Track [Page 84] - -RFC 4306 IKEv2 December 2005 - - - o Identifier (1 octet) is used in PPP to distinguish replayed - messages from repeated ones. Since in IKE, EAP runs over a - reliable protocol, it serves no function here. In a response - message, this octet MUST be set to match the identifier in the - corresponding request. In other messages, this field MAY be set - to any value. - - o Length (2 octets) is the length of the EAP message and MUST be - four less than the Payload Length of the encapsulating payload. - - o Type (1 octet) is present only if the Code field is Request (1) or - Response (2). For other codes, the EAP message length MUST be - four octets and the Type and Type_Data fields MUST NOT be present. - In a Request (1) message, Type indicates the data being requested. - In a Response (2) message, Type MUST either be Nak or match the - type of the data requested. The following types are defined in - RFC 3748: - - 1 Identity - 2 Notification - 3 Nak (Response Only) - 4 MD5-Challenge - 5 One-Time Password (OTP) - 6 Generic Token Card - - o Type_Data (Variable Length) varies with the Type of Request and - the associated Response. For the documentation of the EAP - methods, see [EAP]. - - Note that since IKE passes an indication of initiator identity in - message 3 of the protocol, the responder SHOULD NOT send EAP Identity - requests. The initiator SHOULD, however, respond to such requests if - it receives them. - -4. Conformance Requirements - - In order to assure that all implementations of IKEv2 can - interoperate, there are "MUST support" requirements in addition to - those listed elsewhere. Of course, IKEv2 is a security protocol, and - one of its major functions is to allow only authorized parties to - successfully complete establishment of SAs. So a particular - implementation may be configured with any of a number of restrictions - concerning algorithms and trusted authorities that will prevent - universal interoperability. - - - - - - - -Kaufman Standards Track [Page 85] - -RFC 4306 IKEv2 December 2005 - - - IKEv2 is designed to permit minimal implementations that can - interoperate with all compliant implementations. There are a series - of optional features that can easily be ignored by a particular - implementation if it does not support that feature. Those features - include: - - Ability to negotiate SAs through a NAT and tunnel the resulting - ESP SA over UDP. - - Ability to request (and respond to a request for) a temporary IP - address on the remote end of a tunnel. - - Ability to support various types of legacy authentication. - - Ability to support window sizes greater than one. - - Ability to establish multiple ESP and/or AH SAs within a single - IKE_SA. - - Ability to rekey SAs. - - To assure interoperability, all implementations MUST be capable of - parsing all payload types (if only to skip over them) and to ignore - payload types that it does not support unless the critical bit is set - in the payload header. If the critical bit is set in an unsupported - payload header, all implementations MUST reject the messages - containing those payloads. - - Every implementation MUST be capable of doing four-message - IKE_SA_INIT and IKE_AUTH exchanges establishing two SAs (one for IKE, - one for ESP and/or AH). Implementations MAY be initiate-only or - respond-only if appropriate for their platform. Every implementation - MUST be capable of responding to an INFORMATIONAL exchange, but a - minimal implementation MAY respond to any INFORMATIONAL message with - an empty INFORMATIONAL reply (note that within the context of an - IKE_SA, an "empty" message consists of an IKE header followed by an - Encrypted payload with no payloads contained in it). A minimal - implementation MAY support the CREATE_CHILD_SA exchange only in so - far as to recognize requests and reject them with a Notify payload of - type NO_ADDITIONAL_SAS. A minimal implementation need not be able to - initiate CREATE_CHILD_SA or INFORMATIONAL exchanges. When an SA - expires (based on locally configured values of either lifetime or - octets passed), and implementation MAY either try to renew it with a - CREATE_CHILD_SA exchange or it MAY delete (close) the old SA and - create a new one. If the responder rejects the CREATE_CHILD_SA - request with a NO_ADDITIONAL_SAS notification, the implementation - MUST be capable of instead closing the old SA and creating a new one. - - - - -Kaufman Standards Track [Page 86] - -RFC 4306 IKEv2 December 2005 - - - Implementations are not required to support requesting temporary IP - addresses or responding to such requests. If an implementation does - support issuing such requests, it MUST include a CP payload in - message 3 containing at least a field of type INTERNAL_IP4_ADDRESS or - INTERNAL_IP6_ADDRESS. All other fields are optional. If an - implementation supports responding to such requests, it MUST parse - the CP payload of type CFG_REQUEST in message 3 and recognize a field - of type INTERNAL_IP4_ADDRESS or INTERNAL_IP6_ADDRESS. If it supports - leasing an address of the appropriate type, it MUST return a CP - payload of type CFG_REPLY containing an address of the requested - type. The responder SHOULD include all of the other related - attributes if it has them. - - A minimal IPv4 responder implementation will ignore the contents of - the CP payload except to determine that it includes an - INTERNAL_IP4_ADDRESS attribute and will respond with the address and - other related attributes regardless of whether the initiator - requested them. - - A minimal IPv4 initiator will generate a CP payload containing only - an INTERNAL_IP4_ADDRESS attribute and will parse the response - ignoring attributes it does not know how to use. The only attribute - it MUST be able to process is INTERNAL_ADDRESS_EXPIRY, which it must - use to bound the lifetime of the SA unless it successfully renews the - lease before it expires. Minimal initiators need not be able to - request lease renewals and minimal responders need not respond to - them. - - For an implementation to be called conforming to this specification, - it MUST be possible to configure it to accept the following: - - PKIX Certificates containing and signed by RSA keys of size 1024 or - 2048 bits, where the ID passed is any of ID_KEY_ID, ID_FQDN, - ID_RFC822_ADDR, or ID_DER_ASN1_DN. - - Shared key authentication where the ID passes is any of ID_KEY_ID, - ID_FQDN, or ID_RFC822_ADDR. - - Authentication where the responder is authenticated using PKIX - Certificates and the initiator is authenticated using shared key - authentication. - - - - - - - - - - -Kaufman Standards Track [Page 87] - -RFC 4306 IKEv2 December 2005 - - -5. Security Considerations - - While this protocol is designed to minimize disclosure of - configuration information to unauthenticated peers, some such - disclosure is unavoidable. One peer or the other must identify - itself first and prove its identity first. To avoid probing, the - initiator of an exchange is required to identify itself first, and - usually is required to authenticate itself first. The initiator can, - however, learn that the responder supports IKE and what cryptographic - protocols it supports. The responder (or someone impersonating the - responder) can probe the initiator not only for its identity, but - using CERTREQ payloads may be able to determine what certificates the - initiator is willing to use. - - Use of EAP authentication changes the probing possibilities somewhat. - When EAP authentication is used, the responder proves its identity - before the initiator does, so an initiator that knew the name of a - valid initiator could probe the responder for both its name and - certificates. - - Repeated rekeying using CREATE_CHILD_SA without additional Diffie- - Hellman exchanges leaves all SAs vulnerable to cryptanalysis of a - single key or overrun of either endpoint. Implementers should take - note of this fact and set a limit on CREATE_CHILD_SA exchanges - between exponentiations. This memo does not prescribe such a limit. - - The strength of a key derived from a Diffie-Hellman exchange using - any of the groups defined here depends on the inherent strength of - the group, the size of the exponent used, and the entropy provided by - the random number generator used. Due to these inputs, it is - difficult to determine the strength of a key for any of the defined - groups. Diffie-Hellman group number two, when used with a strong - random number generator and an exponent no less than 200 bits, is - common for use with 3DES. Group five provides greater security than - group two. Group one is for historic purposes only and does not - provide sufficient strength except for use with DES, which is also - for historic use only. Implementations should make note of these - estimates when establishing policy and negotiating security - parameters. - - Note that these limitations are on the Diffie-Hellman groups - themselves. There is nothing in IKE that prohibits using stronger - groups nor is there anything that will dilute the strength obtained - from stronger groups (limited by the strength of the other algorithms - negotiated including the prf function). In fact, the extensible - framework of IKE encourages the definition of more groups; use of - elliptical curve groups may greatly increase strength using much - smaller numbers. - - - -Kaufman Standards Track [Page 88] - -RFC 4306 IKEv2 December 2005 - - - It is assumed that all Diffie-Hellman exponents are erased from - memory after use. In particular, these exponents MUST NOT be derived - from long-lived secrets like the seed to a pseudo-random generator - that is not erased after use. - - The strength of all keys is limited by the size of the output of the - negotiated prf function. For this reason, a prf function whose - output is less than 128 bits (e.g., 3DES-CBC) MUST NOT be used with - this protocol. - - The security of this protocol is critically dependent on the - randomness of the randomly chosen parameters. These should be - generated by a strong random or properly seeded pseudo-random source - (see [RFC4086]). Implementers should take care to ensure that use of - random numbers for both keys and nonces is engineered in a fashion - that does not undermine the security of the keys. - - For information on the rationale of many of the cryptographic design - choices in this protocol, see [SIGMA] and [SKEME]. Though the - security of negotiated CHILD_SAs does not depend on the strength of - the encryption and integrity protection negotiated in the IKE_SA, - implementations MUST NOT negotiate NONE as the IKE integrity - protection algorithm or ENCR_NULL as the IKE encryption algorithm. - - When using pre-shared keys, a critical consideration is how to assure - the randomness of these secrets. The strongest practice is to ensure - that any pre-shared key contain as much randomness as the strongest - key being negotiated. Deriving a shared secret from a password, - name, or other low-entropy source is not secure. These sources are - subject to dictionary and social engineering attacks, among others. - - The NAT_DETECTION_*_IP notifications contain a hash of the addresses - and ports in an attempt to hide internal IP addresses behind a NAT. - Since the IPv4 address space is only 32 bits, and it is usually very - sparse, it would be possible for an attacker to find out the internal - address used behind the NAT box by trying all possible IP addresses - and trying to find the matching hash. The port numbers are normally - fixed to 500, and the SPIs can be extracted from the packet. This - reduces the number of hash calculations to 2^32. With an educated - guess of the use of private address space, the number of hash - calculations is much smaller. Designers should therefore not assume - that use of IKE will not leak internal address information. - - When using an EAP authentication method that does not generate a - shared key for protecting a subsequent AUTH payload, certain man-in- - the-middle and server impersonation attacks are possible [EAPMITM]. - These vulnerabilities occur when EAP is also used in protocols that - are not protected with a secure tunnel. Since EAP is a general- - - - -Kaufman Standards Track [Page 89] - -RFC 4306 IKEv2 December 2005 - - - purpose authentication protocol, which is often used to provide - single-signon facilities, a deployed IPsec solution that relies on an - EAP authentication method that does not generate a shared key (also - known as a non-key-generating EAP method) can become compromised due - to the deployment of an entirely unrelated application that also - happens to use the same non-key-generating EAP method, but in an - unprotected fashion. Note that this vulnerability is not limited to - just EAP, but can occur in other scenarios where an authentication - infrastructure is reused. For example, if the EAP mechanism used by - IKEv2 utilizes a token authenticator, a man-in-the-middle attacker - could impersonate the web server, intercept the token authentication - exchange, and use it to initiate an IKEv2 connection. For this - reason, use of non-key-generating EAP methods SHOULD be avoided where - possible. Where they are used, it is extremely important that all - usages of these EAP methods SHOULD utilize a protected tunnel, where - the initiator validates the responder's certificate before initiating - the EAP exchange. Implementers SHOULD describe the vulnerabilities - of using non-key-generating EAP methods in the documentation of their - implementations so that the administrators deploying IPsec solutions - are aware of these dangers. - - An implementation using EAP MUST also use a public-key-based - authentication of the server to the client before the EAP exchange - begins, even if the EAP method offers mutual authentication. This - avoids having additional IKEv2 protocol variations and protects the - EAP data from active attackers. - - If the messages of IKEv2 are long enough that IP-level fragmentation - is necessary, it is possible that attackers could prevent the - exchange from completing by exhausting the reassembly buffers. The - chances of this can be minimized by using the Hash and URL encodings - instead of sending certificates (see section 3.6). Additional - mitigations are discussed in [KPS03]. - -6. IANA Considerations - - This document defines a number of new field types and values where - future assignments will be managed by the IANA. - - The following registries have been created by the IANA: - - IKEv2 Exchange Types (section 3.1) - IKEv2 Payload Types (section 3.2) - IKEv2 Transform Types (section 3.3.2) - IKEv2 Transform Attribute Types (section 3.3.2) - IKEv2 Encryption Transform IDs (section 3.3.2) - IKEv2 Pseudo-random Function Transform IDs (section 3.3.2) - IKEv2 Integrity Algorithm Transform IDs (section 3.3.2) - - - -Kaufman Standards Track [Page 90] - -RFC 4306 IKEv2 December 2005 - - - IKEv2 Diffie-Hellman Transform IDs (section 3.3.2) - IKEv2 Identification Payload ID Types (section 3.5) - IKEv2 Certificate Encodings (section 3.6) - IKEv2 Authentication Method (section 3.8) - IKEv2 Notify Message Types (section 3.10.1) - IKEv2 Notification IPCOMP Transform IDs (section 3.10.1) - IKEv2 Security Protocol Identifiers (section 3.3.1) - IKEv2 Traffic Selector Types (section 3.13.1) - IKEv2 Configuration Payload CFG Types (section 3.15) - IKEv2 Configuration Payload Attribute Types (section 3.15.1) - - Note: When creating a new Transform Type, a new registry for it must - be created. - - Changes and additions to any of those registries are by expert - review. - -7. Acknowledgements - - This document is a collaborative effort of the entire IPsec WG. If - there were no limit to the number of authors that could appear on an - RFC, the following, in alphabetical order, would have been listed: - Bill Aiello, Stephane Beaulieu, Steve Bellovin, Sara Bitan, Matt - Blaze, Ran Canetti, Darren Dukes, Dan Harkins, Paul Hoffman, John - Ioannidis, Charlie Kaufman, Steve Kent, Angelos Keromytis, Tero - Kivinen, Hugo Krawczyk, Andrew Krywaniuk, Radia Perlman, Omer - Reingold, and Michael Richardson. Many other people contributed to - the design. It is an evolution of IKEv1, ISAKMP, and the IPsec DOI, - each of which has its own list of authors. Hugh Daniel suggested the - feature of having the initiator, in message 3, specify a name for the - responder, and gave the feature the cute name "You Tarzan, Me Jane". - David Faucher and Valery Smyzlov helped refine the design of the - traffic selector negotiation. - -8. References - -8.1. Normative References - - [ADDGROUP] Kivinen, T. and M. Kojo, "More Modular Exponential (MODP) - Diffie-Hellman groups for Internet Key Exchange (IKE)", - RFC 3526, May 2003. - - [ADDRIPV6] Hinden, R. and S. Deering, "Internet Protocol Version 6 - (IPv6) Addressing Architecture", RFC 3513, April 2003. - - [Bra97] Bradner, S., "Key Words for use in RFCs to indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. - - - - -Kaufman Standards Track [Page 91] - -RFC 4306 IKEv2 December 2005 - - - [EAP] Aboba, B., Blunk, L., Vollbrecht, J., Carlson, J., and H. - Levkowetz, "Extensible Authentication Protocol (EAP)", RFC - 3748, June 2004. - - [ESPCBC] Pereira, R. and R. Adams, "The ESP CBC-Mode Cipher - Algorithms", RFC 2451, November 1998. - - [Hutt05] Huttunen, A., Swander, B., Volpe, V., DiBurro, L., and M. - Stenberg, "UDP Encapsulation of IPsec ESP Packets", RFC - 3948, January 2005. - - [RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing an - IANA Considerations Section in RFCs", BCP 26, RFC 2434, - October 1998. - - [RFC3168] Ramakrishnan, K., Floyd, S., and D. Black, "The Addition - of Explicit Congestion Notification (ECN) to IP", RFC - 3168, September 2001. - - [RFC3280] Housley, R., Polk, W., Ford, W., and D. Solo, "Internet - X.509 Public Key Infrastructure Certificate and - Certificate Revocation List (CRL) Profile", RFC 3280, - April 2002. - - [RFC4301] Kent, S. and K. Seo, "Security Architecture for the - Internet Protocol", RFC 4301, December 2005. - -8.2. Informative References - - [DES] ANSI X3.106, "American National Standard for Information - Systems-Data Link Encryption", American National Standards - Institute, 1983. - - [DH] Diffie, W., and Hellman M., "New Directions in - Cryptography", IEEE Transactions on Information Theory, V. - IT-22, n. 6, June 1977. - - [DHCP] Droms, R., "Dynamic Host Configuration Protocol", RFC - 2131, March 1997. - - [DSS] NIST, "Digital Signature Standard", FIPS 186, National - Institute of Standards and Technology, U.S. Department of - Commerce, May, 1994. - - [EAPMITM] Asokan, N., Nierni, V., and Nyberg, K., "Man-in-the-Middle - in Tunneled Authentication Protocols", - http://eprint.iacr.org/2002/163, November 2002. - - - - -Kaufman Standards Track [Page 92] - -RFC 4306 IKEv2 December 2005 - - - [HC98] Harkins, D. and D. Carrel, "The Internet Key Exchange - (IKE)", RFC 2409, November 1998. - - [IDEA] Lai, X., "On the Design and Security of Block Ciphers," - ETH Series in Information Processing, v. 1, Konstanz: - Hartung-Gorre Verlag, 1992. - - [IPCOMP] Shacham, A., Monsour, B., Pereira, R., and M. Thomas, "IP - Payload Compression Protocol (IPComp)", RFC 3173, - September 2001. - - [KPS03] Kaufman, C., Perlman, R., and Sommerfeld, B., "DoS - protection for UDP-based protocols", ACM Conference on - Computer and Communications Security, October 2003. - - [KBC96] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- - Hashing for Message Authentication", RFC 2104, February - 1997. - - [LDAP] Wahl, M., Howes, T., and S Kille, "Lightweight Directory - Access Protocol (v3)", RFC 2251, December 1997. - - [MD5] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, - April 1992. - - [MSST98] Maughan, D., Schertler, M., Schneider, M., and J. Turner, - "Internet Security Association and Key Management Protocol - (ISAKMP)", RFC 2408, November 1998. - - [Orm96] Orman, H., "The OAKLEY Key Determination Protocol", RFC - 2412, November 1998. - - [PFKEY] McDonald, D., Metz, C., and B. Phan, "PF_KEY Key - Management API, Version 2", RFC 2367, July 1998. - - [PKCS1] Jonsson, J. and B. Kaliski, "Public-Key Cryptography - Standards (PKCS) #1: RSA Cryptography Specifications - Version 2.1", RFC 3447, February 2003. - - [PK01] Perlman, R., and Kaufman, C., "Analysis of the IPsec key - exchange Standard", WET-ICE Security Conference, MIT,2001, - http://sec.femto.org/wetice-2001/papers/radia-paper.pdf. - - [Pip98] Piper, D., "The Internet IP Security Domain Of - Interpretation for ISAKMP", RFC 2407, November 1998. - - - - - - -Kaufman Standards Track [Page 93] - -RFC 4306 IKEv2 December 2005 - - - [RADIUS] Rigney, C., Willens, S., Rubens, A., and W. Simpson, - "Remote Authentication Dial In User Service (RADIUS)", RFC - 2865, June 2000. - - [RFC4086] Eastlake, D., 3rd, Schiller, J., and S. Crocker, - "Randomness Requirements for Security", BCP 106, RFC 4086, - June 2005. - - [RFC1958] Carpenter, B., "Architectural Principles of the Internet", - RFC 1958, June 1996. - - [RFC2401] Kent, S. and R. Atkinson, "Security Architecture for the - Internet Protocol", RFC 2401, November 1998. - - [RFC2474] Nichols, K., Blake, S., Baker, F., and D. Black, - "Definition of the Differentiated Services Field (DS - Field) in the IPv4 and IPv6 Headers", RFC 2474, December - 1998. - - [RFC2475] Blake, S., Black, D., Carlson, M., Davies, E., Wang, Z., - and W. Weiss, "An Architecture for Differentiated - Service", RFC 2475, December 1998. - - [RFC2522] Karn, P. and W. Simpson, "Photuris: Session-Key Management - Protocol", RFC 2522, March 1999. - - [RFC2775] Carpenter, B., "Internet Transparency", RFC 2775, February - 2000. - - [RFC2983] Black, D., "Differentiated Services and Tunnels", RFC - 2983, October 2000. - - [RFC3439] Bush, R. and D. Meyer, "Some Internet Architectural - Guidelines and Philosophy", RFC 3439, December 2002. - - [RFC3715] Aboba, B. and W. Dixon, "IPsec-Network Address Translation - (NAT) Compatibility Requirements", RFC 3715, March 2004. - - [RFC4302] Kent, S., "IP Authentication Header", RFC 4302, December - 2005. - - [RFC4303] Kent, S., "IP Encapsulating Security Payload (ESP)", RFC - 4303, December 2005. - - [RSA] Rivest, R., Shamir, A., and Adleman, L., "A Method for - Obtaining Digital Signatures and Public-Key - Cryptosystems", Communications of the ACM, v. 21, n. 2, - February 1978. - - - -Kaufman Standards Track [Page 94] - -RFC 4306 IKEv2 December 2005 - - - [SHA] NIST, "Secure Hash Standard", FIPS 180-1, National - Institute of Standards and Technology, U.S. Department of - Commerce, May 1994. - - [SIGMA] Krawczyk, H., "SIGMA: the `SIGn-and-MAc' Approach to - Authenticated Diffie-Hellman and its Use in the IKE - Protocols", in Advances in Cryptography - CRYPTO 2003 - Proceedings, LNCS 2729, Springer, 2003. Available at: - http://www.informatik.uni-trier.de/~ley/db/conf/ - crypto/crypto2003.html. - - [SKEME] Krawczyk, H., "SKEME: A Versatile Secure Key Exchange - Mechanism for Internet", from IEEE Proceedings of the 1996 - Symposium on Network and Distributed Systems Security. - - [X.501] ITU-T Recommendation X.501: Information Technology - Open - Systems Interconnection - The Directory: Models, 1993. - - [X.509] ITU-T Recommendation X.509 (1997 E): Information - Technology - Open Systems Interconnection - The Directory: - Authentication Framework, June 1997. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Kaufman Standards Track [Page 95] - -RFC 4306 IKEv2 December 2005 - - -Appendix A: Summary of changes from IKEv1 - - The goals of this revision to IKE are: - - 1) To define the entire IKE protocol in a single document, replacing - RFCs 2407, 2408, and 2409 and incorporating subsequent changes to - support NAT Traversal, Extensible Authentication, and Remote Address - acquisition; - - 2) To simplify IKE by replacing the eight different initial exchanges - with a single four-message exchange (with changes in authentication - mechanisms affecting only a single AUTH payload rather than - restructuring the entire exchange) see [PK01]; - - 3) To remove the Domain of Interpretation (DOI), Situation (SIT), and - Labeled Domain Identifier fields, and the Commit and Authentication - only bits; - - 4) To decrease IKE's latency in the common case by making the initial - exchange be 2 round trips (4 messages), and allowing the ability to - piggyback setup of a CHILD_SA on that exchange; - - 5) To replace the cryptographic syntax for protecting the IKE - messages themselves with one based closely on ESP to simplify - implementation and security analysis; - - 6) To reduce the number of possible error states by making the - protocol reliable (all messages are acknowledged) and sequenced. - This allows shortening CREATE_CHILD_SA exchanges from 3 messages to - 2; - - 7) To increase robustness by allowing the responder to not do - significant processing until it receives a message proving that the - initiator can receive messages at its claimed IP address, and not - commit any state to an exchange until the initiator can be - cryptographically authenticated; - - 8) To fix cryptographic weaknesses such as the problem with - symmetries in hashes used for authentication documented by Tero - Kivinen; - - 9) To specify Traffic Selectors in their own payloads type rather - than overloading ID payloads, and making more flexible the Traffic - Selectors that may be specified; - - 10) To specify required behavior under certain error conditions or - when data that is not understood is received, to make it easier to - make future revisions that do not break backward compatibility; - - - -Kaufman Standards Track [Page 96] - -RFC 4306 IKEv2 December 2005 - - - 11) To simplify and clarify how shared state is maintained in the - presence of network failures and Denial of Service attacks; and - - 12) To maintain existing syntax and magic numbers to the extent - possible to make it likely that implementations of IKEv1 can be - enhanced to support IKEv2 with minimum effort. - -Appendix B: Diffie-Hellman Groups - - There are two Diffie-Hellman groups defined here for use in IKE. - These groups were generated by Richard Schroeppel at the University - of Arizona. Properties of these primes are described in [Orm96]. - - The strength supplied by group one may not be sufficient for the - mandatory-to-implement encryption algorithm and is here for historic - reasons. - - Additional Diffie-Hellman groups have been defined in [ADDGROUP]. - -B.1. Group 1 - 768 Bit MODP - - This group is assigned id 1 (one). - - The prime is: 2^768 - 2 ^704 - 1 + 2^64 * { [2^638 pi] + 149686 } Its - hexadecimal value is: - - FFFFFFFF FFFFFFFF C90FDAA2 2168C234 C4C6628B 80DC1CD1 29024E08 - 8A67CC74 020BBEA6 3B139B22 514A0879 8E3404DD EF9519B3 CD3A431B - 302B0A6D F25F1437 4FE1356D 6D51C245 E485B576 625E7EC6 F44C42E9 - A63A3620 FFFFFFFF FFFFFFFF - - The generator is 2. - -B.2. Group 2 - 1024 Bit MODP - - This group is assigned id 2 (two). - - The prime is 2^1024 - 2^960 - 1 + 2^64 * { [2^894 pi] + 129093 }. - Its hexadecimal value is: - - FFFFFFFF FFFFFFFF C90FDAA2 2168C234 C4C6628B 80DC1CD1 29024E08 - 8A67CC74 020BBEA6 3B139B22 514A0879 8E3404DD EF9519B3 CD3A431B - 302B0A6D F25F1437 4FE1356D 6D51C245 E485B576 625E7EC6 F44C42E9 - A637ED6B 0BFF5CB6 F406B7ED EE386BFB 5A899FA5 AE9F2411 7C4B1FE6 - 49286651 ECE65381 FFFFFFFF FFFFFFFF - - The generator is 2. - - - - -Kaufman Standards Track [Page 97] - -RFC 4306 IKEv2 December 2005 - - -Editor's Address - - Charlie Kaufman - Microsoft Corporation - 1 Microsoft Way - Redmond, WA 98052 - - Phone: 1-425-707-3335 - EMail: charliek@microsoft.com - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Kaufman Standards Track [Page 98] - -RFC 4306 IKEv2 December 2005 - - -Full Copyright Statement - - Copyright (C) The Internet Society (2005). - - This document is subject to the rights, licenses and restrictions - contained in BCP 78, and except as set forth therein, the authors - retain all their rights. - - This document and the information contained herein are provided on an - "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS - OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET - ENGINEERING TASK FORCE DISCLAIM 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. - -Intellectual Property - - The IETF takes no position regarding the validity or scope of any - Intellectual Property Rights or other rights that might be claimed to - pertain to the implementation or use of the technology described in - this document or the extent to which any license under such rights - might or might not be available; nor does it represent that it has - made any independent effort to identify any such rights. Information - on the procedures with respect to rights in RFC documents can be - found in BCP 78 and BCP 79. - - Copies of IPR disclosures made to the IETF Secretariat and any - assurances of licenses to be made available, or the result of an - attempt made to obtain a general license or permission for the use of - such proprietary rights by implementers or users of this - specification can be obtained from the IETF on-line IPR repository at - http://www.ietf.org/ipr. - - The IETF invites any interested party to bring to its attention any - copyrights, patents or patent applications, or other proprietary - rights that may cover technology that may be required to implement - this standard. Please address the information to the IETF at ietf- - ipr@ietf.org. - -Acknowledgement - - Funding for the RFC Editor function is currently provided by the - Internet Society. - - - - - - - -Kaufman Standards Track [Page 99] - diff --git a/src/charon/doc/standards/rfc4307.txt b/src/charon/doc/standards/rfc4307.txt deleted file mode 100644 index 5617a2551..000000000 --- a/src/charon/doc/standards/rfc4307.txt +++ /dev/null @@ -1,339 +0,0 @@ - - - - - - -Network Working Group J. Schiller -Request for Comments: 4307 Massachusetts Institute of Technology -Category: Standards Track December 2005 - - - Cryptographic Algorithms for Use in the - Internet Key Exchange Version 2 (IKEv2) - -Status of This Memo - - This document specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" (STD 1) for the standardization state - and status of this protocol. Distribution of this memo is unlimited. - -Copyright Notice - - Copyright (C) The Internet Society (2005). - -Abstract - - The IPsec series of protocols makes use of various cryptographic - algorithms in order to provide security services. The Internet Key - Exchange (IKE (RFC 2409) and IKEv2) provide a mechanism to negotiate - which algorithms should be used in any given association. However, - to ensure interoperability between disparate implementations, it is - necessary to specify a set of mandatory-to-implement algorithms to - ensure that there is at least one algorithm that all implementations - will have available. This document defines the current set of - algorithms that are mandatory to implement as part of IKEv2, as well - as algorithms that should be implemented because they may be promoted - to mandatory at some future time. - -1. Introduction - - The Internet Key Exchange protocol provides for the negotiation of - cryptographic algorithms between both endpoints of a cryptographic - - association. Different implementations of IPsec and IKE may provide - different algorithms. However, the IETF desires that all - implementations should have some way to interoperate. In particular, - this requires that IKE define a set of mandatory-to-implement - algorithms because IKE itself uses such algorithms as part of its own - negotiations. This requires that some set of algorithms be specified - as "mandatory-to-implement" for IKE. - - - - - -Schiller Standards Track [Page 1] - -RFC 4307 IKEv2 Cryptographic Algorithms December 2005 - - - The nature of cryptography is that new algorithms surface - continuously and existing algorithms are continuously attacked. An - algorithm believed to be strong today may be demonstrated to be weak - tomorrow. Given this, the choice of mandatory-to-implement algorithm - should be conservative so as to minimize the likelihood of it being - compromised quickly. Thought should also be given to performance - considerations as many uses of IPsec will be in environments where - performance is a concern. - - Finally, we need to recognize that the mandatory-to-implement - algorithm(s) may need to change over time to adapt to the changing - world. For this reason, the selection of mandatory-to-implement - algorithms was removed from the main IKEv2 specification and placed - in this document. As the choice of algorithm changes, only this - document should need to be updated. - - Ideally, the mandatory-to-implement algorithm of tomorrow should - already be available in most implementations of IPsec by the time it - is made mandatory. To facilitate this, we will attempt to identify - those algorithms (that are known today) in this document. There is - no guarantee that the algorithms we believe today may be mandatory in - the future will in fact become so. All algorithms known today are - subject to cryptographic attack and may be broken in the future. - -2. Requirements Terminology - - Keywords "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", and - "MAY" that appear in this document are to be interpreted as described - in [RFC2119]. - - We define some additional terms here: - - SHOULD+ This term means the same as SHOULD. However, it is likely - that an algorithm marked as SHOULD+ will be promoted at - some future time to be a MUST. - - SHOULD- This term means the same as SHOULD. However, an algorithm - marked as SHOULD- may be deprecated to a MAY in a future - version of this document. - - MUST- This term means the same as MUST. However, we expect at - some point that this algorithm will no longer be a MUST in - a future document. Although its status will be determined - at a later time, it is reasonable to expect that if a - future revision of a document alters the status of a MUST- - algorithm, it will remain at least a SHOULD or a SHOULD-. - - - - - -Schiller Standards Track [Page 2] - -RFC 4307 IKEv2 Cryptographic Algorithms December 2005 - - -3. Algorithm Selection - -3.1. IKEv2 Algorithm Selection - -3.1.1. Encrypted Payload Algorithms - - The IKEv2 Encrypted Payload requires both a confidentiality algorithm - and an integrity algorithm. For confidentiality, implementations - MUST- implement 3DES-CBC and SHOULD+ implement AES-128-CBC. For - integrity, HMAC-SHA1 MUST be implemented. - -3.1.2. Diffie-Hellman Groups - - There are several Modular Exponential (MODP) groups that are defined - for use in IKEv2. They are defined in both the [IKEv2] base document - and in the MODP extensions document. They are identified by group - number. Any groups not listed here are considered as "MAY be - implemented". - - Group Number Bit Length Status Defined - 2 1024 MODP Group MUST- [RFC2409] - 14 2048 MODP Group SHOULD+ [RFC3526] - -3.1.3. IKEv2 Transform Type 1 Algorithms - - IKEv2 defines several possible algorithms for Transfer Type 1 - (encryption). These are defined below with their implementation - status. - - Name Number Defined In Status - RESERVED 0 - ENCR_3DES 3 [RFC2451] MUST- - ENCR_NULL 11 [RFC2410] MAY - ENCR_AES_CBC 12 [AES-CBC] SHOULD+ - ENCR_AES_CTR 13 [AES-CTR] SHOULD - -3.1.4. IKEv2 Transform Type 2 Algorithms - - Transfer Type 2 Algorithms are pseudo-random functions used to - generate random values when needed. - - Name Number Defined In Status - RESERVED 0 - PRF_HMAC_MD5 1 [RFC2104] MAY - PRF_HMAC_SHA1 2 [RFC2104] MUST - PRF_AES128_CBC 4 [AESPRF] SHOULD+ - - - - - -Schiller Standards Track [Page 3] - -RFC 4307 IKEv2 Cryptographic Algorithms December 2005 - - -3.1.5. IKEv2 Transform Type 3 Algorithms - - Transfer Type 3 Algorithms are Integrity algorithms used to protect - data against tampering. - - Name Number Defined In Status - NONE 0 - AUTH_HMAC_MD5_96 1 [RFC2403] MAY - AUTH_HMAC_SHA1_96 2 [RFC2404] MUST - AUTH_AES_XCBC_96 5 [AES-MAC] SHOULD+ - -4. Security Considerations - - The security of cryptographic-based systems depends on both the - strength of the cryptographic algorithms chosen and the strength of - the keys used with those algorithms. The security also depends on - the engineering of the protocol used by the system to ensure that - there are no non-cryptographic ways to bypass the security of the - overall system. - - This document concerns itself with the selection of cryptographic - algorithms for the use of IKEv2, specifically with the selection of - "mandatory-to-implement" algorithms. The algorithms identified in - this document as "MUST implement" or "SHOULD implement" are not known - to be broken at the current time, and cryptographic research so far - leads us to believe that they will likely remain secure into the - foreseeable future. However, this isn't necessarily forever. We - would therefore expect that new revisions of this document will be - issued from time to time that reflect the current best practice in - this area. - -5. Normative References - - [RFC2409] Harkins, D. and D. Carrel, "The Internet Key Exchange - (IKE)", RFC 2409, November 1998. - - [IKEv2] Kaufman, C., Ed., "Internet Key Exchange (IKEv2) - Protocol", RFC 4306, December 2005. - - [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. - - [RFC3526] Kivinen, T. and M. Kojo, "More Modular Exponential - (MODP) Diffie-Hellman groups for Internet Key Exchange - (IKE)", RFC 3526, May 2003. - - [RFC2451] Pereira, R. and R. Adams, "The ESP CBC-Mode Cipher - Algorithms", RFC 2451, November 1998. - - - -Schiller Standards Track [Page 4] - -RFC 4307 IKEv2 Cryptographic Algorithms December 2005 - - - [RFC2410] Glenn, R. and S. Kent, "The NULL Encryption Algorithm - and Its Use With IPsec", RFC 2410, November 1998. - - [AES-CBC] Frankel, S., Glenn, R., and S. Kelly, "The AES-CBC - Cipher Algorithm and Its Use with IPsec", RFC 3602, - September 2003. - - [AES-CTR] Housley, R., "Using Advanced Encryption Standard (AES) - Counter Mode With IPsec Encapsulating Security Payload - (ESP)", RFC 3686, January 2004. - - [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: - Keyed-Hashing for Message Authentication", RFC 2104, - February 1997. - - [AESPRF] Hoffman, P., "The AES-XCBC-PRF-128 Algorithm for the - Internet Key Exchange Protocol (IKE)", RFC 3664, January - 2004. - - [RFC2403] Madson, C. and R. Glenn, "The Use of HMAC-MD5-96 within - ESP and AH", RFC 2403, November 1998. - - [RFC2404] Madson, C. and R. Glenn, "The Use of HMAC-SHA-1-96 - within ESP and AH", RFC 2404, November 1998. - - [AES-MAC] Frankel, S. and H. Herbert, "The AES-XCBC-MAC-96 - Algorithm and Its Use With IPsec", RFC 3566, September - 2003. - -Author's Address - - Jeffrey I. Schiller - Massachusetts Institute of Technology - Room W92-190 - 77 Massachusetts Avenue - Cambridge, MA 02139-4307 - USA - - Phone: +1 (617) 253-0161 - EMail: jis@mit.edu - - - - - - - - - - - -Schiller Standards Track [Page 5] - -RFC 4307 IKEv2 Cryptographic Algorithms December 2005 - - -Full Copyright Statement - - Copyright (C) The Internet Society (2005). - - This document is subject to the rights, licenses and restrictions - contained in BCP 78, and except as set forth therein, the authors - retain all their rights. - - This document and the information contained herein are provided on an - "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS - OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET - ENGINEERING TASK FORCE DISCLAIM 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. - -Intellectual Property - - The IETF takes no position regarding the validity or scope of any - Intellectual Property Rights or other rights that might be claimed to - pertain to the implementation or use of the technology described in - this document or the extent to which any license under such rights - might or might not be available; nor does it represent that it has - made any independent effort to identify any such rights. Information - on the procedures with respect to rights in RFC documents can be - found in BCP 78 and BCP 79. - - Copies of IPR disclosures made to the IETF Secretariat and any - assurances of licenses to be made available, or the result of an - attempt made to obtain a general license or permission for the use of - such proprietary rights by implementers or users of this - specification can be obtained from the IETF on-line IPR repository at - http://www.ietf.org/ipr. - - The IETF invites any interested party to bring to its attention any - copyrights, patents or patent applications, or other proprietary - rights that may cover technology that may be required to implement - this standard. Please address the information to the IETF at ietf- - ipr@ietf.org. - -Acknowledgement - - Funding for the RFC Editor function is currently provided by the - Internet Society. - - - - - - - -Schiller Standards Track [Page 6] - diff --git a/src/charon/doc/standards/rfc4478.txt b/src/charon/doc/standards/rfc4478.txt deleted file mode 100644 index 45bf32536..000000000 --- a/src/charon/doc/standards/rfc4478.txt +++ /dev/null @@ -1,283 +0,0 @@ - - - - - - -Network Working Group Y. Nir -Request for Comments: 4478 Check Point -Category: Experimental April 2006 - - - Repeated Authentication in Internet Key Exchange (IKEv2) Protocol - -Status of This Memo - - This memo defines an Experimental Protocol for the Internet - community. It does not specify an Internet standard of any kind. - Discussion and suggestions for improvement are requested. - Distribution of this memo is unlimited. - -Copyright Notice - - Copyright (C) The Internet Society (2006). - -Abstract - - This document extends the Internet Key Exchange (IKEv2) Protocol - document [IKEv2]. With some IPsec peers, particularly in the remote - access scenario, it is desirable to repeat the mutual authentication - periodically. The purpose of this is to limit the time that security - associations (SAs) can be used by a third party who has gained - control of the IPsec peer. This document describes a mechanism to - perform this function. - -1. Introduction - - In several cases, such as the remote access scenario, policy dictates - that the mutual authentication needs to be repeated periodically. - Repeated authentication can usually be achieved by simply repeating - the Initial exchange by whichever side has a stricter policy. - - However, in the remote access scenario it is usually up to a human - user to supply the authentication credentials, and often Extensible - Authentication Protocol (EAP) is used for authentication, which makes - it unreasonable or impossible for the remote access gateway to - initiate the IKEv2 exchange. - - This document describes a new notification that the original - Responder can send to the original Initiator with the number of - seconds before the authentication needs to be repeated. The - Initiator SHOULD repeat the Initial exchange before that time is - expired. If the Initiator fails to do so, the Responder may close - all Security Associations. - - - - -Nir Experimental [Page 1] - -RFC 4478 Repeated Authentication in IKEv2 April 2006 - - - Repeated authentication is not the same as IKE SA rekeying, and need - not be tied to it. The key words "MUST", "MUST NOT", "SHOULD", - "SHOULD NOT", and "MAY" in this document are to be interpreted as - described in [RFC2119]. - -2. Authentication Lifetime - - The Responder in an IKEv2 negotiation MAY be configured to limit the - time that an IKE SA and the associated IPsec SAs may be used before - the peer is required to repeat the authentication, through a new - Initial Exchange. - - The Responder MUST send this information to the Initiator in an - AUTH_LIFETIME notification either in the last message of an IKE_AUTH - exchange, or in an INFORMATIONAL request, which may be sent at any - time. - - When sent as part of the IKE SA setup, the AUTH_LIFETIME notification - is used as follows: - - Initiator Responder - ------------------------------- ----------------------------- - HDR, SAi1, KEi, Ni --> - <-- HDR, SAr1, KEr, Nr, [CERTREQ] - HDR, SK {IDi, [CERT,] [CERTREQ,] - [IDr,] AUTH, SAi2, TSi, TSr} --> - <-- HDR, SK {IDr, [CERT,] AUTH, - SAr2, TSi, TSr, - N(AUTH_LIFETIME)} - - The separate Informational exchange is formed as follows: - - <-- HDR, SK {N(AUTH_LIFETIME)} - HDR SK {} --> - - The AUTH_LIFETIME notification is described in Section 3. - - The original Responder that sends the AUTH_LIFETIME notification - SHOULD send a DELETE notification soon after the end of the lifetime - period, unless the IKE SA is deleted before the lifetime period - elapses. If the IKE SA is rekeyed, then the time limit applies to - the new SA. - - An Initiator that received an AUTH_LIFETIME notification SHOULD - repeat the Initial exchange within the time indicated in the - notification. The time is measured from the time that the original - Initiator receives the notification. - - - - -Nir Experimental [Page 2] - -RFC 4478 Repeated Authentication in IKEv2 April 2006 - - - A special case is where the notification is sent in an Informational - exchange, and the lifetime is zero. In that case, the original - responder SHOULD allow a reasonable time for the repeated - authentication to occur. - - The AUTH_LIFETIME notification MUST be protected and MAY be sent by - the original Responder at any time. If the policy changes, the - original Responder MAY send it again in a new Informational. - - The new Initial exchange is not altered. The initiator SHOULD delete - the old IKE SA within a reasonable time of the new Auth exchange. - -3. AUTH_LIFETIME Notification - - The AUTH_LIFETIME message is a notification payload formatted as - follows: - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Next Payload !C! RESERVED ! Payload Length ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Protocol ID ! SPI Size ! Notify Message Type ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - ! Lifetime ! - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - o Payload Length is 12. - o Protocol ID (1 octet) MUST be 0. - o SPI size is 0 (SPI is in message header). - o Notify Message type is 16403 by IANA. - o Lifetime is the amount of time (in seconds) left before the - peer should repeat the Initial exchange. A zero value - signifies that the Initial exchange should begin immediately. - It is usually not reasonable to set this value to less than 300 - (5 minutes) since that is too cumbersome for a user. - It is also usually not reasonable to set this value to more - than 86400 (1 day) as that would negate the security benefit of - repeating the authentication. - -4. Interoperability with Non-Supporting IKEv2 Implementations - - IKEv2 implementations that do not support the AUTH_LIFETIME - notification will ignore it and will not repeat the authentication. - In that case the original Responder will send a Delete notification - for the IKE SA in an Informational exchange. Such implementations - may be configured manually to repeat the authentication periodically. - - - - -Nir Experimental [Page 3] - -RFC 4478 Repeated Authentication in IKEv2 April 2006 - - - Non-supporting Responders are not a problem because they will simply - not send these notifications. In that case, there is no requirement - that the original Initiator re-authenticate. - -5. Security Considerations - - The AUTH_LIFETIME notification sent by the Responder does not - override any security policy on the Initiator. In particular, the - Initiator may have a different policy regarding re-authentication, - requiring more frequent re-authentication. Such an Initiator can - repeat the authentication earlier then is required by the - notification. - - An Initiator MAY set reasonable limits on the amount of time in the - AUTH_LIFETIME notification. For example, an authentication lifetime - of less than 300 seconds from SA initiation may be considered - unreasonable. - -6. IANA Considerations - - The IANA has assigned a notification payload type for the - AUTH_LIFETIME notifications from the IKEv2 Notify Message Types - registry. - -7. Normative References - - [IKEv2] Kaufman, C., "Internet Key Exchange (IKEv2) Protocol", RFC - 4306, December 2005. - - [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. - -Author's Address - - Yoav Nir - Check Point Software Technologies - - EMail: ynir@checkpoint.com - - - - - - - - - - - - - -Nir Experimental [Page 4] - -RFC 4478 Repeated Authentication in IKEv2 April 2006 - - -Full Copyright Statement - - Copyright (C) The Internet Society (2006). - - This document is subject to the rights, licenses and restrictions - contained in BCP 78, and except as set forth therein, the authors - retain all their rights. - - This document and the information contained herein are provided on an - "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS - OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET - ENGINEERING TASK FORCE DISCLAIM 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. - -Intellectual Property - - The IETF takes no position regarding the validity or scope of any - Intellectual Property Rights or other rights that might be claimed to - pertain to the implementation or use of the technology described in - this document or the extent to which any license under such rights - might or might not be available; nor does it represent that it has - made any independent effort to identify any such rights. Information - on the procedures with respect to rights in RFC documents can be - found in BCP 78 and BCP 79. - - Copies of IPR disclosures made to the IETF Secretariat and any - assurances of licenses to be made available, or the result of an - attempt made to obtain a general license or permission for the use of - such proprietary rights by implementers or users of this - specification can be obtained from the IETF on-line IPR repository at - http://www.ietf.org/ipr. - - The IETF invites any interested party to bring to its attention any - copyrights, patents or patent applications, or other proprietary - rights that may cover technology that may be required to implement - this standard. Please address the information to the IETF at - ietf-ipr@ietf.org. - -Acknowledgement - - Funding for the RFC Editor function is provided by the IETF - Administrative Support Activity (IASA). - - - - - - - -Nir Experimental [Page 5] - diff --git a/src/charon/doc/standards/rfc4718.txt b/src/charon/doc/standards/rfc4718.txt deleted file mode 100644 index 35ad6986d..000000000 --- a/src/charon/doc/standards/rfc4718.txt +++ /dev/null @@ -1,3251 +0,0 @@ - - - - - - -Network Working Group P. Eronen -Request for Comments: 4718 Nokia -Category: Informational P. Hoffman - VPN Consortium - October 2006 - - - IKEv2 Clarifications and Implementation Guidelines - -Status of This Memo - - This memo provides information for the Internet community. It does - not specify an Internet standard of any kind. Distribution of this - memo is unlimited. - -Copyright Notice - - Copyright (C) The Internet Society (2006). - -Abstract - - This document clarifies many areas of the IKEv2 specification. It - does not to introduce any changes to the protocol, but rather - provides descriptions that are less prone to ambiguous - interpretations. The purpose of this document is to encourage the - development of interoperable implementations. - - - - - - - - - - - - - - - - - - - - - - - - - -Eronen & Hoffman Informational [Page 1] - -RFC 4718 IKEv2 Clarifications October 2006 - - -Table of Contents - - 1. Introduction ....................................................4 - 2. Creating the IKE_SA .............................................4 - 2.1. SPI Values in IKE_SA_INIT Exchange .........................4 - 2.2. Message IDs for IKE_SA_INIT Messages .......................5 - 2.3. Retransmissions of IKE_SA_INIT Requests ....................5 - 2.4. Interaction of COOKIE and INVALID_KE_PAYLOAD ...............6 - 2.5. Invalid Cookies ............................................8 - 3. Authentication ..................................................9 - 3.1. Data Included in AUTH Payload Calculation ..................9 - 3.2. Hash Function for RSA Signatures ...........................9 - 3.3. Encoding Method for RSA Signatures ........................10 - 3.4. Identification Type for EAP ...............................11 - 3.5. Identity for Policy Lookups When Using EAP ................11 - 3.6. Certificate Encoding Types ................................12 - 3.7. Shared Key Authentication and Fixed PRF Key Size ..........12 - 3.8. EAP Authentication and Fixed PRF Key Size .................13 - 3.9. Matching ID Payloads to Certificate Contents ..............13 - 3.10. Message IDs for IKE_AUTH Messages ........................14 - 4. Creating CHILD_SAs .............................................14 - 4.1. Creating SAs with the CREATE_CHILD_SA Exchange ............14 - 4.2. Creating an IKE_SA without a CHILD_SA .....................16 - 4.3. Diffie-Hellman for First CHILD_SA .........................16 - 4.4. Extended Sequence Numbers (ESN) Transform .................17 - 4.5. Negotiation of ESP_TFC_PADDING_NOT_SUPPORTED ..............17 - 4.6. Negotiation of NON_FIRST_FRAGMENTS_ALSO ...................18 - 4.7. Semantics of Complex Traffic Selector Payloads ............18 - 4.8. ICMP Type/Code in Traffic Selector Payloads ...............19 - 4.9. Mobility Header in Traffic Selector Payloads ..............20 - 4.10. Narrowing the Traffic Selectors ..........................20 - 4.11. SINGLE_PAIR_REQUIRED .....................................21 - 4.12. Traffic Selectors Violating Own Policy ...................21 - 4.13. Traffic Selector Authorization ...........................22 - 5. Rekeying and Deleting SAs ......................................23 - 5.1. Rekeying SAs with the CREATE_CHILD_SA Exchange ............23 - 5.2. Rekeying the IKE_SA vs. Reauthentication ..................24 - 5.3. SPIs When Rekeying the IKE_SA .............................25 - 5.4. SPI When Rekeying a CHILD_SA ..............................25 - 5.5. Changing PRFs When Rekeying the IKE_SA ....................26 - 5.6. Deleting vs. Closing SAs ..................................26 - 5.7. Deleting a CHILD_SA Pair ..................................26 - 5.8. Deleting an IKE_SA ........................................27 - 5.9. Who is the original initiator of IKE_SA ...................27 - 5.10. Comparing Nonces .........................................27 - 5.11. Exchange Collisions ......................................28 - 5.12. Diffie-Hellman and Rekeying the IKE_SA ...................36 - - - - -Eronen & Hoffman Informational [Page 2] - -RFC 4718 IKEv2 Clarifications October 2006 - - - 6. Configuration Payloads .........................................37 - 6.1. Assigning IP Addresses ....................................37 - 6.2. Requesting any INTERNAL_IP4/IP6_ADDRESS ...................38 - 6.3. INTERNAL_IP4_SUBNET/INTERNAL_IP6_SUBNET ...................38 - 6.4. INTERNAL_IP4_NETMASK ......................................41 - 6.5. Configuration Payloads for IPv6 ...........................42 - 6.6. INTERNAL_IP6_NBNS .........................................43 - 6.7. INTERNAL_ADDRESS_EXPIRY ...................................43 - 6.8. Address Assignment Failures ...............................44 - 7. Miscellaneous Issues ...........................................45 - 7.1. Matching ID_IPV4_ADDR and ID_IPV6_ADDR ....................45 - 7.2. Relationship of IKEv2 to RFC 4301 .........................45 - 7.3. Reducing the Window Size ..................................46 - 7.4. Minimum Size of Nonces ....................................46 - 7.5. Initial Zero Octets on Port 4500 ..........................46 - 7.6. Destination Port for NAT Traversal ........................47 - 7.7. SPI Values for Messages outside an IKE_SA .................47 - 7.8. Protocol ID/SPI Fields in Notify Payloads .................48 - 7.9. Which message should contain INITIAL_CONTACT ..............48 - 7.10. Alignment of Payloads ....................................48 - 7.11. Key Length Transform Attribute ...........................48 - 7.12. IPsec IANA Considerations ................................49 - 7.13. Combining ESP and AH .....................................50 - 8. Implementation Mistakes ........................................50 - 9. Security Considerations ........................................51 - 10. Acknowledgments ...............................................51 - 11. References ....................................................51 - 11.1. Normative References .....................................51 - 11.2. Informative References ...................................52 - Appendix A. Exchanges and Payloads ................................54 - A.1. IKE_SA_INIT Exchange ......................................54 - A.2. IKE_AUTH Exchange without EAP .............................54 - A.3. IKE_AUTH Exchange with EAP ................................55 - A.4. CREATE_CHILD_SA Exchange for Creating/Rekeying - CHILD_SAs .................................................56 - A.5. CREATE_CHILD_SA Exchange for Rekeying the IKE_SA ..........56 - A.6. INFORMATIONAL Exchange ....................................56 - - - - - - - - - - - - - - -Eronen & Hoffman Informational [Page 3] - -RFC 4718 IKEv2 Clarifications October 2006 - - -1. Introduction - - This document clarifies many areas of the IKEv2 specification that - may be difficult to understand to developers not intimately familiar - with the specification and its history. The clarifications in this - document come from the discussion on the IPsec WG mailing list, from - experience in interoperability testing, and from implementation - issues that have been brought to the editors' attention. - - IKEv2/IPsec can be used for several different purposes, including - IPsec-based remote access (sometimes called the "road warrior" case), - site-to-site virtual private networks (VPNs), and host-to-host - protection of application traffic. While this document attempts to - consider all of these uses, the remote access scenario has perhaps - received more attention here than the other uses. - - This document does not place any requirements on anyone and does not - use [RFC2119] keywords such as "MUST" and "SHOULD", except in - quotations from the original IKEv2 documents. The requirements are - given in the IKEv2 specification [IKEv2] and IKEv2 cryptographic - algorithms document [IKEv2ALG]. - - In this document, references to a numbered section (such as "Section - 2.15") mean that section in [IKEv2]. References to mailing list - messages or threads refer to the IPsec WG mailing list at - ipsec@ietf.org. Archives of the mailing list can be found at - <http://www.ietf.org/mail-archive/web/ipsec/index.html>. - -2. Creating the IKE_SA - -2.1. SPI Values in IKE_SA_INIT Exchange - - Normal IKE messages include the initiator's and responder's Security - Parameter Indexes (SPIs), both of which are non-zero, in the IKE - header. However, there are some corner cases where the IKEv2 - specification is not fully consistent about what values should be - used. - - First, Section 3.1 says that the Responder's SPI "...MUST NOT be zero - in any other message" (than the first message of the IKE_SA_INIT - exchange). However, the figure in Section 2.6 shows the second - IKE_SA_INIT message as "HDR(A,0), N(COOKIE)", contradicting the text - in 3.1. - - Since the responder's SPI identifies security-related state held by - the responder, and in this case no state is created, sending a zero - value seems reasonable. - - - - -Eronen & Hoffman Informational [Page 4] - -RFC 4718 IKEv2 Clarifications October 2006 - - - Second, in addition to cookies, there are several other cases when - the IKE_SA_INIT exchange does not result in the creation of an IKE_SA - (for instance, INVALID_KE_PAYLOAD or NO_PROPOSAL_CHOSEN). What - responder SPI value should be used in the IKE_SA_INIT response in - this case? - - Since the IKE_SA_INIT request always has a zero responder SPI, the - value will not be actually used by the initiator. Thus, we think - sending a zero value is correct also in this case. - - If the responder sends a non-zero responder SPI, the initiator should - not reject the response only for that reason. However, when retrying - the IKE_SA_INIT request, the initiator will use a zero responder SPI, - as described in Section 3.1: "Responder's SPI [...] This value MUST - be zero in the first message of an IKE Initial Exchange (including - repeats of that message including a cookie) [...]". We believe the - intent was to cover repeats of that message due to other reasons, - such as INVALID_KE_PAYLOAD, as well. - - (References: "INVALID_KE_PAYLOAD and clarifications document" thread, - Sep-Oct 2005.) - -2.2. Message IDs for IKE_SA_INIT Messages - - The Message ID for IKE_SA_INIT messages is always zero. This - includes retries of the message due to responses such as COOKIE and - INVALID_KE_PAYLOAD. - - This is because Message IDs are part of the IKE_SA state, and when - the responder replies to IKE_SA_INIT request with N(COOKIE) or - N(INVALID_KE_PAYLOAD), the responder does not allocate any state. - - (References: "Question about N(COOKIE) and N(INVALID_KE_PAYLOAD) - combination" thread, Oct 2004. Tero Kivinen's mail "Comments of - draft-eronen-ipsec-ikev2-clarifications-02.txt", 2005-04-05.) - -2.3. Retransmissions of IKE_SA_INIT Requests - - When a responder receives an IKE_SA_INIT request, it has to determine - whether the packet is a retransmission belonging to an existing - "half-open" IKE_SA (in which case the responder retransmits the same - response), or a new request (in which case the responder creates a - new IKE_SA and sends a fresh response). - - The specification does not describe in detail how this determination - is done. In particular, it is not sufficient to use the initiator's - SPI and/or IP address for this purpose: two different peers behind a - single NAT could choose the same initiator SPI (and the probability - - - -Eronen & Hoffman Informational [Page 5] - -RFC 4718 IKEv2 Clarifications October 2006 - - - of this happening is not necessarily small, since IKEv2 does not - require SPIs to be chosen randomly). Instead, the responder should - do the IKE_SA lookup using the whole packet or its hash (or at the - minimum, the Ni payload which is always chosen randomly). - - For all other packets than IKE_SA_INIT requests, looking up right - IKE_SA is of course done based on the recipient's SPI (either the - initiator or responder SPI depending on the value of the Initiator - bit in the IKE header). - -2.4. Interaction of COOKIE and INVALID_KE_PAYLOAD - - There are two common reasons why the initiator may have to retry the - IKE_SA_INIT exchange: the responder requests a cookie or wants a - different Diffie-Hellman group than was included in the KEi payload. - Both of these cases are quite simple alone, but it is not totally - obvious what happens when they occur at the same time, that is, the - IKE_SA_INIT exchange is retried several times. - - The main question seems to be the following: if the initiator - receives a cookie from the responder, should it include the cookie in - only the next retry of the IKE_SA_INIT request, or in all subsequent - retries as well? Section 3.10.1 says that: - - "This notification MUST be included in an IKE_SA_INIT request - retry if a COOKIE notification was included in the initial - response." - - This could be interpreted as saying that when a cookie is received in - the initial response, it is included in all retries. On the other - hand, Section 2.6 says that: - - "Initiators who receive such responses MUST retry the - IKE_SA_INIT with a Notify payload of type COOKIE containing - the responder supplied cookie data as the first payload and - all other payloads unchanged." - - Including the same cookie in later retries makes sense only if the - "all other payloads unchanged" restriction applies only to the first - retry, but not to subsequent retries. - - It seems that both interpretations can peacefully coexist. If the - initiator includes the cookie only in the next retry, one additional - roundtrip may be needed in some cases: - - - - - - - -Eronen & Hoffman Informational [Page 6] - -RFC 4718 IKEv2 Clarifications October 2006 - - - Initiator Responder - ----------- ----------- - HDR(A,0), SAi1, KEi, Ni --> - <-- HDR(A,0), N(COOKIE) - HDR(A,0), N(COOKIE), SAi1, KEi, Ni --> - <-- HDR(A,0), N(INVALID_KE_PAYLOAD) - HDR(A,0), SAi1, KEi', Ni --> - <-- HDR(A,0), N(COOKIE') - HDR(A,0), N(COOKIE'), SAi1, KEi',Ni --> - <-- HDR(A,B), SAr1, KEr, Nr - - An additional roundtrip is needed also if the initiator includes the - cookie in all retries, but the responder does not support this - functionality. For instance, if the responder includes the SAi1 and - KEi payloads in cookie calculation, it will reject the request by - sending a new cookie (see also Section 2.5 of this document for more - text about invalid cookies): - - - Initiator Responder - ----------- ----------- - HDR(A,0), SAi1, KEi, Ni --> - <-- HDR(A,0), N(COOKIE) - HDR(A,0), N(COOKIE), SAi1, KEi, Ni --> - <-- HDR(A,0), N(INVALID_KE_PAYLOAD) - HDR(A,0), N(COOKIE), SAi1, KEi', Ni --> - <-- HDR(A,0), N(COOKIE') - HDR(A,0), N(COOKIE'), SAi1, KEi',Ni --> - <-- HDR(A,B), SAr1, KEr, Nr - - If both peers support including the cookie in all retries, a slightly - shorter exchange can happen: - - Initiator Responder - ----------- ----------- - HDR(A,0), SAi1, KEi, Ni --> - <-- HDR(A,0), N(COOKIE) - HDR(A,0), N(COOKIE), SAi1, KEi, Ni --> - <-- HDR(A,0), N(INVALID_KE_PAYLOAD) - HDR(A,0), N(COOKIE), SAi1, KEi', Ni --> - <-- HDR(A,B), SAr1, KEr, Nr - - This document recommends that implementations should support this - shorter exchange, but it must not be assumed the other peer also - supports the shorter exchange. - - - - - - -Eronen & Hoffman Informational [Page 7] - -RFC 4718 IKEv2 Clarifications October 2006 - - - In theory, even this exchange has one unnecessary roundtrip, as both - the cookie and Diffie-Hellman group could be checked at the same - time: - - Initiator Responder - ----------- ----------- - HDR(A,0), SAi1, KEi, Ni --> - <-- HDR(A,0), N(COOKIE), - N(INVALID_KE_PAYLOAD) - HDR(A,0), N(COOKIE), SAi1, KEi',Ni --> - <-- HDR(A,B), SAr1, KEr, Nr - - However, it is clear that this case is not allowed by the text in - Section 2.6, since "all other payloads" clearly includes the KEi - payload as well. - - (References: "INVALID_KE_PAYLOAD and clarifications document" thread, - Sep-Oct 2005.) - -2.5. Invalid Cookies - - There has been some confusion what should be done when an IKE_SA_INIT - request containing an invalid cookie is received ("invalid" in the - sense that its contents do not match the value expected by the - responder). - - The correct action is to ignore the cookie and process the message as - if no cookie had been included (usually this means sending a response - containing a new cookie). This is shown in Section 2.6 when it says - "The responder in that case MAY reject the message by sending another - response with a new cookie [...]". - - Other possible actions, such as ignoring the whole request (or even - all requests from this IP address for some time), create strange - failure modes even in the absence of any malicious attackers and do - not provide any additional protection against DoS attacks. - - (References: "Invalid Cookie" thread, Sep-Oct 2005.) - - - - - - - - - - - - - -Eronen & Hoffman Informational [Page 8] - -RFC 4718 IKEv2 Clarifications October 2006 - - -3. Authentication - -3.1. Data Included in AUTH Payload Calculation - - Section 2.15 describes how the AUTH payloads are calculated; this - calculation involves values prf(SK_pi,IDi') and prf(SK_pr,IDr'). The - text describes the method in words, but does not give clear - definitions of what is signed or MACed (i.e., protected with a - message authentication code). - - The initiator's signed octets can be described as: - - InitiatorSignedOctets = RealMessage1 | NonceRData | MACedIDForI - GenIKEHDR = [ four octets 0 if using port 4500 ] | RealIKEHDR - RealIKEHDR = SPIi | SPIr | . . . | Length - RealMessage1 = RealIKEHDR | RestOfMessage1 - NonceRPayload = PayloadHeader | NonceRData - InitiatorIDPayload = PayloadHeader | RestOfIDPayload - RestOfInitIDPayload = IDType | RESERVED | InitIDData - MACedIDForI = prf(SK_pi, RestOfInitIDPayload) - - The responder's signed octets can be described as: - - ResponderSignedOctets = RealMessage2 | NonceIData | MACedIDForR - GenIKEHDR = [ four octets 0 if using port 4500 ] | RealIKEHDR - RealIKEHDR = SPIi | SPIr | . . . | Length - RealMessage2 = RealIKEHDR | RestOfMessage2 - NonceIPayload = PayloadHeader | NonceIData - ResponderIDPayload = PayloadHeader | RestOfIDPayload - RestOfRespIDPayload = IDType | RESERVED | InitIDData - MACedIDForR = prf(SK_pr, RestOfRespIDPayload) - -3.2. Hash Function for RSA Signatures - - Section 3.8 says that RSA digital signature is "Computed as specified - in section 2.15 using an RSA private key over a PKCS#1 padded hash." - - Unlike IKEv1, IKEv2 does not negotiate a hash function for the - IKE_SA. The algorithm for signatures is selected by the signing - party who, in general, may not know beforehand what algorithms the - verifying party supports. Furthermore, [IKEv2ALG] does not say what - algorithms implementations are required or recommended to support. - This clearly has a potential for causing interoperability problems, - since authentication will fail if the signing party selects an - algorithm that is not supported by the verifying party, or not - acceptable according to the verifying party's policy. - - - - - -Eronen & Hoffman Informational [Page 9] - -RFC 4718 IKEv2 Clarifications October 2006 - - - This document recommends that all implementations support SHA-1 and - use SHA-1 as the default hash function when generating the - signatures, unless there are good reasons (such as explicit manual - configuration) to believe that the peer supports something else. - - Note that hash function collision attacks are not important for the - AUTH payloads, since they are not intended for third-party - verification, and the data includes fresh nonces. See [HashUse] for - more discussion about hash function attacks and IPsec. - - Another reasonable choice would be to use the hash function that was - used by the CA when signing the peer certificate. However, this does - not guarantee that the IKEv2 peer would be able to validate the AUTH - payload, because the same code might not be used to validate - certificate signatures and IKEv2 message signatures, and these two - routines may support a different set of hash algorithms. The peer - could be configured with a fingerprint of the certificate, or - certificate validation could be performed by an external entity using - [SCVP]. Furthermore, not all CERT payloads types include a - signature, and the certificate could be signed with some algorithm - other than RSA. - - Note that unlike IKEv1, IKEv2 uses the PKCS#1 v1.5 [PKCS1v20] - signature encoding method (see next section for details), which - includes the algorithm identifier for the hash algorithm. Thus, when - the verifying party receives the AUTH payload it can at least - determine which hash function was used. - - (References: Magnus Alstrom's mail "RE:", 2005-01-03. Pasi Eronen's - reply, 2005-01-04. Tero Kivinen's reply, 2005-01-04. "First draft - of IKEv2.1" thread, Dec 2005/Jan 2006.) - -3.3. Encoding Method for RSA Signatures - - Section 3.8 says that the RSA digital signature is "Computed as - specified in section 2.15 using an RSA private key over a PKCS#1 - padded hash." - - The PKCS#1 specification [PKCS1v21] defines two different encoding - methods (ways of "padding the hash") for signatures. However, the - Internet-Draft approved by the IESG had a reference to the older - PKCS#1 v2.0 [PKCS1v20]. That version has only one encoding method - for signatures (EMSA-PKCS1-v1_5), and thus there is no ambiguity. - - - - - - - - -Eronen & Hoffman Informational [Page 10] - -RFC 4718 IKEv2 Clarifications October 2006 - - - Note that this encoding method is different from the encoding method - used in IKEv1. If future revisions of IKEv2 provide support for - other encoding methods (such as EMSA-PSS), they will be given new - Auth Method numbers. - - (References: Pasi Eronen's mail "RE:", 2005-01-04.) - -3.4. Identification Type for EAP - - Section 3.5 defines several different types for identification - payloads, including, e.g., ID_FQDN, ID_RFC822_ADDR, and ID_KEY_ID. - EAP [EAP] does not mandate the use of any particular type of - identifier, but often EAP is used with Network Access Identifiers - (NAIs) defined in [NAI]. Although NAIs look a bit like email - addresses (e.g., "joe@example.com"), the syntax is not exactly the - same as the syntax of email address in [RFC822]. This raises the - question of which identification type should be used. - - This document recommends that ID_RFC822_ADDR identification type is - used for those NAIs that include the realm component. Therefore, - responder implementations should not attempt to verify that the - contents actually conform to the exact syntax given in [RFC822] or - [RFC2822], but instead should accept any reasonable looking NAI. - - For NAIs that do not include the realm component, this document - recommends using the ID_KEY_ID identification type. - - (References: "need your help on this IKEv2/i18n/EAP issue" and "IKEv2 - identifier issue with EAP" threads, Aug 2004.) - -3.5. Identity for Policy Lookups When Using EAP - - When the initiator authentication uses EAP, it is possible that the - contents of the IDi payload is used only for AAA routing purposes and - selecting which EAP method to use. This value may be different from - the identity authenticated by the EAP method (see [EAP], Sections 5.1 - and 7.3). - - It is important that policy lookups and access control decisions use - the actual authenticated identity. Often the EAP server is - implemented in a separate AAA server that communicates with the IKEv2 - responder using, e.g., RADIUS [RADEAP]. In this case, the - authenticated identity has to be sent from the AAA server to the - IKEv2 responder. - - (References: Pasi Eronen's mail "RE: Reauthentication in IKEv2", - 2004-10-28. "Policy lookups" thread, Oct/Nov 2004. RFC 3748, - Section 7.3.) - - - -Eronen & Hoffman Informational [Page 11] - -RFC 4718 IKEv2 Clarifications October 2006 - - -3.6. Certificate Encoding Types - - Section 3.6 defines a total of twelve different certificate encoding - types, and continues that "Specific syntax is for some of the - certificate type codes above is not defined in this document." - However, the text does not provide references to other documents that - would contain information about the exact contents and use of those - values. - - Without this information, it is not possible to develop interoperable - implementations. Therefore, this document recommends that the - following certificate encoding values should not be used before new - specifications that specify their use are available. - - PKCS #7 wrapped X.509 certificate 1 - PGP Certificate 2 - DNS Signed Key 3 - Kerberos Token 6 - SPKI Certificate 9 - - This document recommends that most implementations should use only - those values that are "MUST"/"SHOULD" requirements in [IKEv2]; i.e., - "X.509 Certificate - Signature" (4), "Raw RSA Key" (11), "Hash and - URL of X.509 certificate" (12), and "Hash and URL of X.509 bundle" - (13). - - Furthermore, Section 3.7 says that the "Certificate Encoding" field - for the Certificate Request payload uses the same values as for - Certificate payload. However, the contents of the "Certification - Authority" field are defined only for X.509 certificates (presumably - covering at least types 4, 10, 12, and 13). This document recommends - that other values should not be used before new specifications that - specify their use are available. - - The "Raw RSA Key" type needs one additional clarification. Section - 3.6 says it contains "a PKCS #1 encoded RSA key". What this means is - a DER-encoded RSAPublicKey structure from PKCS#1 [PKCS1v21]. - -3.7. Shared Key Authentication and Fixed PRF Key Size - - Section 2.15 says that "If the negotiated prf takes a fixed-size key, - the shared secret MUST be of that fixed size". This statement is - correct: the shared secret must be of the correct size. If it is - not, it cannot be used; there is no padding, truncation, or other - processing involved to force it to that correct size. - - - - - - -Eronen & Hoffman Informational [Page 12] - -RFC 4718 IKEv2 Clarifications October 2006 - - - This requirement means that it is difficult to use these pseudo- - random functions (PRFs) with shared key authentication. The authors - think this part of the specification was very poorly thought out, and - using PRFs with a fixed key size is likely to result in - interoperability problems. Thus, we recommend that such PRFs should - not be used with shared key authentication. PRF_AES128_XCBC - [RFC3664] originally used fixed key sizes; that RFC has been updated - to handle variable key sizes in [RFC4434]. - - Note that Section 2.13 also contains text that is related to PRFs - with fixed key size: "When the key for the prf function has fixed - length, the data provided as a key is truncated or padded with zeros - as necessary unless exceptional processing is explained following the - formula". However, this text applies only to the prf+ construction, - so it does not contradict the text in Section 2.15. - - (References: Paul Hoffman's mail "Re: ikev2-07: last nits", - 2003-05-02. Hugo Krawczyk's reply, 2003-05-12. Thread "Question - about PRFs with fixed size key", Jan 2005.) - -3.8. EAP Authentication and Fixed PRF Key Size - - As described in the previous section, PRFs with a fixed key size - require a shared secret of exactly that size. This restriction - applies also to EAP authentication. For instance, a PRF that - requires a 128-bit key cannot be used with EAP since [EAP] specifies - that the MSK is at least 512 bits long. - - (References: Thread "Question about PRFs with fixed size key", Jan - 2005.) - -3.9. Matching ID Payloads to Certificate Contents - - In IKEv1, there was some confusion about whether or not the - identities in certificates used to authenticate IKE were required to - match the contents of the ID payloads. The PKI4IPsec Working Group - produced the document [PKI4IPsec] which covers this topic in much - more detail. However, Section 3.5 of [IKEv2] explicitly says that - the ID payload "does not necessarily have to match anything in the - CERT payload". - - - - - - - - - - - -Eronen & Hoffman Informational [Page 13] - -RFC 4718 IKEv2 Clarifications October 2006 - - -3.10. Message IDs for IKE_AUTH Messages - - According to Section 2.2, "The IKE_SA initial setup messages will - always be numbered 0 and 1." That is true when the IKE_AUTH exchange - does not use EAP. When EAP is used, each pair of messages has their - message numbers incremented. The first pair of AUTH messages will - have an ID of 1, the second will be 2, and so on. - - (References: "Question about MsgID in AUTH exchange" thread, April - 2005.) - -4. Creating CHILD_SAs - -4.1. Creating SAs with the CREATE_CHILD_SA Exchange - - Section 1.3's organization does not lead to clear understanding of - what is needed in which environment. The section can be reorganized - with subsections for each use of the CREATE_CHILD_SA exchange - (creating child SAs, rekeying IKE SAs, and rekeying child SAs.) - - The new Section 1.3 with subsections and the above changes might look - like the following. - - NEW-1.3 The CREATE_CHILD_SA Exchange - - The CREATE_CHILD_SA Exchange is used to create new CHILD_SAs and - to rekey both IKE_SAs and CHILD_SAs. This exchange consists of - a single request/response pair, and some of its function was - referred to as a phase 2 exchange in IKEv1. It MAY be initiated - by either end of the IKE_SA after the initial exchanges are - completed. - - All messages following the initial exchange are - cryptographically protected using the cryptographic algorithms - and keys negotiated in the first two messages of the IKE - exchange. These subsequent messages use the syntax of the - Encrypted Payload described in section 3.14. All subsequent - messages include an Encrypted Payload, even if they are referred - to in the text as "empty". - - The CREATE_CHILD_SA is used for rekeying IKE_SAs and CHILD_SAs. - This section describes the first part of rekeying, the creation - of new SAs; Section 2.8 covers the mechanics of rekeying, - including moving traffic from old to new SAs and the deletion of - the old SAs. The two sections must be read together to - understand the entire process of rekeying. - - - - - -Eronen & Hoffman Informational [Page 14] - -RFC 4718 IKEv2 Clarifications October 2006 - - - Either endpoint may initiate a CREATE_CHILD_SA exchange, so in - this section the term initiator refers to the endpoint - initiating this exchange. An implementation MAY refuse all - CREATE_CHILD_SA requests within an IKE_SA. - - The CREATE_CHILD_SA request MAY optionally contain a KE payload - for an additional Diffie-Hellman exchange to enable stronger - guarantees of forward secrecy for the CHILD_SA or IKE_SA. The - keying material for the SA is a function of SK_d established - during the establishment of the IKE_SA, the nonces exchanged - during the CREATE_CHILD_SA exchange, and the Diffie-Hellman - value (if KE payloads are included in the CREATE_CHILD_SA - exchange). The details are described in sections 2.17 and 2.18. - - If a CREATE_CHILD_SA exchange includes a KEi payload, at least - one of the SA offers MUST include the Diffie-Hellman group of - the KEi. The Diffie-Hellman group of the KEi MUST be an element - of the group the initiator expects the responder to accept - (additional Diffie-Hellman groups can be proposed). If the - responder rejects the Diffie-Hellman group of the KEi payload, - the responder MUST reject the request and indicate its preferred - Diffie-Hellman group in the INVALID_KE_PAYLOAD Notification - payload. In the case of such a rejection, the CREATE_CHILD_SA - exchange fails, and the initiator SHOULD retry the exchange with - a Diffie-Hellman proposal and KEi in the group that the - responder gave in the INVALID_KE_PAYLOAD. - - NEW-1.3.1 Creating New CHILD_SAs with the CREATE_CHILD_SA Exchange - - A CHILD_SA may be created by sending a CREATE_CHILD_SA request. - The CREATE_CHILD_SA request for creating a new CHILD_SA is: - - Initiator Responder - ----------- ----------- - HDR, SK {[N+], SA, Ni, [KEi], - TSi, TSr} --> - - The initiator sends SA offer(s) in the SA payload, a nonce in - the Ni payload, optionally a Diffie-Hellman value in the KEi - payload, and the proposed traffic selectors for the proposed - CHILD_SA in the TSi and TSr payloads. The request can also - contain Notify payloads that specify additional details for the - CHILD_SA: these include IPCOMP_SUPPORTED, USE_TRANSPORT_MODE, - ESP_TFC_PADDING_NOT_SUPPORTED, and NON_FIRST_FRAGMENTS_ALSO. - - - - - - - -Eronen & Hoffman Informational [Page 15] - -RFC 4718 IKEv2 Clarifications October 2006 - - - The CREATE_CHILD_SA response for creating a new CHILD_SA is: - - <-- HDR, SK {[N+], SA, Nr, - [KEr], TSi, TSr} - - The responder replies with the accepted offer in an SA payload, - and a Diffie-Hellman value in the KEr payload if KEi was - included in the request and the selected cryptographic suite - includes that group. As with the request, optional Notification - payloads can specify additional details for the CHILD_SA. - - The traffic selectors for traffic to be sent on that SA are - specified in the TS payloads in the response, which may be a - subset of what the initiator of the CHILD_SA proposed. - - The text about rekeying SAs can be found in Section 5.1 of this - document. - -4.2. Creating an IKE_SA without a CHILD_SA - - CHILD_SAs can be created either by being piggybacked on the IKE_AUTH - exchange, or using a separate CREATE_CHILD_SA exchange. The - specification is not clear about what happens if creating the - CHILD_SA during the IKE_AUTH exchange fails for some reason. - - Our recommendation in this situation is that the IKE_SA is created as - usual. This is also in line with how the CREATE_CHILD_SA exchange - works: a failure to create a CHILD_SA does not close the IKE_SA. - - The list of responses in the IKE_AUTH exchange that do not prevent an - IKE_SA from being set up include at least the following: - NO_PROPOSAL_CHOSEN, TS_UNACCEPTABLE, SINGLE_PAIR_REQUIRED, - INTERNAL_ADDRESS_FAILURE, and FAILED_CP_REQUIRED. - - (References: "Questions about internal address" thread, April 2005.) - -4.3. Diffie-Hellman for First CHILD_SA - - Section 1.2 shows that IKE_AUTH messages do not contain KEi/KEr or - Ni/Nr payloads. This implies that the SA payload in IKE_AUTH - exchange cannot contain Transform Type 4 (Diffie-Hellman Group) with - any other value than NONE. Implementations should probably leave the - transform out entirely in this case. - - - - - - - - -Eronen & Hoffman Informational [Page 16] - -RFC 4718 IKEv2 Clarifications October 2006 - - -4.4. Extended Sequence Numbers (ESN) Transform - - The description of the ESN transform in Section 3.3 has be proved - difficult to understand. The ESN transform has the following - meaning: - - o A proposal containing one ESN transform with value 0 means "do not - use extended sequence numbers". - - o A proposal containing one ESN transform with value 1 means "use - extended sequence numbers". - - o A proposal containing two ESN transforms with values 0 and 1 means - "I support both normal and extended sequence numbers, you choose". - (Obviously this case is only allowed in requests; the response - will contain only one ESN transform.) - - In most cases, the exchange initiator will include either the first - or third alternative in its SA payload. The second alternative is - rarely useful for the initiator: it means that using normal sequence - numbers is not acceptable (so if the responder does not support ESNs, - the exchange will fail with NO_PROPOSAL_CHOSEN). - - Note that including the ESN transform is mandatory when creating - ESP/AH SAs (it was optional in earlier drafts of the IKEv2 - specification). - - (References: "Technical change needed to IKEv2 before publication", - "STRAW POLL: Dealing with the ESN negotiation interop issue in IKEv2" - and "Results of straw poll regarding: IKEv2 interoperability issue" - threads, March-April 2005.) - -4.5. Negotiation of ESP_TFC_PADDING_NOT_SUPPORTED - - The description of ESP_TFC_PADDING_NOT_SUPPORTED notification in - Section 3.10.1 says that "This notification asserts that the sending - endpoint will NOT accept packets that contain Flow Confidentiality - (TFC) padding". - - However, the text does not say in which messages this notification - should be included, or whether the scope of this notification is a - single CHILD_SA or all CHILD_SAs of the peer. - - Our interpretation is that the scope is a single CHILD_SA, and thus - this notification is included in messages containing an SA payload - negotiating a CHILD_SA. If neither endpoint accepts TFC padding, - this notification will be included in both the request proposing an - SA and the response accepting it. If this notification is included - - - -Eronen & Hoffman Informational [Page 17] - -RFC 4718 IKEv2 Clarifications October 2006 - - - in only one of the messages, TFC padding can still be sent in one - direction. - -4.6. Negotiation of NON_FIRST_FRAGMENTS_ALSO - - NON_FIRST_FRAGMENTS_ALSO notification is described in Section 3.10.1 - simply as "Used for fragmentation control. See [RFC4301] for - explanation." - - [RFC4301] says "Implementations that will transmit non-initial - fragments on a tunnel mode SA that makes use of non-trivial port (or - ICMP type/code or MH type) selectors MUST notify a peer via the IKE - NOTIFY NON_FIRST_FRAGMENTS_ALSO payload. The peer MUST reject this - proposal if it will not accept non-initial fragments in this context. - If an implementation does not successfully negotiate transmission of - non-initial fragments for such an SA, it MUST NOT send such fragments - over the SA." - - However, it is not clear exactly how the negotiation works. Our - interpretation is that the negotiation works the same way as for - IPCOMP_SUPPORTED and USE_TRANSPORT_MODE: sending non-first fragments - is enabled only if NON_FIRST_FRAGMENTS_ALSO notification is included - in both the request proposing an SA and the response accepting it. - In other words, if the peer "rejects this proposal", it only omits - NON_FIRST_FRAGMENTS_ALSO notification from the response, but does not - reject the whole CHILD_SA creation. - -4.7. Semantics of Complex Traffic Selector Payloads - - As described in Section 3.13, the TSi/TSr payloads can include one or - more individual traffic selectors. - - There is no requirement that TSi and TSr contain the same number of - individual traffic selectors. Thus, they are interpreted as follows: - a packet matches a given TSi/TSr if it matches at least one of the - individual selectors in TSi, and at least one of the individual - selectors in TSr. - - For instance, the following traffic selectors: - - TSi = ((17, 100, 192.0.1.66-192.0.1.66), - (17, 200, 192.0.1.66-192.0.1.66)) - TSr = ((17, 300, 0.0.0.0-255.255.255.255), - (17, 400, 0.0.0.0-255.255.255.255)) - - would match UDP packets from 192.0.1.66 to anywhere, with any of the - four combinations of source/destination ports (100,300), (100,400), - (200,300), and (200, 400). - - - -Eronen & Hoffman Informational [Page 18] - -RFC 4718 IKEv2 Clarifications October 2006 - - - This implies that some types of policies may require several CHILD_SA - pairs. For instance, a policy matching only source/destination ports - (100,300) and (200,400), but not the other two combinations, cannot - be negotiated as a single CHILD_SA pair using IKEv2. - - (References: "IKEv2 Traffic Selectors?" thread, Feb 2005.) - -4.8. ICMP Type/Code in Traffic Selector Payloads - - The traffic selector types 7 and 8 can also refer to ICMP type and - code fields. As described in Section 3.13.1, "For the ICMP protocol, - the two one-octet fields Type and Code are treated as a single 16-bit - integer (with Type in the most significant eight bits and Code in the - least significant eight bits) port number for the purposes of - filtering based on this field." - - Since ICMP packets do not have separate source and destination port - fields, there is some room for confusion what exactly the four TS - payloads (two in the request, two in the response, each containing - both start and end port fields) should contain. - - The answer to this question can be found from [RFC4301] Section - 4.4.1.3. - - To give a concrete example, if a host at 192.0.1.234 wants to create - a transport mode SA for sending "Destination Unreachable" packets - (ICMPv4 type 3) to 192.0.2.155, but is not willing to receive them - over this SA pair, the CREATE_CHILD_SA exchange would look like this: - - Initiator Responder - ----------- ----------- - HDR, SK { N(USE_TRANSPORT_MODE), SA, Ni, - TSi(1, 0x0300-0x03FF, 192.0.1.234-192.0.1.234), - TSr(1, 65535-0, 192.0.2.155-192.0.2.155) } --> - - <-- HDR, SK { N(USE_TRANSPORT_MODE), SA, Nr, - TSi(1, 0x0300-0x03FF, 192.0.1.234-192.0.1.234), - TSr(1, 65535-0, 192.0.2.155-192.0.2.155) } - - Since IKEv2 always creates IPsec SAs in pairs, two SAs are also - created in this case, even though the second SA is never used for - data traffic. - - An exchange creating an SA pair that can be used both for sending and - receiving "Destination Unreachable" places the same value in all the - port: - - - - - -Eronen & Hoffman Informational [Page 19] - -RFC 4718 IKEv2 Clarifications October 2006 - - - Initiator Responder - ----------- ----------- - HDR, SK { N(USE_TRANSPORT_MODE), SA, Ni, - TSi(1, 0x0300-0x03FF, 192.0.1.234-192.0.1.234), - TSr(1, 0x0300-0x03FF, 192.0.2.155-192.0.2.155) } --> - - <-- HDR, SK { N(USE_TRANSPORT_MODE), SA, Nr, - TSi(1, 0x0300-0x03FF, 192.0.1.234-192.0.1.234), - TSr(1, 0x0300-0x03FF, 192.0.2.155-192.0.2.155) } - - (References: "ICMP and MH TSs for IKEv2" thread, Sep 2005.) - -4.9. Mobility Header in Traffic Selector Payloads - - Traffic selectors can use IP Protocol ID 135 to match the IPv6 - mobility header [MIPv6]. However, the IKEv2 specification does not - define how to represent the "MH Type" field in traffic selectors. - - At some point, it was expected that this will be defined in a - separate document later. However, [RFC4301] says that "For IKE, the - IPv6 mobility header message type (MH type) is placed in the most - significant eight bits of the 16 bit local "port" selector". The - direction semantics of TSi/TSr port fields are the same as for ICMP - and are described in the previous section. - - (References: Tero Kivinen's mail "Issue #86: Add IPv6 mobility header - message type as selector", 2003-10-14. "ICMP and MH TSs for IKEv2" - thread, Sep 2005.) - -4.10. Narrowing the Traffic Selectors - - Section 2.9 describes how traffic selectors are negotiated when - creating a CHILD_SA. A more concise summary of the narrowing process - is presented below. - - o If the responder's policy does not allow any part of the traffic - covered by TSi/TSr, it responds with TS_UNACCEPTABLE. - - o If the responder's policy allows the entire set of traffic covered - by TSi/TSr, no narrowing is necessary, and the responder can - return the same TSi/TSr values. - - o Otherwise, narrowing is needed. If the responder's policy allows - all traffic covered by TSi[1]/TSr[1] (the first traffic selectors - in TSi/TSr) but not entire TSi/TSr, the responder narrows to an - acceptable subset of TSi/TSr that includes TSi[1]/TSr[1]. - - - - - -Eronen & Hoffman Informational [Page 20] - -RFC 4718 IKEv2 Clarifications October 2006 - - - o If the responder's policy does not allow all traffic covered by - TSi[1]/TSr[1], but does allow some parts of TSi/TSr, it narrows to - an acceptable subset of TSi/TSr. - - In the last two cases, there may be several subsets that are - acceptable (but their union is not); in this case, the responder - arbitrarily chooses one of them and includes ADDITIONAL_TS_POSSIBLE - notification in the response. - -4.11. SINGLE_PAIR_REQUIRED - - The description of the SINGLE_PAIR_REQUIRED notify payload in - Sections 2.9 and 3.10.1 is not fully consistent. - - We do not attempt to describe this payload in this document either, - since it is expected that most implementations will not have policies - that require separate SAs for each address pair. - - Thus, if only some part (or parts) of the TSi/TSr proposed by the - initiator is (are) acceptable to the responder, most responders - should simply narrow TSi/TSr to an acceptable subset (as described in - the last two paragraphs of Section 2.9), rather than use - SINGLE_PAIR_REQUIRED. - -4.12. Traffic Selectors Violating Own Policy - - Section 2.9 describes traffic selector negotiation in great detail. - One aspect of this negotiation that may need some clarification is - that when creating a new SA, the initiator should not propose traffic - selectors that violate its own policy. If this rule is not followed, - valid traffic may be dropped. - - This is best illustrated by an example. Suppose that host A has a - policy whose effect is that traffic to 192.0.1.66 is sent via host B - encrypted using Advanced Encryption Standard (AES), and traffic to - all other hosts in 192.0.1.0/24 is also sent via B, but encrypted - using Triple Data Encryption Standard (3DES). Suppose also that host - B accepts any combination of AES and 3DES. - - If host A now proposes an SA that uses 3DES, and includes TSr - containing (192.0.1.0-192.0.1.0.255), this will be accepted by host - B. Now, host B can also use this SA to send traffic from 192.0.1.66, - but those packets will be dropped by A since it requires the use of - AES for those traffic. Even if host A creates a new SA only for - 192.0.1.66 that uses AES, host B may freely continue to use the first - SA for the traffic. In this situation, when proposing the SA, host A - should have followed its own policy, and included a TSr containing - ((192.0.1.0-192.0.1.65),(192.0.1.67-192.0.1.255)) instead. - - - -Eronen & Hoffman Informational [Page 21] - -RFC 4718 IKEv2 Clarifications October 2006 - - - In general, if (1) the initiator makes a proposal "for traffic X - (TSi/TSr), do SA", and (2) for some subset X' of X, the initiator - does not actually accept traffic X' with SA, and (3) the initiator - would be willing to accept traffic X' with some SA' (!=SA), valid - traffic can be unnecessarily dropped since the responder can apply - either SA or SA' to traffic X'. - - (References: "Question about "narrowing" ..." thread, Feb 2005. - "IKEv2 needs a "policy usage mode"..." thread, Feb 2005. "IKEv2 - Traffic Selectors?" thread, Feb 2005. "IKEv2 traffic selector - negotiation examples", 2004-08-08.) - -4.13. Traffic Selector Authorization - - IKEv2 relies on information in the Peer Authorization Database (PAD) - when determining what kind of IPsec SAs a peer is allowed to create. - This process is described in [RFC4301] Section 4.4.3. When a peer - requests the creation of an IPsec SA with some traffic selectors, the - PAD must contain "Child SA Authorization Data" linking the identity - authenticated by IKEv2 and the addresses permitted for traffic - selectors. - - For example, the PAD might be configured so that authenticated - identity "sgw23.example.com" is allowed to create IPsec SAs for - 192.0.2.0/24, meaning this security gateway is a valid - "representative" for these addresses. Host-to-host IPsec requires - similar entries, linking, for example, "fooserver4.example.com" with - 192.0.1.66/32, meaning this identity a valid "owner" or - "representative" of the address in question. - - As noted in [RFC4301], "It is necessary to impose these constraints - on creation of child SAs to prevent an authenticated peer from - spoofing IDs associated with other, legitimate peers." In the - example given above, a correct configuration of the PAD prevents - sgw23 from creating IPsec SAs with address 192.0.1.66 and prevents - fooserver4 from creating IPsec SAs with addresses from 192.0.2.0/24. - - It is important to note that simply sending IKEv2 packets using some - particular address does not imply a permission to create IPsec SAs - with that address in the traffic selectors. For example, even if - sgw23 would be able to spoof its IP address as 192.0.1.66, it could - not create IPsec SAs matching fooserver4's traffic. - - The IKEv2 specification does not specify how exactly IP address - assignment using configuration payloads interacts with the PAD. Our - interpretation is that when a security gateway assigns an address - - - - - -Eronen & Hoffman Informational [Page 22] - -RFC 4718 IKEv2 Clarifications October 2006 - - - using configuration payloads, it also creates a temporary PAD entry - linking the authenticated peer identity and the newly allocated inner - address. - - It has been recognized that configuring the PAD correctly may be - difficult in some environments. For instance, if IPsec is used - between a pair of hosts whose addresses are allocated dynamically - using Dynamic Host Configuration Protocol (DHCP), it is extremely - difficult to ensure that the PAD specifies the correct "owner" for - each IP address. This would require a mechanism to securely convey - address assignments from the DHCP server and link them to identities - authenticated using IKEv2. - - Due to this limitation, some vendors have been known to configure - their PADs to allow an authenticated peer to create IPsec SAs with - traffic selectors containing the same address that was used for the - IKEv2 packets. In environments where IP spoofing is possible (i.e., - almost everywhere) this essentially allows any peer to create IPsec - SAs with any traffic selectors. This is not an appropriate or secure - configuration in most circumstances. See [Aura05] for an extensive - discussion about this issue, and the limitations of host-to-host - IPsec in general. - -5. Rekeying and Deleting SAs - -5.1. Rekeying SAs with the CREATE_CHILD_SA Exchange - - Continued from Section 4.1 of this document. - - NEW-1.3.2 Rekeying IKE_SAs with the CREATE_CHILD_SA Exchange - - The CREATE_CHILD_SA request for rekeying an IKE_SA is: - - Initiator Responder - ----------- ----------- - HDR, SK {SA, Ni, [KEi]} --> - - The initiator sends SA offer(s) in the SA payload, a nonce in - the Ni payload, and optionally a Diffie-Hellman value in the KEi - payload. - - The CREATE_CHILD_SA response for rekeying an IKE_SA is: - - <-- HDR, SK {SA, Nr, [KEr]} - - - - - - - -Eronen & Hoffman Informational [Page 23] - -RFC 4718 IKEv2 Clarifications October 2006 - - - The responder replies (using the same Message ID to respond) - with the accepted offer in an SA payload, a nonce in the Nr - payload, and, optionally, a Diffie-Hellman value in the KEr - payload. - - The new IKE_SA has its message counters set to 0, regardless of - what they were in the earlier IKE_SA. The window size starts at - 1 for any new IKE_SA. The new initiator and responder SPIs are - supplied in the SPI fields of the SA payloads. - - NEW-1.3.3 Rekeying CHILD_SAs with the CREATE_CHILD_SA Exchange - - The CREATE_CHILD_SA request for rekeying a CHILD_SA is: - - Initiator Responder - ----------- ----------- - HDR, SK {N(REKEY_SA), [N+], SA, - Ni, [KEi], TSi, TSr} --> - - The leading Notify payload of type REKEY_SA identifies the - CHILD_SA being rekeyed, and it contains the SPI that the initiator - expects in the headers of inbound packets. In addition, the - initiator sends SA offer(s) in the SA payload, a nonce in the Ni - payload, optionally a Diffie-Hellman value in the KEi payload, - and the proposed traffic selectors in the TSi and TSr payloads. - The request can also contain Notify payloads that specify - additional details for the CHILD_SA. - - The CREATE_CHILD_SA response for rekeying a CHILD_SA is: - - <-- HDR, SK {[N+], SA, Nr, - [KEr], TSi, TSr} - - The responder replies with the accepted offer in an SA payload, - and a Diffie-Hellman value in the KEr payload if KEi was - included in the request and the selected cryptographic suite - includes that group. - - The traffic selectors for traffic to be sent on that SA are - specified in the TS payloads in the response, which may be a - subset of what the initiator of the CHILD_SA proposed. - -5.2. Rekeying the IKE_SA vs. Reauthentication - - Rekeying the IKE_SA and reauthentication are different concepts in - IKEv2. Rekeying the IKE_SA establishes new keys for the IKE_SA and - resets the Message ID counters, but it does not authenticate the - parties again (no AUTH or EAP payloads are involved). - - - -Eronen & Hoffman Informational [Page 24] - -RFC 4718 IKEv2 Clarifications October 2006 - - - While rekeying the IKE_SA may be important in some environments, - reauthentication (the verification that the parties still have access - to the long-term credentials) is often more important. - - IKEv2 does not have any special support for reauthentication. - Reauthentication is done by creating a new IKE_SA from scratch (using - IKE_SA_INIT/IKE_AUTH exchanges, without any REKEY_SA notify - payloads), creating new CHILD_SAs within the new IKE_SA (without - REKEY_SA notify payloads), and finally deleting the old IKE_SA (which - deletes the old CHILD_SAs as well). - - This means that reauthentication also establishes new keys for the - IKE_SA and CHILD_SAs. Therefore, while rekeying can be performed - more often than reauthentication, the situation where "authentication - lifetime" is shorter than "key lifetime" does not make sense. - - While creation of a new IKE_SA can be initiated by either party - (initiator or responder in the original IKE_SA), the use of EAP - authentication and/or configuration payloads means in practice that - reauthentication has to be initiated by the same party as the - original IKE_SA. IKEv2 base specification does not allow the - responder to request reauthentication in this case; however, this - functionality is added in [ReAuth]. - - (References: "Reauthentication in IKEv2" thread, Oct/Nov 2004.) - -5.3. SPIs When Rekeying the IKE_SA - - Section 2.18 says that "New initiator and responder SPIs are supplied - in the SPI fields". This refers to the SPI fields in the Proposal - structures inside the Security Association (SA) payloads, not the SPI - fields in the IKE header. - - (References: Tom Stiemerling's mail "Rekey IKE SA", 2005-01-24. - Geoffrey Huang's reply, 2005-01-24.) - -5.4. SPI When Rekeying a CHILD_SA - - Section 3.10.1 says that in REKEY_SA notifications, "The SPI field - identifies the SA being rekeyed." - - Since CHILD_SAs always exist in pairs, there are two different SPIs. - The SPI placed in the REKEY_SA notification is the SPI the exchange - initiator would expect in inbound ESP or AH packets (just as in - Delete payloads). - - - - - - -Eronen & Hoffman Informational [Page 25] - -RFC 4718 IKEv2 Clarifications October 2006 - - -5.5. Changing PRFs When Rekeying the IKE_SA - - When rekeying the IKE_SA, Section 2.18 says that "SKEYSEED for the - new IKE_SA is computed using SK_d from the existing IKE_SA as - follows: - - SKEYSEED = prf(SK_d (old), [g^ir (new)] | Ni | Nr)" - - If the old and new IKE_SA selected a different PRF, it is not totally - clear which PRF should be used. - - Since the rekeying exchange belongs to the old IKE_SA, it is the old - IKE_SA's PRF that is used. This also follows the principle that the - same key (the old SK_d) should not be used with multiple - cryptographic algorithms. - - Note that this may work poorly if the new IKE_SA's PRF has a fixed - key size, since the output of the PRF may not be of the correct size. - This supports our opinion earlier in the document that the use of - PRFs with a fixed key size is a bad idea. - - (References: "Changing PRFs when rekeying the IKE_SA" thread, June - 2005.) - -5.6. Deleting vs. Closing SAs - - The IKEv2 specification talks about "closing" and "deleting" SAs, but - it is not always clear what exactly is meant. However, other parts - of the specification make it clear that when local state related to a - CHILD_SA is removed, the SA must also be actively deleted with a - Delete payload. - - In particular, Section 2.4 says that "If an IKE endpoint chooses to - delete CHILD_SAs, it MUST send Delete payloads to the other end - notifying it of the deletion". Section 1.4 also explains that "ESP - and AH SAs always exist in pairs, with one SA in each direction. - When an SA is closed, both members of the pair MUST be closed." - -5.7. Deleting a CHILD_SA Pair - - Section 1.4 describes how to delete SA pairs using the Informational - exchange: "To delete an SA, an INFORMATIONAL exchange with one or - more delete payloads is sent listing the SPIs (as they would be - expected in the headers of inbound packets) of the SAs to be deleted. - The recipient MUST close the designated SAs." - - - - - - -Eronen & Hoffman Informational [Page 26] - -RFC 4718 IKEv2 Clarifications October 2006 - - - The "one or more delete payloads" phrase has caused some confusion. - You never send delete payloads for the two sides of an SA in a single - message. If you have many SAs to delete at the same time (such as - the nested example given in that paragraph), you include delete - payloads for the inbound half of each SA in your Informational - exchange. - -5.8. Deleting an IKE_SA - - Since IKE_SAs do not exist in pairs, it is not totally clear what the - response message should contain when the request deleted the IKE_SA. - - Since there is no information that needs to be sent to the other side - (except that the request was received), an empty Informational - response seems like the most logical choice. - - (References: "Question about delete IKE SA" thread, May 2005.) - -5.9. Who is the original initiator of IKE_SA - - In the IKEv2 document, "initiator" refers to the party who initiated - the exchange being described, and "original initiator" refers to the - party who initiated the whole IKE_SA. However, there is some - potential for confusion because the IKE_SA can be rekeyed by either - party. - - To clear up this confusion, we propose that "original initiator" - always refers to the party who initiated the exchange that resulted - in the current IKE_SA. In other words, if the "original responder" - starts rekeying the IKE_SA, that party becomes the "original - initiator" of the new IKE_SA. - - (References: Paul Hoffman's mail "Original initiator in IKEv2", - 2005-04-21.) - -5.10. Comparing Nonces - - Section 2.8 about rekeying says that "If redundant SAs are created - though such a collision, the SA created with the lowest of the four - nonces used in the two exchanges SHOULD be closed by the endpoint - that created it." - - - - - - - - - - -Eronen & Hoffman Informational [Page 27] - -RFC 4718 IKEv2 Clarifications October 2006 - - - Here "lowest" uses an octet-by-octet (lexicographical) comparison - (instead of, for instance, comparing the nonces as large integers). - In other words, start by comparing the first octet; if they're equal, - move to the next octet, and so on. If you reach the end of one - nonce, that nonce is the lower one. - - (References: "IKEv2 rekeying question" thread, July 2005.) - -5.11. Exchange Collisions - - Since IKEv2 exchanges can be initiated by both peers, it is possible - that two exchanges affecting the same SA partly overlap. This can - lead to a situation where the SA state information is temporarily not - synchronized, and a peer can receive a request it cannot process in a - normal fashion. Some of these corner cases are discussed in the - specification, some are not. - - Obviously, using a window size greater than one leads to infinitely - more complex situations, especially if requests are processed out of - order. In this section, we concentrate on problems that can arise - even with window size 1. - - (References: "IKEv2: invalid SPI in DELETE payload" thread, Dec 2005/ - Jan 2006. "Problem with exchanges collisions" thread, Dec 2005.) - -5.11.1. Simultaneous CHILD_SA Close - - Probably the simplest case happens if both peers decide to close the - same CHILD_SA pair at the same time: - - Host A Host B - -------- -------- - send req1: D(SPIa) --> - <-- send req2: D(SPIb) - --> recv req1 - <-- send resp1: () - recv resp1 - recv req2 - send resp2: () --> - --> recv resp2 - - This case is described in Section 1.4 and is handled by omitting the - Delete payloads from the response messages. - - - - - - - - -Eronen & Hoffman Informational [Page 28] - -RFC 4718 IKEv2 Clarifications October 2006 - - -5.11.2. Simultaneous IKE_SA Close - - Both peers can also decide to close the IKE_SA at the same time. The - desired end result is obvious; however, in certain cases the final - exchanges may not be fully completed. - - Host A Host B - -------- -------- - send req1: D() --> - <-- send req2: D() - --> recv req1 - - At this point, host B should reply as usual (with empty Informational - response), close the IKE_SA, and stop retransmitting req2. This is - because once host A receives resp1, it may not be able to reply any - longer. The situation is symmetric, so host A should behave the same - way. - - Host A Host B - -------- -------- - <-- send resp1: () - send resp2: () - - Even if neither resp1 nor resp2 ever arrives, the end result is still - correct: the IKE_SA is gone. The same happens if host A never - receives req2. - -5.11.3. Simultaneous CHILD_SA Rekeying - - Another case that is described in the specification is simultaneous - rekeying. Section 2.8 says - - "If the two ends have the same lifetime policies, it is possible - that both will initiate a rekeying at the same time (which will - result in redundant SAs). To reduce the probability of this - happening, the timing of rekeying requests SHOULD be jittered - (delayed by a random amount of time after the need for rekeying is - noticed). - - This form of rekeying may temporarily result in multiple similar - SAs between the same pairs of nodes. When there are two SAs - eligible to receive packets, a node MUST accept incoming packets - through either SA. If redundant SAs are created though such a - collision, the SA created with the lowest of the four nonces used - in the two exchanges SHOULD be closed by the endpoint that created - it." - - - - - -Eronen & Hoffman Informational [Page 29] - -RFC 4718 IKEv2 Clarifications October 2006 - - - However, a better explanation on what impact this has on - implementations is needed. Assume that hosts A and B have an - existing IPsec SA pair with SPIs (SPIa1,SPIb1), and both start - rekeying it at the same time: - - Host A Host B - -------- -------- - send req1: N(REKEY_SA,SPIa1), - SA(..,SPIa2,..),Ni1,.. --> - <-- send req2: N(REKEY_SA,SPIb1), - SA(..,SPIb2,..),Ni2,.. - recv req2 <-- - - At this point, A knows there is a simultaneous rekeying going on. - However, it cannot yet know which of the exchanges will have the - lowest nonce, so it will just note the situation and respond as - usual. - - send resp2: SA(..,SPIa3,..),Nr1,.. --> - --> recv req1 - - Now B also knows that simultaneous rekeying is going on. Similarly - as host A, it has to respond as usual. - - <-- send resp1: SA(..,SPIb3,..),Nr2,.. - recv resp1 <-- - --> recv resp2 - - At this point, there are three CHILD_SA pairs between A and B (the - old one and two new ones). A and B can now compare the nonces. - Suppose that the lowest nonce was Nr1 in message resp2; in this case, - B (the sender of req2) deletes the redundant new SA, and A (the node - that initiated the surviving rekeyed SA) deletes the old one. - - send req3: D(SPIa1) --> - <-- send req4: D(SPIb2) - --> recv req3 - <-- send resp4: D(SPIb1) - recv req4 <-- - send resp4: D(SPIa3) --> - - The rekeying is now finished. - - However, there is a second possible sequence of events that can - happen if some packets are lost in the network, resulting in - retransmissions. The rekeying begins as usual, but A's first packet - (req1) is lost. - - - - -Eronen & Hoffman Informational [Page 30] - -RFC 4718 IKEv2 Clarifications October 2006 - - - Host A Host B - -------- -------- - send req1: N(REKEY_SA,SPIa1), - SA(..,SPIa2,..),Ni1,.. --> (lost) - <-- send req2: N(REKEY_SA,SPIb1), - SA(..,SPIb2,..),Ni2,.. - recv req2 <-- - send resp2: SA(..,SPIa3,..),Nr1,.. --> - --> recv resp2 - <-- send req3: D(SPIb1) - recv req3 <-- - send resp3: D(SPIa1) --> - --> recv resp3 - - From B's point of view, the rekeying is now completed, and since it - has not yet received A's req1, it does not even know that these was - simultaneous rekeying. However, A will continue retransmitting the - message, and eventually it will reach B. - - resend req1 --> - --> recv req1 - - What should B do in this point? To B, it looks like A is trying to - rekey an SA that no longer exists; thus failing the request with - something non-fatal such as NO_PROPOSAL_CHOSEN seems like a - reasonable approach. - - <-- send resp1: N(NO_PROPOSAL_CHOSEN) - recv resp1 <-- - - When A receives this error, it already knows there was simultaneous - rekeying, so it can ignore the error message. - -5.11.4. Simultaneous IKE_SA Rekeying - - Probably the most complex case occurs when both peers try to rekey - the IKE_SA at the same time. Basically, the text in Section 2.8 - applies to this case as well; however, it is important to ensure that - the CHILD_SAs are inherited by the right IKE_SA. - - The case where both endpoints notice the simultaneous rekeying works - the same way as with CHILD_SAs. After the CREATE_CHILD_SA exchanges, - three IKE_SAs exist between A and B; the one containing the lowest - nonce inherits the CHILD_SAs. - - However, there is a twist to the other case where one rekeying - finishes first: - - - - -Eronen & Hoffman Informational [Page 31] - -RFC 4718 IKEv2 Clarifications October 2006 - - - Host A Host B - -------- -------- - send req1: - SA(..,SPIa1,..),Ni1,.. --> - <-- send req2: SA(..,SPIb1,..),Ni2,.. - --> recv req1 - <-- send resp1: SA(..,SPIb2,..),Nr2,.. - recv resp1 <-- - send req3: D() --> - --> recv req3 - - At this point, host B sees a request to close the IKE_SA. There's - not much more to do than to reply as usual. However, at this point - host B should stop retransmitting req2, since once host A receives - resp3, it will delete all the state associated with the old IKE_SA - and will not be able to reply to it. - - <-- send resp3: () - -5.11.5. Closing and Rekeying a CHILD_SA - - A case similar to simultaneous rekeying can occur if one peer decides - to close an SA and the other peer tries to rekey it: - - Host A Host B - -------- -------- - send req1: D(SPIa) --> - <-- send req2: N(REKEY_SA,SPIb),SA,.. - --> recv req1 - - At this point, host B notices that host A is trying to close an SA - that host B is currently rekeying. Replying as usual is probably the - best choice: - - <-- send resp1: D(SPIb) - - Depending on in which order req2 and resp1 arrive, host A sees either - a request to rekey an SA that it is currently closing, or a request - to rekey an SA that does not exist. In both cases, - NO_PROPOSAL_CHOSEN is probably fine. - - recv req2 - recv resp1 - send resp2: N(NO_PROPOSAL_CHOSEN) --> - --> recv resp2 - - - - - - -Eronen & Hoffman Informational [Page 32] - -RFC 4718 IKEv2 Clarifications October 2006 - - -5.11.6. Closing a New CHILD_SA - - Yet another case occurs when host A creates a CHILD_SA pair, but soon - thereafter host B decides to delete it (possible because its policy - changed): - - Host A Host B - -------- -------- - send req1: [N(REKEY_SA,SPIa1)], - SA(..,SPIa2,..),.. --> - --> recv req1 - (lost) <-- send resp1: SA(..,SPIb2,..),.. - - <-- send req2: D(SPIb2) - recv req2 - - At this point, host A has not yet received message resp1 (and is - retransmitting message req1), so it does not recognize SPIb in - message req2. What should host A do? - - One option would be to reply with an empty Informational response. - However, this same reply would also be sent if host A has received - resp1, but has already sent a new request to delete the SA that was - just created. This would lead to a situation where the peers are no - longer in sync about which SAs exist between them. However, host B - would eventually notice that the other half of the CHILD_SA pair has - not been deleted. Section 1.4 describes this case and notes that "a - node SHOULD regard half-closed connections as anomalous and audit - their existence should they persist", and continues that "if - connection state becomes sufficiently messed up, a node MAY close the - IKE_SA". - - Another solution that has been proposed is to reply with an - INVALID_SPI notification that contains SPIb. This would explicitly - tell host B that the SA was not deleted, so host B could try deleting - it again later. However, this usage is not part of the IKEv2 - specification and would not be in line with normal use of the - INVALID_SPI notification where the data field contains the SPI the - recipient of the notification would put in outbound packets. - - Yet another solution would be to ignore req2 at this time and wait - until we have received resp1. However, this alternative has not been - fully analyzed at this time; in general, ignoring valid requests is - always a bit dangerous, because both endpoints could do it, leading - to a deadlock. - - This document recommends the first alternative. - - - - -Eronen & Hoffman Informational [Page 33] - -RFC 4718 IKEv2 Clarifications October 2006 - - -5.11.7. Rekeying a New CHILD_SA - - Yet another case occurs when a CHILD_SA is rekeyed soon after it has - been created: - - Host A Host B - -------- -------- - send req1: [N(REKEY_SA,SPIa1)], - SA(..,SPIa2,..),.. --> - (lost) <-- send resp1: SA(..,SPIb2,..),.. - - <-- send req2: N(REKEY_SA,SPIb2), - SA(..,SPIb3,..),.. - recv req2 <-- - - To host A, this looks like a request to rekey an SA that does not - exist. Like in the simultaneous rekeying case, replying with - NO_PROPOSAL_CHOSEN is probably reasonable: - - send resp2: N(NO_PROPOSAL_CHOSEN) --> - recv resp1 - -5.11.8. Collisions with IKE_SA Rekeying - - Another set of cases occurs when one peer starts rekeying the IKE_SA - at the same time the other peer starts creating, rekeying, or closing - a CHILD_SA. Suppose that host B starts creating a CHILD_SA, and soon - after, host A starts rekeying the IKE_SA: - - Host A Host B - -------- -------- - <-- send req1: SA,Ni1,TSi,TSr - send req2: SA,Ni2,.. --> - --> recv req2 - - What should host B do at this point? Replying as usual would seem - like a reasonable choice: - - <-- send resp2: SA,Ni2,.. - recv resp2 <-- - send req3: D() --> - --> recv req3 - - Now, a problem arises: If host B now replies normally with an empty - Informational response, this will cause host A to delete state - associated with the IKE_SA. This means host B should stop - retransmitting req1. However, host B cannot know whether or not host - A has received req1. If host A did receive it, it will move the - - - -Eronen & Hoffman Informational [Page 34] - -RFC 4718 IKEv2 Clarifications October 2006 - - - CHILD_SA to the new IKE_SA as usual, and the state information will - then be out of sync. - - It seems this situation is tricky to handle correctly. Our proposal - is as follows: if a host receives a request to rekey the IKE_SA when - it has CHILD_SAs in "half-open" state (currently being created or - rekeyed), it should reply with NO_PROPOSAL_CHOSEN. If a host - receives a request to create or rekey a CHILD_SA after it has started - rekeying the IKE_SA, it should reply with NO_ADDITIONAL_SAS. - - The case where CHILD_SAs are being closed is even worse. Our - recommendation is that if a host receives a request to rekey the - IKE_SA when it has CHILD_SAs in "half-closed" state (currently being - closed), it should reply with NO_PROPOSAL_CHOSEN. And if a host - receives a request to close a CHILD_SA after it has started rekeying - the IKE_SA, it should reply with an empty Informational response. - This ensures that at least the other peer will eventually notice that - the CHILD_SA is still in "half-closed" state and will start a new - IKE_SA from scratch. - -5.11.9. Closing and Rekeying the IKE_SA - - The final case considered in this section occurs if one peer decides - to close the IKE_SA while the other peer tries to rekey it. - - Host A Host B - -------- -------- - send req1: SA(..,SPIa1,..),Ni1 --> - <-- send req2: D() - --> recv req1 - recv req2 <-- - - At this point, host B should probably reply with NO_PROPOSAL_CHOSEN, - and host A should reply as usual, close the IKE_SA, and stop - retransmitting req1. - - <-- send resp1: N(NO_PROPOSAL_CHOSEN) - send resp2: () - - If host A wants to continue communication with B, it can now start a - new IKE_SA. - -5.11.10. Summary - - If a host receives a request to rekey: - - o a CHILD_SA pair that the host is currently trying to close: reply - with NO_PROPOSAL_CHOSEN. - - - -Eronen & Hoffman Informational [Page 35] - -RFC 4718 IKEv2 Clarifications October 2006 - - - o a CHILD_SA pair that the host is currently rekeying: reply as - usual, but prepare to close redundant SAs later based on the - nonces. - - o a CHILD_SA pair that does not exist: reply with - NO_PROPOSAL_CHOSEN. - - o the IKE_SA, and the host is currently rekeying the IKE_SA: reply - as usual, but prepare to close redundant SAs and move inherited - CHILD_SAs later based on the nonces. - - o the IKE_SA, and the host is currently creating, rekeying, or - closing a CHILD_SA: reply with NO_PROPOSAL_CHOSEN. - - o the IKE_SA, and the host is currently trying to close the IKE_SA: - reply with NO_PROPOSAL_CHOSEN. - - If a host receives a request to close: - - o a CHILD_SA pair that the host is currently trying to close: reply - without Delete payloads. - - o a CHILD_SA pair that the host is currently rekeying: reply as - usual, with Delete payload. - - o a CHILD_SA pair that does not exist: reply without Delete - payloads. - - o the IKE_SA, and the host is currently rekeying the IKE_SA: reply - as usual, and forget about our own rekeying request. - - o the IKE_SA, and the host is currently trying to close the IKE_SA: - reply as usual, and forget about our own close request. - - If a host receives a request to create or rekey a CHILD_SA when it is - currently rekeying the IKE_SA: reply with NO_ADDITIONAL_SAS. - - If a host receives a request to delete a CHILD_SA when it is - currently rekeying the IKE_SA: reply without Delete payloads. - -5.12. Diffie-Hellman and Rekeying the IKE_SA - - There has been some confusion whether doing a new Diffie-Hellman - exchange is mandatory when the IKE_SA is rekeyed. - - It seems that this case is allowed by the IKEv2 specification. - Section 2.18 shows the Diffie-Hellman term (g^ir) in brackets. - Section 3.3.3 does not contradict this when it says that including - - - -Eronen & Hoffman Informational [Page 36] - -RFC 4718 IKEv2 Clarifications October 2006 - - - the D-H transform is mandatory: although including the transform is - mandatory, it can contain the value "NONE". - - However, having the option to skip the Diffie-Hellman exchange when - rekeying the IKE_SA does not add useful functionality to the - protocol. The main purpose of rekeying the IKE_SA is to ensure that - the compromise of old keying material does not provide information - about the current keys, or vice versa. This requires performing the - Diffie-Hellman exchange when rekeying. Furthermore, it is likely - that this option would have been removed from the protocol as - unnecessary complexity had it been discussed earlier. - - Given this, we recommend that implementations should have a hard- - coded policy that requires performing a new Diffie-Hellman exchange - when rekeying the IKE_SA. In other words, the initiator should not - propose the value "NONE" for the D-H transform, and the responder - should not accept such a proposal. This policy also implies that a - successful exchange rekeying the IKE_SA always includes the KEi/KEr - payloads. - - (References: "Rekeying IKE_SAs with the CREATE_CHILD_SA exhange" - thread, Oct 2005. "Comments of - draft-eronen-ipsec-ikev2-clarifications-02.txt" thread, Apr 2005.) - -6. Configuration Payloads - -6.1. Assigning IP Addresses - - Section 2.9 talks about traffic selector negotiation and mentions - that "In support of the scenario described in section 1.1.3, an - initiator may request that the responder assign an IP address and - tell the initiator what it is." - - This sentence is correct, but its placement is slightly confusing. - IKEv2 does allow the initiator to request assignment of an IP address - from the responder, but this is done using configuration payloads, - not traffic selector payloads. An address in a TSi payload in a - response does not mean that the responder has assigned that address - to the initiator; it only means that if packets matching these - traffic selectors are sent by the initiator, IPsec processing can be - performed as agreed for this SA. The TSi payload itself does not - give the initiator permission to configure the initiator's TCP/IP - stack with the address and use it as its source address. - - In other words, IKEv2 does not have two different mechanisms for - assigning addresses, but only one: configuration payloads. In the - scenario described in Section 1.1.3, both configuration and traffic - selector payloads are usually included in the same message, and they - - - -Eronen & Hoffman Informational [Page 37] - -RFC 4718 IKEv2 Clarifications October 2006 - - - often contain the same information in the response message (see - Section 6.3 of this document for some examples). However, their - semantics are still different. - -6.2. Requesting any INTERNAL_IP4/IP6_ADDRESS - - When describing the INTERNAL_IP4/IP6_ADDRESS attributes, Section - 3.15.1 says that "In a request message, the address specified is a - requested address (or zero if no specific address is requested)". - The question here is whether "zero" means an address "0.0.0.0" or a - zero-length string. - - Earlier, the same section also says that "If an attribute in the - CFG_REQUEST Configuration Payload is not zero-length, it is taken as - a suggestion for that attribute". Also, the table of configuration - attributes shows that the length of INTERNAL_IP4_ADDRESS is either "0 - or 4 octets", and likewise, INTERNAL_IP6_ADDRESS is either "0 or 17 - octets". - - Thus, if the client does not request a specific address, it includes - a zero-length INTERNAL_IP4/IP6_ADDRESS attribute, not an attribute - containing an all-zeroes address. The example in 2.19 is thus - incorrect, since it shows the attribute as - "INTERNAL_ADDRESS(0.0.0.0)". - - However, since the value is only a suggestion, implementations are - recommended to ignore suggestions they do not accept; or in other - words, to treat the same way a zero-length INTERNAL_IP4_ADDRESS, - "0.0.0.0", and any other addresses the implementation does not - recognize as a reasonable suggestion. - -6.3. INTERNAL_IP4_SUBNET/INTERNAL_IP6_SUBNET - - Section 3.15.1 describes the INTERNAL_IP4_SUBNET as "The protected - sub-networks that this edge-device protects. This attribute is made - up of two fields: the first is an IP address and the second is a - netmask. Multiple sub-networks MAY be requested. The responder MAY - respond with zero or more sub-network attributes." - INTERNAL_IP6_SUBNET is defined in a similar manner. - - This raises two questions: first, since this information is usually - included in the TSr payload, what functionality does this attribute - add? And second, what does this attribute mean in CFG_REQUESTs? - - For the first question, there seem to be two sensible - interpretations. Clearly TSr (in IKE_AUTH or CREATE_CHILD_SA - response) indicates which subnets are accessible through the SA that - was just created. - - - -Eronen & Hoffman Informational [Page 38] - -RFC 4718 IKEv2 Clarifications October 2006 - - - The first interpretation of the INTERNAL_IP4/6_SUBNET attributes is - that they indicate additional subnets that can be reached through - this gateway, but need a separate SA. According to this - interpretation, the INTERNAL_IP4/6_SUBNET attributes are useful - mainly when they contain addresses not included in TSr. - - The second interpretation is that the INTERNAL_IP4/6_SUBNET - attributes express the gateway's policy about what traffic should be - sent through the gateway. The client can choose whether other - traffic (covered by TSr, but not in INTERNAL_IP4/6_SUBNET) is sent - through the gateway or directly to the destination. According to - this interpretation, the attributes are useful mainly when TSr - contains addresses not included in the INTERNAL_IP4/6_SUBNET - attributes. - - It turns out that these two interpretations are not incompatible, but - rather two sides of the same principle: traffic to the addresses - listed in the INTERNAL_IP4/6_SUBNET attributes should be sent via - this gateway. If there are no existing IPsec SAs whose traffic - selectors cover the address in question, new SAs have to be created. - - A couple of examples are given below. For instance, if there are two - subnets, 192.0.1.0/26 and 192.0.2.0/24, and the client's request - contains the following: - - CP(CFG_REQUEST) = - INTERNAL_IP4_ADDRESS() - TSi = (0, 0-65535, 0.0.0.0-255.255.255.255) - TSr = (0, 0-65535, 0.0.0.0-255.255.255.255) - - Then a valid response could be the following (in which TSr and - INTERNAL_IP4_SUBNET contain the same information): - - CP(CFG_REPLY) = - INTERNAL_IP4_ADDRESS(192.0.1.234) - INTERNAL_IP4_SUBNET(192.0.1.0/255.255.255.192) - INTERNAL_IP4_SUBNET(192.0.2.0/255.255.255.0) - TSi = (0, 0-65535, 192.0.1.234-192.0.1.234) - TSr = ((0, 0-65535, 192.0.1.0-192.0.1.63), - (0, 0-65535, 192.0.2.0-192.0.2.255)) - - In these cases, the INTERNAL_IP4_SUBNET does not really carry any - useful information. Another possible reply would have been this: - - CP(CFG_REPLY) = - INTERNAL_IP4_ADDRESS(192.0.1.234) - INTERNAL_IP4_SUBNET(192.0.1.0/255.255.255.192) - INTERNAL_IP4_SUBNET(192.0.2.0/255.255.255.0) - - - -Eronen & Hoffman Informational [Page 39] - -RFC 4718 IKEv2 Clarifications October 2006 - - - TSi = (0, 0-65535, 192.0.1.234-192.0.1.234) - TSr = (0, 0-65535, 0.0.0.0-255.255.255.255) - - This would mean that the client can send all its traffic through the - gateway, but the gateway does not mind if the client sends traffic - not included by INTERNAL_IP4_SUBNET directly to the destination - (without going through the gateway). - - A different situation arises if the gateway has a policy that - requires the traffic for the two subnets to be carried in separate - SAs. Then a response like this would indicate to the client that if - it wants access to the second subnet, it needs to create a separate - SA: - - CP(CFG_REPLY) = - INTERNAL_IP4_ADDRESS(192.0.1.234) - INTERNAL_IP4_SUBNET(192.0.1.0/255.255.255.192) - INTERNAL_IP4_SUBNET(192.0.2.0/255.255.255.0) - TSi = (0, 0-65535, 192.0.1.234-192.0.1.234) - TSr = (0, 0-65535, 192.0.1.0-192.0.1.63) - - INTERNAL_IP4_SUBNET can also be useful if the client's TSr included - only part of the address space. For instance, if the client requests - the following: - - CP(CFG_REQUEST) = - INTERNAL_IP4_ADDRESS() - TSi = (0, 0-65535, 0.0.0.0-255.255.255.255) - TSr = (0, 0-65535, 192.0.2.155-192.0.2.155) - - Then the gateway's reply could be this: - - CP(CFG_REPLY) = - INTERNAL_IP4_ADDRESS(192.0.1.234) - INTERNAL_IP4_SUBNET(192.0.1.0/255.255.255.192) - INTERNAL_IP4_SUBNET(192.0.2.0/255.255.255.0) - TSi = (0, 0-65535, 192.0.1.234-192.0.1.234) - TSr = (0, 0-65535, 192.0.2.155-192.0.2.155) - - It is less clear what the attributes mean in CFG_REQUESTs, and - whether other lengths than zero make sense in this situation (but for - INTERNAL_IP6_SUBNET, zero length is not allowed at all!). This - document recommends that implementations should not include - INTERNAL_IP4_SUBNET or INTERNAL_IP6_SUBNET attributes in - CFG_REQUESTs. - - For the IPv4 case, this document recommends using only netmasks - consisting of some amount of "1" bits followed by "0" bits; for - - - -Eronen & Hoffman Informational [Page 40] - -RFC 4718 IKEv2 Clarifications October 2006 - - - instance, "255.0.255.0" would not be a valid netmask for - INTERNAL_IP4_SUBNET. - - It is also worthwhile to note that the contents of the INTERNAL_IP4/ - 6_SUBNET attributes do not imply link boundaries. For instance, a - gateway providing access to a large company intranet using addresses - from the 10.0.0.0/8 block can send a single INTERNAL_IP4_SUBNET - attribute (10.0.0.0/255.0.0.0) even if the intranet has hundreds of - routers and separate links. - - (References: Tero Kivinen's mail "Intent of couple of attributes in - Configuration Payload in IKEv2?", 2004-11-19. Srinivasa Rao - Addepalli's mail "INTERNAL_IP4_SUBNET and INTERNAL_IP6_SUBNET in - IKEv2", 2004-09-10. Yoav Nir's mail "Re: New I-D: IKEv2 - Clarifications and Implementation Guidelines", 2005-02-07. - "Clarifications open issue: INTERNAL_IP4_SUBNET/NETMASK" thread, - April 2005.) - -6.4. INTERNAL_IP4_NETMASK - - Section 3.15.1 defines the INTERNAL_IP4_NETMASK attribute and says - that "The internal network's netmask. Only one netmask is allowed in - the request and reply messages (e.g., 255.255.255.0) and it MUST be - used only with an INTERNAL_IP4_ADDRESS attribute". - - However, it is not clear what exactly this attribute means, as the - concept of "netmask" is not very well defined for point-to-point - links (unlike multi-access links, where it means "you can reach hosts - inside this netmask directly using layer 2, instead of sending - packets via a router"). Even if the operating system's TCP/IP stack - requires a netmask to be configured, for point-to-point links it - could be just set to 255.255.255.255. So, why is this information - sent in IKEv2? - - One possible interpretation would be that the host is given a whole - block of IP addresses instead of a single address. This is also what - Framed-IP-Netmask does in [RADIUS], the IPCP "subnet mask" extension - does in PPP [IPCPSubnet], and the prefix length in the IPv6 Framed- - IPv6-Prefix attribute does in [RADIUS6]. However, nothing in the - specification supports this interpretation, and discussions on the - IPsec WG mailing list have confirmed it was not intended. Section - 3.15.1 also says that multiple addresses are assigned using multiple - INTERNAL_IP4/6_ADDRESS attributes. - - Currently, this document's interpretation is the following: - INTERNAL_IP4_NETMASK in a CFG_REPLY means roughly the same thing as - INTERNAL_IP4_SUBNET containing the same information ("send traffic to - these addresses through me"), but also implies a link boundary. For - - - -Eronen & Hoffman Informational [Page 41] - -RFC 4718 IKEv2 Clarifications October 2006 - - - instance, the client could use its own address and the netmask to - calculate the broadcast address of the link. (Whether the gateway - will actually deliver broadcast packets to other VPN clients and/or - other nodes connected to this link is another matter.) - - An empty INTERNAL_IP4_NETMASK attribute can be included in a - CFG_REQUEST to request this information (although the gateway can - send the information even when not requested). However, it seems - that non-empty values for this attribute do not make sense in - CFG_REQUESTs. - - Fortunately, Section 4 clearly says that a minimal implementation - does not need to include or understand the INTERNAL_IP4_NETMASK - attribute, and thus this document recommends that implementations - should not use the INTERNAL_IP4_NETMASK attribute or assume that the - other peer supports it. - - (References: Charlie Kaufman's mail "RE: Proposed Last Call based - revisions to IKEv2", 2004-05-27. Email discussion with Tero Kivinen, - Jan 2005. Yoav Nir's mail "Re: New I-D: IKEv2 Clarifications and - Implementation Guidelines", 2005-02-07. "Clarifications open issue: - INTERNAL_IP4_SUBNET/NETMASK" thread, April 2005.) - -6.5. Configuration Payloads for IPv6 - - IKEv2 also defines configuration payloads for IPv6. However, they - are based on the corresponding IPv4 payloads and do not fully follow - the "normal IPv6 way of doing things". - - A client can be assigned an IPv6 address using the - INTERNAL_IP6_ADDRESS configuration payload. A minimal exchange could - look like this: - - CP(CFG_REQUEST) = - INTERNAL_IP6_ADDRESS() - INTERNAL_IP6_DNS() - TSi = (0, 0-65535, :: - FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF) - TSr = (0, 0-65535, :: - FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF) - - CP(CFG_REPLY) = - INTERNAL_IP6_ADDRESS(2001:DB8:0:1:2:3:4:5/64) - INTERNAL_IP6_DNS(2001:DB8:99:88:77:66:55:44) - TSi = (0, 0-65535, 2001:DB8:0:1:2:3:4:5 - 2001:DB8:0:1:2:3:4:5) - TSr = (0, 0-65535, :: - FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF) - - In particular, IPv6 stateless autoconfiguration or router - advertisement messages are not used; neither is neighbor discovery. - - - - -Eronen & Hoffman Informational [Page 42] - -RFC 4718 IKEv2 Clarifications October 2006 - - - The client can also send a non-empty INTERNAL_IP6_ADDRESS attribute - in the CFG_REQUEST to request a specific address or interface - identifier. The gateway first checks if the specified address is - acceptable, and if it is, returns that one. If the address was not - acceptable, the gateway will attempt to use the interface identifier - with some other prefix; if even that fails, the gateway will select - another interface identifier. - - The INTERNAL_IP6_ADDRESS attribute also contains a prefix length - field. When used in a CFG_REPLY, this corresponds to the - INTERNAL_IP4_NETMASK attribute in the IPv4 case (and indeed, was - called INTERNAL_IP6_NETMASK in earlier versions of the IKEv2 draft). - See the previous section for more details. - - While this approach to configuring IPv6 addresses is reasonably - simple, it has some limitations: IPsec tunnels configured using IKEv2 - are not fully-featured "interfaces" in the IPv6 addressing - architecture [IPv6Addr] sense. In particular, they do not - necessarily have link-local addresses, and this may complicate the - use of protocols that assume them, such as [MLDv2]. (Whether they - are called "interfaces" in some particular operating system is a - different issue.) - - (References: "VPN remote host configuration IPv6 ?" thread, May 2004. - "Clarifications open issue: INTERNAL_IP4_SUBNET/NETMASK" thread, - April 2005.) - -6.6. INTERNAL_IP6_NBNS - - Section 3.15.1 defines the INTERNAL_IP6_NBNS attribute for sending - the IPv6 address of NetBIOS name servers. - - However, NetBIOS is not defined for IPv6 and probably never will be. - Thus, this attribute most likely does not make much sense. - - (Pointed out by Bernard Aboba in the IP Configuration Security (ICOS) - BoF at IETF62.) - -6.7. INTERNAL_ADDRESS_EXPIRY - - Section 3.15.1 defines the INTERNAL_ADDRESS_EXPIRY attribute as - "Specifies the number of seconds that the host can use the internal - IP address. The host MUST renew the IP address before this expiry - time. Only one of these attributes MAY be present in the reply." - - Expiry times and explicit renewals are primarily useful in - environments like DHCP, where the server cannot reliably know when - - - - -Eronen & Hoffman Informational [Page 43] - -RFC 4718 IKEv2 Clarifications October 2006 - - - the client has gone away. However, in IKEv2 this is known, and the - gateway can simply free the address when the IKE_SA is deleted. - - Also, Section 4 says that supporting renewals is not mandatory. - Given that this functionality is usually not needed, we recommend - that gateways should not send the INTERNAL_ADDRESS_EXPIRY attribute. - (And since this attribute does not seem to make much sense for - CFG_REQUESTs, clients should not send it either.) - - Note that according to Section 4, clients are required to understand - INTERNAL_ADDRESS_EXPIRY if they receive it. A minimum implementation - would use the value to limit the lifetime of the IKE_SA. - - (References: Tero Kivinen's mail "Comments of - draft-eronen-ipsec-ikev2-clarifications-02.txt", 2005-04-05. - "Questions about internal address" thread, April 2005.) - -6.8. Address Assignment Failures - - If the responder encounters an error while attempting to assign an IP - address to the initiator, it responds with an - INTERNAL_ADDRESS_FAILURE notification as described in Section 3.10.1. - However, there are some more complex error cases. - - First, if the responder does not support configuration payloads at - all, it can simply ignore all configuration payloads. This type of - implementation never sends INTERNAL_ADDRESS_FAILURE notifications. - If the initiator requires the assignment of an IP address, it will - treat a response without CFG_REPLY as an error. - - A second case is where the responder does support configuration - payloads, but only for particular type of addresses (IPv4 or IPv6). - Section 4 says that "A minimal IPv4 responder implementation will - ignore the contents of the CP payload except to determine that it - includes an INTERNAL_IP4_ADDRESS attribute". If, for instance, the - initiator includes both INTERNAL_IP4_ADDRESS and INTERNAL_IP6_ADDRESS - in the CFG_REQUEST, an IPv4-only responder can thus simply ignore the - IPv6 part and process the IPv4 request as usual. - - A third case is where the initiator requests multiple addresses of a - type that the responder supports: what should happen if some (but not - all) of the requests fail? It seems that an optimistic approach - would be the best one here: if the responder is able to assign at - least one address, it replies with those; it sends - INTERNAL_ADDRESS_FAILURE only if no addresses can be assigned. - - (References: "ikev2 and internal_ivpn_address" thread, June 2005.) - - - - -Eronen & Hoffman Informational [Page 44] - -RFC 4718 IKEv2 Clarifications October 2006 - - -7. Miscellaneous Issues - -7.1. Matching ID_IPV4_ADDR and ID_IPV6_ADDR - - When using the ID_IPV4_ADDR/ID_IPV6_ADDR identity types in IDi/IDr - payloads, IKEv2 does not require this address to match anything in - the TSi/TSr payloads. For example, in a site-to-site VPN between two - security gateways, the gateways could authenticate each other as - ID_IPV4_ADDR(192.0.1.1) and ID_IPV4_ADDR(192.0.2.1), and then create - a CHILD_SA for protecting traffic between 192.0.1.55/32 (a host - behind the first security gateway) and 192.0.2.240/28 (a network - behind the second security gateway). The authenticated identities - (IDi/IDr) are linked to the authorized traffic selectors (TSi/TSr) - using "Child SA Authorization Data" in the Peer Authorization - Database (PAD). - - Furthermore, IKEv2 does not require that the addresses in - ID_IPV4_ADDR/ID_IPV6_ADDR match the address in the IP header of the - IKE packets. However, other specifications may place additional - requirements regarding this. For example, [PKI4IPsec] requires that - implementation must be capable of comparing the addresses in the - ID_IPV4_ADDR/ID_IPV6_ADDR with the addresses in the IP header of the - IKE packets, and this comparison must be enabled by default. - - (References: "Identities types IP address,FQDN/user FQDN and DN and - its usage in preshared key authentication" thread, Jan 2005. - "Matching ID_IPV4_ADDR and ID_IPV6_ADDR" thread, May 2006.) - -7.2. Relationship of IKEv2 to RFC 4301 - - The IKEv2 specification refers to [RFC4301], but it never clearly - defines the exact relationship. - - However, there are some requirements in the specification that make - it clear that IKEv2 requires [RFC4301]. In other words, an - implementation that does IPsec processing strictly according to - [RFC2401] cannot be compliant with the IKEv2 specification. - - One such example can be found in Section 2.24: "Specifically, tunnel - encapsulators and decapsulators for all tunnel-mode SAs created by - IKEv2 [...] MUST implement the tunnel encapsulation and - decapsulation processing specified in [RFC4301] to prevent discarding - of ECN congestion indications." - - Nevertheless, the changes required to existing [RFC2401] - implementations are not very large, especially since supporting many - of the new features (such as Extended Sequence Numbers) is optional. - - - - -Eronen & Hoffman Informational [Page 45] - -RFC 4718 IKEv2 Clarifications October 2006 - - -7.3. Reducing the Window Size - - In IKEv2, the window size is assumed to be a (possibly configurable) - property of a particular implementation and is not related to - congestion control (unlike the window size in TCP, for instance). - - In particular, it is not defined what the responder should do when it - receives a SET_WINDOW_SIZE notification containing a smaller value - than is currently in effect. Thus, there is currently no way to - reduce the window size of an existing IKE_SA. However, when rekeying - an IKE_SA, the new IKE_SA starts with window size 1 until it is - explicitly increased by sending a new SET_WINDOW_SIZE notification. - - (References: Tero Kivinen's mail "Comments of - draft-eronen-ipsec-ikev2-clarifications-02.txt", 2005-04-05.) - -7.4. Minimum Size of Nonces - - Section 2.10 says that "Nonces used in IKEv2 MUST be randomly chosen, - MUST be at least 128 bits in size, and MUST be at least half the key - size of the negotiated prf." - - However, the initiator chooses the nonce before the outcome of the - negotiation is known. In this case, the nonce has to be long enough - for all the PRFs being proposed. - -7.5. Initial Zero Octets on Port 4500 - - It is not clear whether a peer sending an IKE_SA_INIT request on port - 4500 should include the initial four zero octets. Section 2.23 talks - about how to upgrade to tunneling over port 4500 after message 2, but - it does not say what to do if message 1 is sent on port 4500. - - IKE MUST listen on port 4500 as well as port 500. - - [...] - - The IKE initiator MUST check these payloads if present and if - they do not match the addresses in the outer packet MUST tunnel - all future IKE and ESP packets associated with this IKE_SA over - UDP port 4500. - - To tunnel IKE packets over UDP port 4500, the IKE header has four - octets of zero prepended and the result immediately follows the - UDP header. [...] - - - - - - -Eronen & Hoffman Informational [Page 46] - -RFC 4718 IKEv2 Clarifications October 2006 - - - The very beginning of Section 2 says "... though IKE messages may - also be received on UDP port 4500 with a slightly different format - (see section 2.23)." - - That "slightly different format" is only described in discussing what - to do after changing to port 4500. However, [RFC3948] shows clearly - the format has the initial zeros even for initiators on port 4500. - Furthermore, without the initial zeros, the processing engine cannot - determine whether the packet is an IKE packet or an ESP packet. - - Thus, all packets sent on port 4500 need the four-zero prefix; - otherwise, the receiver won't know how to handle them. - -7.6. Destination Port for NAT Traversal - - Section 2.23 says that "an IPsec endpoint that discovers a NAT - between it and its correspondent MUST send all subsequent traffic to - and from port 4500". - - This sentence is misleading. The peer "outside" the NAT uses source - port 4500 for the traffic it sends, but the destination port is, of - course, taken from packets sent by the peer behind the NAT. This - port number is usually dynamically allocated by the NAT. - -7.7. SPI Values for Messages outside an IKE_SA - - The IKEv2 specification is not quite clear what SPI values should be - used in the IKE header for the small number of notifications that are - allowed to be sent outside an IKE_SA. Note that such notifications - are explicitly not Informational exchanges; Section 1.5 makes it - clear that these are one-way messages that must not be responded to. - - There are two cases when such a one-way notification can be sent: - INVALID_IKE_SPI and INVALID_SPI. - - In case of INVALID_IKE_SPI, the message sent is a response message, - and Section 2.21 says that "If a response is sent, the response MUST - be sent to the IP address and port from whence it came with the same - IKE SPIs and the Message ID copied." - - In case of INVALID_SPI, however, there are no IKE SPI values that - would be meaningful to the recipient of such a notification. Also, - the message sent is now an INFORMATIONAL request. A strict - interpretation of the specification would require the sender to - invent garbage values for the SPI fields. However, we think this was - not the intention, and using zero values is acceptable. - - (References: "INVALID_IKE_SPI" thread, June 2005.) - - - -Eronen & Hoffman Informational [Page 47] - -RFC 4718 IKEv2 Clarifications October 2006 - - -7.8. Protocol ID/SPI Fields in Notify Payloads - - Section 3.10 says that the Protocol ID field in Notify payloads "For - notifications that do not relate to an existing SA, this field MUST - be sent as zero and MUST be ignored on receipt". However, the - specification does not clearly say which notifications are related to - existing SAs and which are not. - - Since the main purpose of the Protocol ID field is to specify the - type of the SPI, our interpretation is that the Protocol ID field - should be non-zero only when the SPI field is non-empty. - - There are currently only two notifications where this is the case: - INVALID_SELECTORS and REKEY_SA. - -7.9. Which message should contain INITIAL_CONTACT - - The description of the INITIAL_CONTACT notification in Section 3.10.1 - says that "This notification asserts that this IKE_SA is the only - IKE_SA currently active between the authenticated identities". - However, neither Section 2.4 nor 3.10.1 says in which message this - payload should be placed. - - The general agreement is that INITIAL_CONTACT is best communicated in - the first IKE_AUTH request, not as a separate exchange afterwards. - - (References: "Clarifying the use of INITIAL_CONTACT in IKEv2" thread, - April 2005. "Initial Contact messages" thread, December 2004. - "IKEv2 and Initial Contact" thread, September 2004 and April 2005.) - -7.10. Alignment of Payloads - - Many IKEv2 payloads contain fields marked as "RESERVED", mostly - because IKEv1 had them, and partly because they make the pictures - easier to draw. In particular, payloads in IKEv2 are not, in - general, aligned to 4-octet boundaries. (Note that payloads were not - aligned to 4-octet boundaries in IKEv1 either.) - - (References: "IKEv2: potential 4-byte alignment problem" thread, June - 2004.) - -7.11. Key Length Transform Attribute - - Section 3.3.5 says that "The only algorithms defined in this document - that accept attributes are the AES based encryption, integrity, and - pseudo-random functions, which require a single attribute specifying - key width." - - - - -Eronen & Hoffman Informational [Page 48] - -RFC 4718 IKEv2 Clarifications October 2006 - - - This is incorrect. The AES-based integrity and pseudo-random - functions defined in [IKEv2] always use a 128-bit key. In fact, - there are currently no integrity or PRF algorithms that use the key - length attribute (and we recommend that they should not be defined in - the future either). - - For encryption algorithms, the situation is slightly more complex - since there are three different types of algorithms: - - o The key length attribute is never used with algorithms that use a - fixed length key, such as DES and IDEA. - - o The key length attribute is always included for the currently - defined AES-based algorithms (Cipher Block Chaining (CBC), Counter - (CTR) Mode, Counter with CBC-MAC (CCM), and Galois/Counter Mode - (GCM)). Omitting the key length attribute is not allowed; if the - proposal does not contain it, the proposal has to be rejected. - - o For other algorithms, the key length attribute can be included but - is not mandatory. These algorithms include, e.g., RC5, CAST, and - BLOWFISH. If the key length attribute is not included, the - default value specified in [RFC2451] is used. - -7.12. IPsec IANA Considerations - - There are currently three different IANA registry files that contain - important numbers for IPsec: ikev2-registry, isakmp-registry, and - ipsec-registry. Implementers should note that IKEv2 may use numbers - different from those of IKEv1 for a particular algorithm. - - For instance, an encryption algorithm can have up to three different - numbers: the IKEv2 "Transform Type 1" identifier in ikev2-registry, - the IKEv1 phase 1 "Encryption Algorithm" identifier in ipsec- - registry, and the IKEv1 phase 2 "IPSEC ESP Transform Identifier" - isakmp-registry. Although some algorithms have the same number in - all three registries, the registries are not identical. - - Similarly, an integrity algorithm can have at least the IKEv2 - "Transform Type 3" identifier in ikev2-registry, the IKEv1 phase 2 - "IPSEC AH Transform Identifier" in isakmp-registry, and the IKEv1 - phase 2 ESP "Authentication Algorithm Security Association Attribute" - identifier in isakmp-registry. And there is also the IKEv1 phase 1 - "Hash Algorithm" list in ipsec-registry. - - This issue needs special care also when writing a specification for - how a new algorithm is used with IPsec. - - - - - -Eronen & Hoffman Informational [Page 49] - -RFC 4718 IKEv2 Clarifications October 2006 - - -7.13. Combining ESP and AH - - The IKEv2 specification contains some misleading text about how ESP - and AH can be combined. - - IKEv2 is based on [RFC4301], which does not include "SA bundles" that - were part of [RFC2401]. While a single packet can go through IPsec - processing multiple times, each of these passes uses a separate SA, - and the passes are coordinated by the forwarding tables. In IKEv2, - each of these SAs has to be created using a separate CREATE_CHILD_SA - exchange. Thus, the text in Section 2.7 about a single proposal - containing both ESP and AH is incorrect. - - Moreover, the combination of ESP and AH (between the same endpoints) - had already become largely obsolete in 1998 when RFC 2406 was - published. Our recommendation is that IKEv2 implementations should - not support this combination, and implementers should not assume the - combination can be made to work in an interoperable manner. - - (References: "Rekeying SA bundles" thread, Oct 2005.) - -8. Implementation Mistakes - - Some implementers at the early IKEv2 bakeoffs didn't do everything - correctly. This may seem like an obvious statement, but it is - probably useful to list a few things that were clear in the document, - but that some implementers didn't do. All of these things caused - interoperability problems. - - o Some implementations continued to send traffic on a CHILD_SA after - it was rekeyed, even after receiving an DELETE payload. - - o After rekeying an IKE_SA, some implementations did not reset their - message counters to zero. One set the counter to 2, another did - not reset the counter at all. - - o Some implementations could only handle a single pair of traffic - selectors or would only process the first pair in the proposal. - - o Some implementations responded to a delete request by sending an - empty INFORMATIONAL response and then initiated their own - INFORMATIONAL exchange with the pair of SAs to delete. - - o Although this did not happen at the bakeoff, from the discussion - there, it is clear that some people had not implemented message - window sizes correctly. Some implementations might have sent - - - - - -Eronen & Hoffman Informational [Page 50] - -RFC 4718 IKEv2 Clarifications October 2006 - - - messages that did not fit into the responder's message windows, - and some implementations may not have torn down an SA if they did - not ever receive a message that they know they should have. - -9. Security Considerations - - This document does not introduce any new security considerations to - IKEv2. If anything, clarifying complex areas of the specification - can reduce the likelihood of implementation problems that may have - security implications. - -10. Acknowledgments - - This document is mainly based on conversations on the IPsec WG - mailing list. The authors would especially like to thank Bernard - Aboba, Jari Arkko, Vijay Devarapalli, William Dixon, Francis Dupont, - Alfred Hoenes, Mika Joutsenvirta, Charlie Kaufman, Stephen Kent, Tero - Kivinen, Yoav Nir, Michael Richardson, and Joel Snyder for their - contributions. - - In addition, the authors would like to thank all the participants of - the first public IKEv2 bakeoff, held in Santa Clara in February 2005, - for their questions and proposed clarifications. - -11. References - -11.1. Normative References - - [IKEv2] Kaufman, C., Ed., "Internet Key Exchange (IKEv2) - Protocol", RFC 4306, December 2005. - - [IKEv2ALG] Schiller, J., "Cryptographic Algorithms for Use in the - Internet Key Exchange Version 2 (IKEv2)", RFC 4307, - December 2005. - - [PKCS1v20] Kaliski, B. and J. Staddon, "PKCS #1: RSA Cryptography - Specifications Version 2.0", RFC 2437, October 1998. - - [PKCS1v21] Jonsson, J. and B. Kaliski, "Public-Key Cryptography - Standards (PKCS) #1: RSA Cryptography Specifications - Version 2.1", RFC 3447, February 2003. - - [RFC2401] Kent, S. and R. Atkinson, "Security Architecture for - the Internet Protocol", RFC 2401, November 1998. - - [RFC4301] Kent, S. and K. Seo, "Security Architecture for the - Internet Protocol", RFC 4301, December 2005. - - - - -Eronen & Hoffman Informational [Page 51] - -RFC 4718 IKEv2 Clarifications October 2006 - - -11.2. Informative References - - [Aura05] Aura, T., Roe, M., and A. Mohammed, "Experiences with - Host-to-Host IPsec", 13th International Workshop on - Security Protocols, Cambridge, UK, April 2005. - - [EAP] Aboba, B., Blunk, L., Vollbrecht, J., Carlson, J., and - H. Levkowetz, "Extensible Authentication Protocol - (EAP)", RFC 3748, June 2004. - - [HashUse] Hoffman, P., "Use of Hash Algorithms in IKE and IPsec", - Work in Progress, July 2006. - - [IPCPSubnet] Cisco Systems, Inc., "IPCP Subnet Mask Support - Enhancements", http://www.cisco.com/univercd/cc/td/ - doc/product/software/ios121/121newft/121limit/121dc/ - 121dc3/ipcp_msk.htm, January 2003. - - [IPv6Addr] Hinden, R. and S. Deering, "IP Version 6 Addressing - Architecture", RFC 4291, February 2006. - - [MIPv6] Johnson, D., Perkins, C., and J. Arkko, "Mobility - Support in IPv6", RFC 3775, June 2004. - - [MLDv2] Vida, R. and L. Costa, "Multicast Listener Discovery - Version 2 (MLDv2) for IPv6", RFC 3810, June 2004. - - [NAI] Aboba, B., Beadles, M., Arkko, J., and P. Eronen, "The - Network Access Identifier", RFC 4282, December 2005. - - [PKI4IPsec] Korver, B., "Internet PKI Profile of IKEv1/ISAKMP, - IKEv2, and PKIX", Work in Progress, April 2006. - - [RADEAP] Aboba, B. and P. Calhoun, "RADIUS (Remote - Authentication Dial In User Service) Support For - Extensible Authentication Protocol (EAP)", RFC 3579, - September 2003. - - [RADIUS] Rigney, C., Willens, S., Rubens, A., and W. Simpson, - "Remote Authentication Dial In User Service (RADIUS)", - RFC 2865, June 2000. - - [RADIUS6] Aboba, B., Zorn, G., and D. Mitton, "RADIUS and IPv6", - RFC 3162, August 2001. - - [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", RFC 2119, March 1997. - - - - -Eronen & Hoffman Informational [Page 52] - -RFC 4718 IKEv2 Clarifications October 2006 - - - [RFC2451] Pereira, R. and R. Adams, "The ESP CBC-Mode Cipher - Algorithms", RFC 2451, November 1998. - - [RFC2822] Resnick, P., "Internet Message Format", RFC 2822, - April 2001. - - [RFC3664] Hoffman, P., "The AES-XCBC-PRF-128 Algorithm for the - Internet Key Exchange Protocol (IKE)", RFC 3664, - January 2004. - - [RFC3948] Huttunen, A., Swander, B., Volpe, V., DiBurro, L., and - M. Stenberg, "UDP Encapsulation of IPsec ESP Packets", - RFC 3948, January 2005. - - [RFC4434] Hoffman, P., "The AES-XCBC-PRF-128 Algorithm for the - Internet Key Exchange Protocol (IKE)", RFC 4434, - February 2006. - - [RFC822] Crocker, D., "Standard for the format of ARPA Internet - text messages", RFC 822, August 1982. - - [ReAuth] Nir, Y., "Repeated Authentication in Internet Key - Exchange (IKEv2) Protocol", RFC 4478, April 2006. - - [SCVP] Freeman, T., Housley, R., Malpani, A., Cooper, D., and - T. Polk, "Simple Certificate Validation Protocol - (SCVP)", Work in Progress, June 2006. - - - - - - - - - - - - - - - - - - - - - - - - -Eronen & Hoffman Informational [Page 53] - -RFC 4718 IKEv2 Clarifications October 2006 - - -Appendix A. Exchanges and Payloads - - This appendix contains a short summary of the IKEv2 exchanges, and - what payloads can appear in which message. This appendix is purely - informative; if it disagrees with the body of this document or the - IKEv2 specification, the other text is considered correct. - - Vendor-ID (V) payloads may be included in any place in any message. - This sequence shows what are, in our opinion, the most logical places - for them. - - The specification does not say which messages can contain - N(SET_WINDOW_SIZE). It can possibly be included in any message, but - it is not yet shown below. - -A.1. IKE_SA_INIT Exchange - - request --> [N(COOKIE)], - SA, KE, Ni, - [N(NAT_DETECTION_SOURCE_IP)+, - N(NAT_DETECTION_DESTINATION_IP)], - [V+] - - normal response <-- SA, KE, Nr, - (no cookie) [N(NAT_DETECTION_SOURCE_IP), - N(NAT_DETECTION_DESTINATION_IP)], - [[N(HTTP_CERT_LOOKUP_SUPPORTED)], CERTREQ+], - [V+] - -A.2. IKE_AUTH Exchange without EAP - - request --> IDi, [CERT+], - [N(INITIAL_CONTACT)], - [[N(HTTP_CERT_LOOKUP_SUPPORTED)], CERTREQ+], - [IDr], - AUTH, - [CP(CFG_REQUEST)], - [N(IPCOMP_SUPPORTED)+], - [N(USE_TRANSPORT_MODE)], - [N(ESP_TFC_PADDING_NOT_SUPPORTED)], - [N(NON_FIRST_FRAGMENTS_ALSO)], - SA, TSi, TSr, - [V+] - - - - - - - - -Eronen & Hoffman Informational [Page 54] - -RFC 4718 IKEv2 Clarifications October 2006 - - - response <-- IDr, [CERT+], - AUTH, - [CP(CFG_REPLY)], - [N(IPCOMP_SUPPORTED)], - [N(USE_TRANSPORT_MODE)], - [N(ESP_TFC_PADDING_NOT_SUPPORTED)], - [N(NON_FIRST_FRAGMENTS_ALSO)], - SA, TSi, TSr, - [N(ADDITIONAL_TS_POSSIBLE)], - [V+] - -A.3. IKE_AUTH Exchange with EAP - - first request --> IDi, - [N(INITIAL_CONTACT)], - [[N(HTTP_CERT_LOOKUP_SUPPORTED)], CERTREQ+], - [IDr], - [CP(CFG_REQUEST)], - [N(IPCOMP_SUPPORTED)+], - [N(USE_TRANSPORT_MODE)], - [N(ESP_TFC_PADDING_NOT_SUPPORTED)], - [N(NON_FIRST_FRAGMENTS_ALSO)], - SA, TSi, TSr, - [V+] - - first response <-- IDr, [CERT+], AUTH, - EAP, - [V+] - - / --> EAP - repeat 1..N times | - \ <-- EAP - - last request --> AUTH - - last response <-- AUTH, - [CP(CFG_REPLY)], - [N(IPCOMP_SUPPORTED)], - [N(USE_TRANSPORT_MODE)], - [N(ESP_TFC_PADDING_NOT_SUPPORTED)], - [N(NON_FIRST_FRAGMENTS_ALSO)], - SA, TSi, TSr, - [N(ADDITIONAL_TS_POSSIBLE)], - [V+] - - - - - - - -Eronen & Hoffman Informational [Page 55] - -RFC 4718 IKEv2 Clarifications October 2006 - - -A.4. CREATE_CHILD_SA Exchange for Creating/Rekeying CHILD_SAs - - request --> [N(REKEY_SA)], - [N(IPCOMP_SUPPORTED)+], - [N(USE_TRANSPORT_MODE)], - [N(ESP_TFC_PADDING_NOT_SUPPORTED)], - [N(NON_FIRST_FRAGMENTS_ALSO)], - SA, Ni, [KEi], TSi, TSr - - response <-- [N(IPCOMP_SUPPORTED)], - [N(USE_TRANSPORT_MODE)], - [N(ESP_TFC_PADDING_NOT_SUPPORTED)], - [N(NON_FIRST_FRAGMENTS_ALSO)], - SA, Nr, [KEr], TSi, TSr, - [N(ADDITIONAL_TS_POSSIBLE)] - -A.5. CREATE_CHILD_SA Exchange for Rekeying the IKE_SA - - request --> SA, Ni, [KEi] - - response <-- SA, Nr, [KEr] - -A.6. INFORMATIONAL Exchange - - request --> [N+], - [D+], - [CP(CFG_REQUEST)] - - response <-- [N+], - [D+], - [CP(CFG_REPLY)] - - - - - - - - - - - - - - - - - - - - -Eronen & Hoffman Informational [Page 56] - -RFC 4718 IKEv2 Clarifications October 2006 - - -Authors' Addresses - - Pasi Eronen - Nokia Research Center - P.O. Box 407 - FIN-00045 Nokia Group - Finland - - EMail: pasi.eronen@nokia.com - - - Paul Hoffman - VPN Consortium - 127 Segre Place - Santa Cruz, CA 95060 - USA - - EMail: paul.hoffman@vpnc.org - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Eronen & Hoffman Informational [Page 57] - -RFC 4718 IKEv2 Clarifications October 2006 - - -Full Copyright Statement - - Copyright (C) The Internet Society (2006). - - This document is subject to the rights, licenses and restrictions - contained in BCP 78, and except as set forth therein, the authors - retain all their rights. - - This document and the information contained herein are provided on an - "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS - OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET - ENGINEERING TASK FORCE DISCLAIM 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. - -Intellectual Property - - The IETF takes no position regarding the validity or scope of any - Intellectual Property Rights or other rights that might be claimed to - pertain to the implementation or use of the technology described in - this document or the extent to which any license under such rights - might or might not be available; nor does it represent that it has - made any independent effort to identify any such rights. Information - on the procedures with respect to rights in RFC documents can be - found in BCP 78 and BCP 79. - - Copies of IPR disclosures made to the IETF Secretariat and any - assurances of licenses to be made available, or the result of an - attempt made to obtain a general license or permission for the use of - such proprietary rights by implementers or users of this - specification can be obtained from the IETF on-line IPR repository at - http://www.ietf.org/ipr. - - The IETF invites any interested party to bring to its attention any - copyrights, patents or patent applications, or other proprietary - rights that may cover technology that may be required to implement - this standard. Please address the information to the IETF at - ietf-ipr@ietf.org. - -Acknowledgement - - Funding for the RFC Editor function is provided by the IETF - Administrative Support Activity (IASA). - - - - - - - -Eronen & Hoffman Informational [Page 58] - diff --git a/src/charon/doc/standards/rfc4739.txt b/src/charon/doc/standards/rfc4739.txt deleted file mode 100644 index db5cf6acf..000000000 --- a/src/charon/doc/standards/rfc4739.txt +++ /dev/null @@ -1,619 +0,0 @@ - - - - - - -Network Working Group P. Eronen -Request for Comments: 4739 Nokia -Category: Experimental J. Korhonen - TeliaSonera - November 2006 - - - Multiple Authentication Exchanges - in the Internet Key Exchange (IKEv2) Protocol - -Status of This Memo - - This memo defines an Experimental Protocol for the Internet - community. It does not specify an Internet standard of any kind. - Discussion and suggestions for improvement are requested. - Distribution of this memo is unlimited. - -Copyright Notice - - Copyright (C) The IETF Trust (2006). - -Abstract - - The Internet Key Exchange (IKEv2) protocol supports several - mechanisms for authenticating the parties, including signatures with - public-key certificates, shared secrets, and Extensible - Authentication Protocol (EAP) methods. Currently, each endpoint uses - only one of these mechanisms to authenticate itself. This document - specifies an extension to IKEv2 that allows the use of multiple - authentication exchanges, using either different mechanisms or the - same mechanism. This extension allows, for instance, performing - certificate-based authentication of the client host followed by an - EAP authentication of the user. When backend authentication servers - are used, they can belong to different administrative domains, such - as the network access provider and the service provider. - - - - - - - - - - - - - - - - -Eronen & Korhonen Experimental [Page 1] - -RFC 4739 Multiple Auth. Exchanges in IKEv2 November 2006 - - -Table of Contents - - 1. Introduction ....................................................3 - 1.1. Usage Scenarios ............................................4 - 1.2. Terminology ................................................5 - 2. Solution ........................................................5 - 2.1. Solution Overview ..........................................5 - 2.2. Example 1: Multiple EAP Authentications ....................6 - 2.3. Example 2: Mixed EAP and Certificate Authentications .......7 - 2.4. Example 3: Multiple Initiator Certificates .................8 - 2.5. Example 4: Multiple Responder Certificates .................8 - 3. Payload Formats .................................................9 - 3.1. MULTIPLE_AUTH_SUPPORTED Notify Payload .....................9 - 3.2. ANOTHER_AUTH_FOLLOWS Notify Payload ........................9 - 4. IANA Considerations .............................................9 - 5. Security Considerations .........................................9 - 6. Acknowledgments ................................................10 - 7. References .....................................................10 - 7.1. Normative References ......................................10 - 7.2. Informative References ....................................10 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Eronen & Korhonen Experimental [Page 2] - -RFC 4739 Multiple Auth. Exchanges in IKEv2 November 2006 - - -1. Introduction - - IKEv2 [IKEv2] supports several mechanisms for parties involved in the - IKE_SA (IKE security association). These include signatures with - public-key certificates, shared secrets, and Extensible - Authentication Protocol (EAP) methods. - - Currently, each endpoint uses only one of these mechanisms to - authenticate itself. However, there are scenarios where making the - authorization decision in IKEv2 (whether to allow access or not) - requires using several of these methods. - - For instance, it may be necessary to authenticate both the host - (machine) requesting access, and the user currently using the host. - These two authentications would use two separate sets of credentials - (such as certificates and associated private keys) and might even use - different authentication mechanisms. - - To take another example, when an operator is hosting a Virtual - Private Network (VPN) gateway service for a third party, it may be - necessary to authenticate the client to both the operator (for - billing purposes) and the third party's Authentication, - Authorization, and Accounting (AAA) server (for authorizing access to - the third party's internal network). - - This document specifies an extension to IKEv2 that allows the use of - multiple authentication exchanges, using either different mechanisms - or the same mechanism. This extension allows, for instance, - performing certificate-based authentication of the client host - followed by an EAP authentication of the user. - - Each authentication exchange requiring communication with backend AAA - servers may be directed to different backend AAA servers, located - even in different administrative domains. However, details of the - communication between the IKEv2 gateway and the backend - authentication servers are beyond the scope of this document. In - particular, this document does not specify any changes to existing - AAA protocols, and it does not require the use of any particular AAA - protocol. - - In case of several EAP authentications, it is important to notice - that they are not a "sequence" (as described in Section 2.1 of - [EAP]), but separate independent EAP conversations, which are usually - also terminated in different EAP servers. Multiple authentication - methods within a single EAP conversation are still prohibited as - described in Section 2.1 of [EAP]. Using multiple independent EAP - conversations is similar to the separate Network Access Provider - (NAP) and Internet Service Provider (ISP) authentication exchanges - - - -Eronen & Korhonen Experimental [Page 3] - -RFC 4739 Multiple Auth. Exchanges in IKEv2 November 2006 - - - planned for [PANA]. The discovery of the appropriate EAP server for - each EAP authentication conversation is based on AAA routing. - -1.1. Usage Scenarios - - Figure 1 shows an example architecture of an operator-hosted VPN - scenario that could benefit from a two-phase authentication within - the IKEv2 exchange. First, the client authenticates towards the - Network Access Provider (NAP) and gets access to the NAP-hosted VPN - gateway. The first-phase authentication involves the backend AAA - server of the NAP. After the first authentication, the client - initiates the second authentication round that also involves the - Third Party's backend AAA server. If both authentications succeed, - the required IPsec tunnels are set up and the client can access - protected networks behind the Third Party. - - - Client *Network Access Provider* - +---------+ +---------+ +-----+ - | | | NAP's | | NAP | - |Protected| IPsec SAs | Tunnel | AAA Protocol | AAA | - |Endpoint |<------------------>|Endpoint |<------------>|Serv/| - | | | | |Proxy| - +---------+ +---------+ +-----+ - ^ ^ - IPsec or / AAA | - Leased Line / Protocol | - / | - v | - +---------+ *Third Party* v - |3rd Party| +-----+ - Protected | Tunnel | | 3rd | - Subnet <----|Endpoint | |Party| - | | | AAA | - +---------+ +-----+ - - Figure 1: Two-phase authentication used to gain access to - the Third Party network via Network Access Provider. AAA - traffic goes through NAP's AAA server. - - The NAP's AAA server can be used to proxy the AAA traffic to the - Third Party's backend AAA server. Alternatively, the AAA traffic - from the NAP's tunnel endpoint could go directly to the Third Party's - backend AAA servers. However, this is more or less an AAA routing - issue. - - - - - - -Eronen & Korhonen Experimental [Page 4] - -RFC 4739 Multiple Auth. Exchanges in IKEv2 November 2006 - - -1.2. Terminology - - 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 [KEYWORDS]. - - The terms and abbreviations "authenticator", "backend authentication - server", "EAP server", and "peer" in this document are to be - interpreted as described in [EAP]. - - When messages containing IKEv2 payloads are described, optional - payloads are shown in brackets (for instance, "[FOO]"), and a plus - sign indicates that a payload can be repeated one or more times (for - instance, "FOO+"). - -2. Solution - -2.1. Solution Overview - - The peers announce support for this IKEv2 extension by including a - MULTIPLE_AUTH_SUPPORTED notification in the IKE_SA_INIT response - (responder) and the first IKE_AUTH request (initiator). - - If both peers support this extension, either of them can announce - that it wishes to have a second authentication by including an - ANOTHER_AUTH_FOLLOWS notification in any IKE_AUTH message that - contains an AUTH payload. This indicates that the peer sending the - ANOTHER_AUTH_FOLLOWS wishes to authenticate another set of - credentials to the other peer. The next IKE_AUTH message sent by - this peer will contain a second identity payload (IDi or IDr) and - starts another authentication exchange. The IKE_AUTH phase is - considered successful only if all the individual authentication - exchanges complete successfully. - - It is assumed that both peers know what credentials they want to - present; there is no negotiation about, for instance, what type of - authentication is to be done. As in IKEv2, EAP-based authentication - is always requested by the initiator (by omitting the AUTH payload). - - The AUTH payloads are calculated as specified in [IKEv2] Sections - 2.15 and 2.16, where IDi' refers to the latest IDi payload sent by - the initiator, and IDr' refers to the latest IDr payload sent by the - responder. If EAP methods that do not generate shared keys are used, - it is possible that several AUTH payloads with identical contents are - sent. When such EAP methods are used, the purpose of the AUTH - payload is simply to delimit the authentication exchanges, and ensure - that the IKE_SA_INIT request/response messages were not modified. - - - - -Eronen & Korhonen Experimental [Page 5] - -RFC 4739 Multiple Auth. Exchanges in IKEv2 November 2006 - - -2.2. Example 1: Multiple EAP Authentications - - This example shows certificate-based authentication of the responder - followed by an EAP authentication exchange (messages 1-10). When the - first EAP exchange is ending (the initiator is sending its AUTH - payload), the initiator announces that it wishes to have a second - authentication exchange by including an ANOTHER_AUTH_FOLLOWS - notification (message 9). - - After this, a second authentication exchange begins. The initiator - sends a new IDi payload but no AUTH payload (message 11), indicating - that EAP will be used. After that, another EAP authentication - exchange follows (messages 12-18). - - Initiator Responder - ----------- ----------- - 1. HDR, SA, KE, Ni --> - <-- 2. HDR, SA, KE, Nr, [CERTREQ], - N(MULTIPLE_AUTH_SUPPORTED) - 3. HDR, SK { IDi, [CERTREQ+], [IDr], - SA, TSi, TSr, N(MULTIPLE_AUTH_SUPPORTED) } --> - <-- 4. HDR, SK { IDr, [CERT+], AUTH, - EAP(Request) } - 5. HDR, SK { EAP(Response) } --> - <-- 6. HDR, SK { EAP(Request) } - 7. HDR, SK { EAP(Response) } --> - <-- 8. HDR, SK { EAP(Success) } - 9. HDR, SK { AUTH, - N(ANOTHER_AUTH_FOLLOWS) } --> - <-- 10. HDR, SK { AUTH } - 11. HDR, SK { IDi } --> - <-- 12. HDR, SK { EAP(Request) } - 13. HDR, SK { EAP(Response) } --> - <-- 14. HDR, SK { EAP(Request) } - 15. HDR, SK { EAP(Response) } --> - <-- 16. HDR, SK { EAP(Success) } - 17. HDR, SK { AUTH } --> - <-- 18. HDR, SK { AUTH, SA, TSi, TSr } - - Example 1: Certificate-based authentication of the - responder, followed by two EAP authentication exchanges. - - - - - - - - - - -Eronen & Korhonen Experimental [Page 6] - -RFC 4739 Multiple Auth. Exchanges in IKEv2 November 2006 - - -2.3. Example 2: Mixed EAP and Certificate Authentications - - Another example is shown below: here both the initiator and the - responder are first authenticated using certificates (or shared - secrets); this is followed by an EAP authentication exchange. - - Initiator Responder - ----------- ----------- - 1. HDR, SA, KE, Ni --> - <-- 2. HDR, SA, KE, Nr, [CERTREQ], - N(MULTIPLE_AUTH_SUPPORTED) - 3. HDR, SK { IDi, [CERT+], [CERTREQ+], [IDr], AUTH, - SA, TSi, TSr, N(MULTIPLE_AUTH_SUPPORTED), - N(ANOTHER_AUTH_FOLLOWS) } --> - <-- 4. HDR, SK { IDr, [CERT+], AUTH } - 5. HDR, SK { IDi } --> - <-- 6. HDR, SK { EAP(Request) } - 7. HDR, SK { EAP(Response) } --> - <-- 8. HDR, SK { EAP(Request) } - 9. HDR, SK { EAP(Response) } --> - <-- 10. HDR, SK { EAP(Success) } - 11. HDR, SK { AUTH } --> - <-- 12. HDR, SK { AUTH, SA, TSi, TSr } - - Example 2: Certificate-based (or shared-secret-based) - authentication of the initiator and the responder, - followed by an EAP authentication exchange. - - - - - - - - - - - - - - - - - - - - - - - - -Eronen & Korhonen Experimental [Page 7] - -RFC 4739 Multiple Auth. Exchanges in IKEv2 November 2006 - - -2.4. Example 3: Multiple Initiator Certificates - - This example shows yet another possibility: the initiator has two - different certificates (and associated private keys), and - authenticates both of them to the responder. - - Initiator Responder - ----------- ----------- - 1. HDR, SA, KE, Ni --> - <-- 2. HDR, SA, KE, Nr, [CERTREQ], - N(MULTIPLE_AUTH_SUPPORTED) - 3. HDR, SK { IDi, [CERT+], [CERTREQ+], [IDr], AUTH, - SA, TSi, TSr, N(MULTIPLE_AUTH_SUPPORTED), - N(ANOTHER_AUTH_FOLLOWS) } --> - <-- 4. HDR, SK { IDr, [CERT+], AUTH } - 5. HDR, SK { IDi, [CERT+], AUTH } --> - <-- 6. HDR, SK { SA, TSi, TSr } - - Example 3: Two certificate-based authentications of the - initiator, and one certificate-based authentication - of the responder. - -2.5. Example 4: Multiple Responder Certificates - - This example shows yet another possibility: the responder has two - different certificates (and associated private keys), and - authenticates both of them to the initiator. - - Initiator Responder - ----------- ----------- - 1. HDR, SA, KE, Ni --> - <-- 2. HDR, SA, KE, Nr, [CERTREQ], - N(MULTIPLE_AUTH_SUPPORTED) - 3. HDR, SK { IDi, [CERT+], [CERTREQ+], [IDr], AUTH, - SA, TSi, TSr, N(MULTIPLE_AUTH_SUPPORTED) } --> - <-- 4. HDR, SK { IDr, [CERT+], AUTH, - N(ANOTHER_AUTH_FOLLOWS) } - 5. HDR, SK { } --> - <-- 6. HDR, SK { IDr, [CERT+], AUTH, - SA, TSi, TSr } - - Example 4: Two certificate-based authentications of the - responder, and one certificate-based authentication - of the initiator. - - - - - - - -Eronen & Korhonen Experimental [Page 8] - -RFC 4739 Multiple Auth. Exchanges in IKEv2 November 2006 - - -3. Payload Formats - -3.1. MULTIPLE_AUTH_SUPPORTED Notify Payload - - The MULTIPLE_AUTH_SUPPORTED notification is included in the - IKE_SA_INIT response or the first IKE_AUTH request to indicate that - the peer supports this specification. The Notify Message Type is - MULTIPLE_AUTH_SUPPORTED (16404). The Protocol ID and SPI Size fields - MUST be set to zero, and there is no data associated with this Notify - type. - -3.2. ANOTHER_AUTH_FOLLOWS Notify Payload - - The ANOTHER_AUTH_FOLLOWS notification payload is included in an - IKE_AUTH message containing an AUTH payload to indicate that the peer - wants to continue with another authentication exchange. The Notify - Message Type is ANOTHER_AUTH_FOLLOWS (16405). The Protocol ID and - SPI Size fields MUST be set to zero, and there is no data associated - with this Notify type. - -4. IANA Considerations - - This document defines two new IKEv2 notifications, - MULTIPLE_AUTH_SUPPORTED and ANOTHER_AUTH_FOLLOWS, whose values are - allocated from the "IKEv2 Notify Message Types" namespace defined in - [IKEv2]. - - This document does not define any new namespaces to be managed by - IANA. - -5. Security Considerations - - Security considerations for IKEv2 are discussed in [IKEv2]. The - reader is encouraged to pay special attention to considerations - relating to the use of EAP methods that do not generate shared keys. - However, the use of multiple authentication exchanges results in at - least one new security consideration. - - In normal IKEv2, the responder authenticates the initiator before - revealing its identity (except when EAP is used). When multiple - authentication exchanges are used to authenticate the initiator, the - responder has to reveal its identity before all of the initiator - authentication exchanges have been completed. - - - - - - - - -Eronen & Korhonen Experimental [Page 9] - -RFC 4739 Multiple Auth. Exchanges in IKEv2 November 2006 - - -6. Acknowledgments - - The authors would like to thank Bernard Aboba, Jari Arkko, Spencer - Dawkins, Lakshminath Dondeti, Henry Haverinen, Russ Housley, Mika - Joutsenvirta, Charlie Kaufman, Tero Kivinen, Yoav Nir, Magnus - Nystrom, Mohan Parthasarathy, and Juha Savolainen for their valuable - comments. - -7. References - -7.1. Normative References - - [IKEv2] Kaufman, C., "Internet Key Exchange (IKEv2) Protocol", - RFC 4306, December 2005. - - [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", RFC 2119, March 1997. - -7.2. Informative References - - [EAP] Aboba, B., Blunk, L., Vollbrecht, J., Carlson, J., and H. - Levkowetz, "Extensible Authentication Protocol (EAP)", - RFC 3748, June 2004. - - [PANA] Yegin, A., Ohba, Y., Penno, R., Tsirtsis, G., and C. - Wang, "Protocol for Carrying Authentication for Network - Access (PANA) Requirements", RFC 4058, May 2005. - -Authors' Addresses - - Pasi Eronen - Nokia Research Center - P.O. Box 407 - FIN-00045 Nokia Group - Finland - - EMail: pasi.eronen@nokia.com - - - Jouni Korhonen - TeliaSonera - P.O. Box 970 - FIN-00051 Sonera - Finland - - EMail: jouni.korhonen@teliasonera.com - - - - - -Eronen & Korhonen Experimental [Page 10] - -RFC 4739 Multiple Auth. Exchanges in IKEv2 November 2006 - - -Full Copyright Statement - - Copyright (C) The IETF Trust (2006). - - This document is subject to the rights, licenses and restrictions - contained in BCP 78, and except as set forth therein, the authors - retain all their rights. - - This document and the information contained herein are provided on an - "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS - OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST, - AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM 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. - -Intellectual Property - - The IETF takes no position regarding the validity or scope of any - Intellectual Property Rights or other rights that might be claimed to - pertain to the implementation or use of the technology described in - this document or the extent to which any license under such rights - might or might not be available; nor does it represent that it has - made any independent effort to identify any such rights. Information - on the procedures with respect to rights in RFC documents can be - found in BCP 78 and BCP 79. - - Copies of IPR disclosures made to the IETF Secretariat and any - assurances of licenses to be made available, or the result of an - attempt made to obtain a general license or permission for the use of - such proprietary rights by implementers or users of this - specification can be obtained from the IETF on-line IPR repository at - http://www.ietf.org/ipr. - - The IETF invites any interested party to bring to its attention any - copyrights, patents or patent applications, or other proprietary - rights that may cover technology that may be required to implement - this standard. Please address the information to the IETF at - ietf-ipr@ietf.org. - -Acknowledgement - - Funding for the RFC Editor function is currently provided by the - Internet Society. - - - - - - -Eronen & Korhonen Experimental [Page 11] - diff --git a/src/charon/threads/kernel_interface.c b/src/charon/kernel/kernel_interface.c index 4a70d2ecf..e9cddccb4 100644 --- a/src/charon/threads/kernel_interface.c +++ b/src/charon/kernel/kernel_interface.c @@ -45,9 +45,9 @@ #include <daemon.h> #include <utils/linked_list.h> -#include <queues/jobs/delete_child_sa_job.h> -#include <queues/jobs/rekey_child_sa_job.h> -#include <queues/jobs/acquire_job.h> +#include <processing/jobs/delete_child_sa_job.h> +#include <processing/jobs/rekey_child_sa_job.h> +#include <processing/jobs/acquire_job.h> /** kernel level protocol identifiers */ #define KERNEL_ESP 50 diff --git a/src/charon/threads/kernel_interface.h b/src/charon/kernel/kernel_interface.h index 34b06f594..34b06f594 100644 --- a/src/charon/threads/kernel_interface.h +++ b/src/charon/kernel/kernel_interface.h diff --git a/src/charon/threads/receiver.c b/src/charon/network/receiver.c index 7195c162d..640339cc9 100644 --- a/src/charon/threads/receiver.c +++ b/src/charon/network/receiver.c @@ -29,9 +29,9 @@ #include <daemon.h> #include <network/socket.h> #include <network/packet.h> -#include <queues/job_queue.h> -#include <queues/jobs/job.h> -#include <queues/jobs/process_message_job.h> +#include <processing/job_queue.h> +#include <processing/jobs/job.h> +#include <processing/jobs/process_message_job.h> /** length of the full cookie, including time (u_int32_t + SHA1()) */ #define COOKIE_LENGTH 24 diff --git a/src/charon/threads/receiver.h b/src/charon/network/receiver.h index 68d9136c0..68d9136c0 100644 --- a/src/charon/threads/receiver.h +++ b/src/charon/network/receiver.h diff --git a/src/charon/threads/sender.c b/src/charon/network/sender.c index c1cd0a68c..c1cd0a68c 100644 --- a/src/charon/threads/sender.c +++ b/src/charon/network/sender.c diff --git a/src/charon/threads/sender.h b/src/charon/network/sender.h index 4f42f6f9e..4f42f6f9e 100644 --- a/src/charon/threads/sender.h +++ b/src/charon/network/sender.h diff --git a/src/charon/queues/event_queue.c b/src/charon/processing/event_queue.c index 40bcb1ed8..40bcb1ed8 100644 --- a/src/charon/queues/event_queue.c +++ b/src/charon/processing/event_queue.c diff --git a/src/charon/queues/event_queue.h b/src/charon/processing/event_queue.h index cd275123b..3258b254f 100644 --- a/src/charon/queues/event_queue.h +++ b/src/charon/processing/event_queue.h @@ -29,7 +29,7 @@ typedef struct event_queue_t event_queue_t; #include <sys/time.h> #include <library.h> -#include <queues/jobs/job.h> +#include <processing/jobs/job.h> /** * @brief Event-Queue used to store timed events. diff --git a/src/charon/queues/job_queue.c b/src/charon/processing/job_queue.c index 2310ca6ff..2310ca6ff 100644 --- a/src/charon/queues/job_queue.c +++ b/src/charon/processing/job_queue.c diff --git a/src/charon/queues/job_queue.h b/src/charon/processing/job_queue.h index c971ba514..26e1492d8 100644 --- a/src/charon/queues/job_queue.h +++ b/src/charon/processing/job_queue.h @@ -27,7 +27,7 @@ typedef struct job_queue_t job_queue_t; #include <library.h> -#include <queues/jobs/job.h> +#include <processing/jobs/job.h> /** * @brief The job queue stores jobs, which will be processed by the thread_pool_t. diff --git a/src/charon/queues/jobs/acquire_job.c b/src/charon/processing/jobs/acquire_job.c index b4ffb258d..b4ffb258d 100644 --- a/src/charon/queues/jobs/acquire_job.c +++ b/src/charon/processing/jobs/acquire_job.c diff --git a/src/charon/queues/jobs/acquire_job.h b/src/charon/processing/jobs/acquire_job.h index 54f1b9b5b..226966215 100644 --- a/src/charon/queues/jobs/acquire_job.h +++ b/src/charon/processing/jobs/acquire_job.h @@ -26,7 +26,7 @@ typedef struct acquire_job_t acquire_job_t; #include <library.h> -#include <queues/jobs/job.h> +#include <processing/jobs/job.h> /** * @brief Class representing an ACQUIRE Job. diff --git a/src/charon/queues/jobs/delete_child_sa_job.c b/src/charon/processing/jobs/delete_child_sa_job.c index f694696b0..f694696b0 100644 --- a/src/charon/queues/jobs/delete_child_sa_job.c +++ b/src/charon/processing/jobs/delete_child_sa_job.c diff --git a/src/charon/queues/jobs/delete_child_sa_job.h b/src/charon/processing/jobs/delete_child_sa_job.h index 9c2e4fa4d..0b90e008d 100644 --- a/src/charon/queues/jobs/delete_child_sa_job.h +++ b/src/charon/processing/jobs/delete_child_sa_job.h @@ -27,7 +27,7 @@ typedef struct delete_child_sa_job_t delete_child_sa_job_t; #include <library.h> #include <sa/ike_sa_id.h> -#include <queues/jobs/job.h> +#include <processing/jobs/job.h> #include <config/proposal.h> diff --git a/src/charon/queues/jobs/delete_ike_sa_job.c b/src/charon/processing/jobs/delete_ike_sa_job.c index 706155aa6..706155aa6 100644 --- a/src/charon/queues/jobs/delete_ike_sa_job.c +++ b/src/charon/processing/jobs/delete_ike_sa_job.c diff --git a/src/charon/queues/jobs/delete_ike_sa_job.h b/src/charon/processing/jobs/delete_ike_sa_job.h index 43701a354..11bb46e73 100644 --- a/src/charon/queues/jobs/delete_ike_sa_job.h +++ b/src/charon/processing/jobs/delete_ike_sa_job.h @@ -28,7 +28,7 @@ typedef struct delete_ike_sa_job_t delete_ike_sa_job_t; #include <library.h> #include <sa/ike_sa_id.h> -#include <queues/jobs/job.h> +#include <processing/jobs/job.h> /** diff --git a/src/charon/queues/jobs/initiate_job.c b/src/charon/processing/jobs/initiate_job.c index af50663d6..68ca17258 100644 --- a/src/charon/queues/jobs/initiate_job.c +++ b/src/charon/processing/jobs/initiate_job.c @@ -6,7 +6,7 @@ */ /* - * Copyright (C) 2005-2006 Martin Willi + * Copyright (C) 2005-2007 Martin Willi * Copyright (C) 2005 Jan Hutter * Hochschule fuer Technik Rapperswil * @@ -40,14 +40,14 @@ struct private_initiate_job_t { initiate_job_t public; /** - * associated connection to initiate + * associated peer config to use for IKE_SA setup */ - connection_t *connection; + peer_cfg_t *peer_cfg; /** - * associated policy to initiate + * child config to use for CHILD_SA */ - policy_t *policy; + child_cfg_t *child_cfg; }; /** @@ -64,14 +64,20 @@ static job_type_t get_type(private_initiate_job_t *this) static status_t execute(private_initiate_job_t *this) { ike_sa_t *ike_sa; + ike_cfg_t *ike_cfg = this->peer_cfg->get_ike_cfg(this->peer_cfg); ike_sa = charon->ike_sa_manager->checkout_by_peer(charon->ike_sa_manager, - this->connection->get_my_host(this->connection), - this->connection->get_other_host(this->connection), - this->policy->get_my_id(this->policy), - this->policy->get_other_id(this->policy)); + ike_cfg->get_my_host(ike_cfg), + ike_cfg->get_other_host(ike_cfg), + this->peer_cfg->get_my_id(this->peer_cfg), + this->peer_cfg->get_other_id(this->peer_cfg)); - if (ike_sa->initiate(ike_sa, this->connection, this->policy) != SUCCESS) + if (ike_sa->get_peer_cfg(ike_sa) == NULL) + { + ike_sa->set_peer_cfg(ike_sa, this->peer_cfg); + } + + if (ike_sa->initiate(ike_sa, this->child_cfg) != SUCCESS) { DBG1(DBG_JOB, "initiation failed, going to delete IKE_SA"); charon->ike_sa_manager->checkin_and_destroy(charon->ike_sa_manager, ike_sa); @@ -87,15 +93,15 @@ static status_t execute(private_initiate_job_t *this) */ static void destroy(private_initiate_job_t *this) { - this->connection->destroy(this->connection); - this->policy->destroy(this->policy); + this->peer_cfg->destroy(this->peer_cfg); + this->child_cfg->destroy(this->child_cfg); free(this); } /* * Described in header */ -initiate_job_t *initiate_job_create(connection_t *connection, policy_t *policy) +initiate_job_t *initiate_job_create(peer_cfg_t *peer_cfg, child_cfg_t *child_cfg) { private_initiate_job_t *this = malloc_thing(private_initiate_job_t); @@ -105,8 +111,8 @@ initiate_job_t *initiate_job_create(connection_t *connection, policy_t *policy) this->public.job_interface.destroy = (void (*) (job_t *)) destroy; /* private variables */ - this->connection = connection; - this->policy = policy; + this->peer_cfg = peer_cfg; + this->child_cfg = child_cfg; return &this->public; } diff --git a/src/charon/queues/jobs/initiate_job.h b/src/charon/processing/jobs/initiate_job.h index af1dd9ece..15b46a74c 100644 --- a/src/charon/queues/jobs/initiate_job.h +++ b/src/charon/processing/jobs/initiate_job.h @@ -5,7 +5,7 @@ */ /* - * Copyright (C) 2005-2006 Martin Willi + * Copyright (C) 2005-2007 Martin Willi * Copyright (C) 2005 Jan Hutter * Hochschule fuer Technik Rapperswil * @@ -20,15 +20,15 @@ * for more details. */ -#ifndef INITIATE_IKE_SA_JOB_H_ -#define INITIATE_IKE_SA_JOB_H_ +#ifndef INITIATE_JOB_H_ +#define INITIATE_JOB_H_ typedef struct initiate_job_t initiate_job_t; #include <library.h> -#include <queues/jobs/job.h> -#include <config/connections/connection.h> -#include <config/policies/policy.h> +#include <processing/jobs/job.h> +#include <config/peer_cfg.h> +#include <config/child_cfg.h> /** * @brief Class representing an INITIATE_IKE_SA Job. @@ -48,14 +48,14 @@ struct initiate_job_t { }; /** - * @brief Creates a job of type INITIATE_IKE_SA. + * @brief Creates a job of type INITIATE. * - * @param connection connection_t to initialize - * @param policy policy to set up + * @param peer_cfg peer configuration to use (if not yet established) + * @param child_cfg config to create a CHILD from * @return initiate_job_t object * * @ingroup jobs */ -initiate_job_t *initiate_job_create(connection_t *connection, policy_t *policy); +initiate_job_t *initiate_job_create(peer_cfg_t *peer_cfg, child_cfg_t *child_cfg); -#endif /*INITIATE_IKE_SA_JOB_H_*/ +#endif /*INITIATE_JOB_H_*/ diff --git a/src/charon/queues/jobs/job.c b/src/charon/processing/jobs/job.c index d32d1bc61..d32d1bc61 100644 --- a/src/charon/queues/jobs/job.c +++ b/src/charon/processing/jobs/job.c diff --git a/src/charon/queues/jobs/job.h b/src/charon/processing/jobs/job.h index 28632672d..28632672d 100644 --- a/src/charon/queues/jobs/job.h +++ b/src/charon/processing/jobs/job.h diff --git a/src/charon/queues/jobs/process_message_job.c b/src/charon/processing/jobs/process_message_job.c index ee7484bbd..ee7484bbd 100644 --- a/src/charon/queues/jobs/process_message_job.c +++ b/src/charon/processing/jobs/process_message_job.c diff --git a/src/charon/queues/jobs/process_message_job.h b/src/charon/processing/jobs/process_message_job.h index 2e60a298c..5bb18155a 100644 --- a/src/charon/queues/jobs/process_message_job.h +++ b/src/charon/processing/jobs/process_message_job.h @@ -28,7 +28,7 @@ typedef struct process_message_job_t process_message_job_t; #include <library.h> #include <encoding/message.h> -#include <queues/jobs/job.h> +#include <processing/jobs/job.h> /** * @brief Class representing an PROCESS_MESSAGE job. diff --git a/src/charon/queues/jobs/rekey_child_sa_job.c b/src/charon/processing/jobs/rekey_child_sa_job.c index 3422b614d..3422b614d 100644 --- a/src/charon/queues/jobs/rekey_child_sa_job.c +++ b/src/charon/processing/jobs/rekey_child_sa_job.c diff --git a/src/charon/queues/jobs/rekey_child_sa_job.h b/src/charon/processing/jobs/rekey_child_sa_job.h index 19e1b5d32..df86070bc 100644 --- a/src/charon/queues/jobs/rekey_child_sa_job.h +++ b/src/charon/processing/jobs/rekey_child_sa_job.h @@ -27,7 +27,7 @@ typedef struct rekey_child_sa_job_t rekey_child_sa_job_t; #include <library.h> #include <sa/ike_sa_id.h> -#include <queues/jobs/job.h> +#include <processing/jobs/job.h> #include <config/proposal.h> /** diff --git a/src/charon/queues/jobs/rekey_ike_sa_job.c b/src/charon/processing/jobs/rekey_ike_sa_job.c index 2539d997e..2539d997e 100644 --- a/src/charon/queues/jobs/rekey_ike_sa_job.c +++ b/src/charon/processing/jobs/rekey_ike_sa_job.c diff --git a/src/charon/queues/jobs/rekey_ike_sa_job.h b/src/charon/processing/jobs/rekey_ike_sa_job.h index f3e336fb3..4031b3813 100644 --- a/src/charon/queues/jobs/rekey_ike_sa_job.h +++ b/src/charon/processing/jobs/rekey_ike_sa_job.h @@ -27,7 +27,7 @@ typedef struct rekey_ike_sa_job_t rekey_ike_sa_job_t; #include <library.h> #include <sa/ike_sa_id.h> -#include <queues/jobs/job.h> +#include <processing/jobs/job.h> /** * @brief Class representing an REKEY_IKE_SA Job. diff --git a/src/charon/queues/jobs/retransmit_job.c b/src/charon/processing/jobs/retransmit_job.c index 5bfa20dfd..5bfa20dfd 100644 --- a/src/charon/queues/jobs/retransmit_job.c +++ b/src/charon/processing/jobs/retransmit_job.c diff --git a/src/charon/queues/jobs/retransmit_job.h b/src/charon/processing/jobs/retransmit_job.h index 19e29b909..93bb548e7 100644 --- a/src/charon/queues/jobs/retransmit_job.h +++ b/src/charon/processing/jobs/retransmit_job.h @@ -27,7 +27,7 @@ typedef struct retransmit_job_t retransmit_job_t; #include <library.h> -#include <queues/jobs/job.h> +#include <processing/jobs/job.h> #include <sa/ike_sa_id.h> /** diff --git a/src/charon/queues/jobs/route_job.c b/src/charon/processing/jobs/route_job.c index bb6281dcc..36afa5513 100644 --- a/src/charon/queues/jobs/route_job.c +++ b/src/charon/processing/jobs/route_job.c @@ -6,7 +6,7 @@ */ /* - * Copyright (C) 2005-2006 Martin Willi + * Copyright (C) 2005-2007 Martin Willi * Hochschule fuer Technik Rapperswil * * This program is free software; you can redistribute it and/or modify it @@ -39,14 +39,14 @@ struct private_route_job_t { route_job_t public; /** - * associated connection to route + * peer config for route */ - connection_t *connection; + peer_cfg_t *peer_cfg; /** - * associated policy to route + * child config to route */ - policy_t *policy; + child_cfg_t *child_cfg; /** * route or unroute? @@ -68,22 +68,29 @@ static job_type_t get_type(private_route_job_t *this) static status_t execute(private_route_job_t *this) { ike_sa_t *ike_sa; + ike_cfg_t *ike_cfg = this->peer_cfg->get_ike_cfg(this->peer_cfg); ike_sa = charon->ike_sa_manager->checkout_by_peer(charon->ike_sa_manager, - this->connection->get_my_host(this->connection), - this->connection->get_other_host(this->connection), - this->policy->get_my_id(this->policy), - this->policy->get_other_id(this->policy)); + ike_cfg->get_my_host(ike_cfg), + ike_cfg->get_other_host(ike_cfg), + this->peer_cfg->get_my_id(this->peer_cfg), + this->peer_cfg->get_other_id(this->peer_cfg)); + + if (ike_sa->get_peer_cfg(ike_sa) == NULL) + { + ike_sa->set_peer_cfg(ike_sa, this->peer_cfg); + } + if (this->route) { - if (ike_sa->route(ike_sa, this->connection, this->policy) != SUCCESS) + if (ike_sa->route(ike_sa, this->child_cfg) != SUCCESS) { DBG1(DBG_JOB, "routing failed"); } } else { - if (ike_sa->unroute(ike_sa, this->policy) == DESTROY_ME) + if (ike_sa->unroute(ike_sa, this->child_cfg) == DESTROY_ME) { DBG1(DBG_JOB, "removing IKE_SA, as last routed CHILD_SA unrouted"); charon->ike_sa_manager->checkin_and_destroy(charon->ike_sa_manager, ike_sa); @@ -99,15 +106,16 @@ static status_t execute(private_route_job_t *this) */ static void destroy(private_route_job_t *this) { - this->connection->destroy(this->connection); - this->policy->destroy(this->policy); + this->peer_cfg->destroy(this->peer_cfg); + this->child_cfg->destroy(this->child_cfg); free(this); } /* * Described in header */ -route_job_t *route_job_create(connection_t *connection, policy_t *policy, bool route) +route_job_t *route_job_create(peer_cfg_t *peer_cfg, child_cfg_t *child_cfg, + bool route) { private_route_job_t *this = malloc_thing(private_route_job_t); @@ -117,8 +125,8 @@ route_job_t *route_job_create(connection_t *connection, policy_t *policy, bool r this->public.job_interface.destroy = (void (*) (job_t *)) destroy; /* private variables */ - this->connection = connection; - this->policy = policy; + this->peer_cfg = peer_cfg; + this->child_cfg = child_cfg; this->route = route; return &this->public; diff --git a/src/charon/queues/jobs/route_job.h b/src/charon/processing/jobs/route_job.h index 2743a70ab..840fcc92a 100644 --- a/src/charon/queues/jobs/route_job.h +++ b/src/charon/processing/jobs/route_job.h @@ -5,7 +5,7 @@ */ /* - * Copyright (C) 2005-2006 Martin Willi + * Copyright (C) 2005-2007 Martin Willi * Hochschule fuer Technik Rapperswil * * This program is free software; you can redistribute it and/or modify it @@ -25,9 +25,8 @@ typedef struct route_job_t route_job_t; #include <library.h> -#include <queues/jobs/job.h> -#include <config/policies/policy.h> -#include <config/connections/connection.h> +#include <processing/jobs/job.h> +#include <config/peer_cfg.h> /** * @brief Class representing an ROUTE Job. @@ -47,13 +46,14 @@ struct route_job_t { /** * @brief Creates a job of type ROUTE. * - * @param connection connection used for routing - * @param policy policy to set up + * @param peer_cfg peer config to use for acquire + * @param child_cfg route to install * @param route TRUE to route, FALSE to unroute * @return route_job_t object * * @ingroup jobs */ -route_job_t *route_job_create(connection_t *connection, policy_t *policy, bool route); +route_job_t *route_job_create(peer_cfg_t *peer_cfg, child_cfg_t *child_cfg, + bool route); #endif /*ROUTE_JOB_H_*/ diff --git a/src/charon/queues/jobs/send_dpd_job.c b/src/charon/processing/jobs/send_dpd_job.c index 7294d78d5..7294d78d5 100644 --- a/src/charon/queues/jobs/send_dpd_job.c +++ b/src/charon/processing/jobs/send_dpd_job.c diff --git a/src/charon/queues/jobs/send_dpd_job.h b/src/charon/processing/jobs/send_dpd_job.h index f3900f9a2..26c9e2e81 100644 --- a/src/charon/queues/jobs/send_dpd_job.h +++ b/src/charon/processing/jobs/send_dpd_job.h @@ -25,8 +25,7 @@ typedef struct send_dpd_job_t send_dpd_job_t; #include <library.h> -#include <queues/jobs/job.h> -#include <config/connections/connection.h> +#include <processing/jobs/job.h> #include <sa/ike_sa_id.h> /** diff --git a/src/charon/queues/jobs/send_keepalive_job.c b/src/charon/processing/jobs/send_keepalive_job.c index 1c1cb288e..1c1cb288e 100644 --- a/src/charon/queues/jobs/send_keepalive_job.c +++ b/src/charon/processing/jobs/send_keepalive_job.c diff --git a/src/charon/queues/jobs/send_keepalive_job.h b/src/charon/processing/jobs/send_keepalive_job.h index c7d05be65..f7b38337e 100644 --- a/src/charon/queues/jobs/send_keepalive_job.h +++ b/src/charon/processing/jobs/send_keepalive_job.h @@ -25,8 +25,7 @@ typedef struct send_keepalive_job_t send_keepalive_job_t; #include <library.h> -#include <queues/jobs/job.h> -#include <config/connections/connection.h> +#include <processing/jobs/job.h> #include <sa/ike_sa_id.h> /** diff --git a/src/charon/threads/scheduler.c b/src/charon/processing/scheduler.c index 74091e3a3..156c1e240 100644 --- a/src/charon/threads/scheduler.c +++ b/src/charon/processing/scheduler.c @@ -27,7 +27,7 @@ #include "scheduler.h" #include <daemon.h> -#include <queues/job_queue.h> +#include <processing/job_queue.h> typedef struct private_scheduler_t private_scheduler_t; diff --git a/src/charon/threads/scheduler.h b/src/charon/processing/scheduler.h index daecce3c6..daecce3c6 100644 --- a/src/charon/threads/scheduler.h +++ b/src/charon/processing/scheduler.h diff --git a/src/charon/threads/thread_pool.c b/src/charon/processing/thread_pool.c index 052b5aab9..effa30a2d 100644 --- a/src/charon/threads/thread_pool.c +++ b/src/charon/processing/thread_pool.c @@ -29,7 +29,7 @@ #include "thread_pool.h" #include <daemon.h> -#include <queues/job_queue.h> +#include <processing/job_queue.h> typedef struct private_thread_pool_t private_thread_pool_t; diff --git a/src/charon/threads/thread_pool.h b/src/charon/processing/thread_pool.h index 8e1989bda..8e1989bda 100644 --- a/src/charon/threads/thread_pool.h +++ b/src/charon/processing/thread_pool.h diff --git a/src/charon/sa/authenticators/eap_authenticator.c b/src/charon/sa/authenticators/eap_authenticator.c index 6c8ca8d8f..08edd80e8 100644 --- a/src/charon/sa/authenticators/eap_authenticator.c +++ b/src/charon/sa/authenticators/eap_authenticator.c @@ -25,7 +25,7 @@ #include "eap_authenticator.h" #include <daemon.h> -#include <config/policies/policy.h> +#include <config/peer_cfg.h> #include <sa/authenticators/eap/eap_method.h> typedef struct private_eap_authenticator_t private_eap_authenticator_t; diff --git a/src/charon/sa/authenticators/psk_authenticator.c b/src/charon/sa/authenticators/psk_authenticator.c index 43aec0971..1831b2ded 100644 --- a/src/charon/sa/authenticators/psk_authenticator.c +++ b/src/charon/sa/authenticators/psk_authenticator.c @@ -25,7 +25,6 @@ #include "psk_authenticator.h" -#include <config/policies/policy.h> #include <daemon.h> /** diff --git a/src/charon/sa/authenticators/rsa_authenticator.c b/src/charon/sa/authenticators/rsa_authenticator.c index dfa01e332..42d861ef6 100644 --- a/src/charon/sa/authenticators/rsa_authenticator.c +++ b/src/charon/sa/authenticators/rsa_authenticator.c @@ -25,7 +25,6 @@ #include "rsa_authenticator.h" -#include <config/policies/policy.h> #include <daemon.h> diff --git a/src/charon/sa/child_sa.c b/src/charon/sa/child_sa.c index 19131389d..7ce8ca2fd 100644 --- a/src/charon/sa/child_sa.c +++ b/src/charon/sa/child_sa.c @@ -154,9 +154,9 @@ struct private_child_sa_t { host_t *virtual_ip; /** - * policy used to create this child + * config used to create this child */ - policy_t *policy; + child_cfg_t *config; }; /** @@ -164,7 +164,7 @@ struct private_child_sa_t { */ static char *get_name(private_child_sa_t *this) { - return this->policy->get_name(this->policy);; + return this->config->get_name(this->config); } /** @@ -204,11 +204,11 @@ static child_sa_state_t get_state(private_child_sa_t *this) } /** - * Implements child_sa_t.get_policy + * Implements child_sa_t.get_config */ -static policy_t* get_policy(private_child_sa_t *this) +static child_cfg_t* get_config(private_child_sa_t *this) { - return this->policy; + return this->config; } /** @@ -220,7 +220,7 @@ static void updown(private_child_sa_t *this, bool up) iterator_t *iterator; char *script; - script = this->policy->get_updown(this->policy); + script = this->config->get_updown(this->config); if (script == NULL) { @@ -300,7 +300,7 @@ static void updown(private_child_sa_t *this, bool up) policy->my_ts->is_host(policy->my_ts, this->me.addr) ? "-host" : "-client", this->me.addr->get_family(this->me.addr) == AF_INET ? "" : "-ipv6", - this->policy->get_name(this->policy), + this->config->get_name(this->config), ifname ? ifname : "(unknown)", this->reqid, this->me.addr, @@ -316,7 +316,7 @@ static void updown(private_child_sa_t *this, bool up) policy->other_ts->get_from_port(policy->other_ts), policy->other_ts->get_protocol(policy->other_ts), virtual_ip, - this->policy->get_hostaccess(this->policy) ? + this->config->get_hostaccess(this->config) ? "PLUTO_HOST_ACCESS='1' " : "", script); free(ifname); @@ -528,8 +528,8 @@ static status_t install(private_child_sa_t *this, proposal_t *proposal, natt = NULL; } - soft = this->policy->get_soft_lifetime(this->policy); - hard = this->policy->get_hard_lifetime(this->policy); + soft = this->config->get_lifetime(this->config, TRUE); + hard = this->config->get_lifetime(this->config, FALSE); /* send SA down to the kernel */ DBG2(DBG_CHD, " SPI 0x%.8x, src %H dst %H", ntohl(spi), src, dst); @@ -665,10 +665,10 @@ static status_t add_policies(private_child_sa_t *this, policy = malloc_thing(sa_policy_t); policy->my_ts = my_ts->clone(my_ts); policy->other_ts = other_ts->clone(other_ts); - this->policies->insert_last(this->policies, (void*)policy); + this->policies->insert_last(this->policies, policy); /* add to separate list to query them via get_*_traffic_selectors() */ - this->my_ts->insert_last(this->my_ts, (void*)policy->my_ts); - this->other_ts->insert_last(this->other_ts, (void*)policy->other_ts); + this->my_ts->insert_last(this->my_ts, policy->my_ts); + this->other_ts->insert_last(this->other_ts, policy->other_ts); } } my_iter->destroy(my_iter); @@ -685,18 +685,14 @@ static status_t add_policies(private_child_sa_t *this, } /** - * Implementation of child_sa_t.get_my_traffic_selectors. + * Implementation of child_sa_t.get_traffic_selectors. */ -static linked_list_t *get_my_traffic_selectors(private_child_sa_t *this) -{ - return this->my_ts; -} - -/** - * Implementation of child_sa_t.get_my_traffic_selectors. - */ -static linked_list_t *get_other_traffic_selectors(private_child_sa_t *this) +static linked_list_t *get_traffic_selectors(private_child_sa_t *this, bool local) { + if (local) + { + return this->my_ts; + } return this->other_ts; } @@ -762,7 +758,7 @@ static int print(FILE *stream, const struct printf_info *info, now = time(NULL); written += fprintf(stream, "%12s{%d}: %N, %N", - this->policy->get_name(this->policy), this->reqid, + this->config->get_name(this->config), this->reqid, child_sa_state_names, this->state, mode_names, this->mode); @@ -775,7 +771,7 @@ static int print(FILE *stream, const struct printf_info *info, if (info->alt) { written += fprintf(stream, "\n%12s{%d}: ", - this->policy->get_name(this->policy), + this->config->get_name(this->config), this->reqid); if (this->protocol == PROTO_ESP) @@ -814,7 +810,7 @@ static int print(FILE *stream, const struct printf_info *info, while (iterator->iterate(iterator, (void**)&policy)) { written += fprintf(stream, "\n%12s{%d}: %R===%R, last use: ", - this->policy->get_name(this->policy), this->reqid, + this->config->get_name(this->config), this->reqid, policy->my_ts, policy->other_ts); /* query time of last policy use */ @@ -1066,7 +1062,7 @@ static void destroy(private_child_sa_t *this) this->other.addr->destroy(this->other.addr); this->me.id->destroy(this->me.id); this->other.id->destroy(this->other.id); - this->policy->destroy(this->policy); + this->config->destroy(this->config); DESTROY_IF(this->virtual_ip); free(this); } @@ -1076,7 +1072,7 @@ static void destroy(private_child_sa_t *this) */ child_sa_t * child_sa_create(host_t *me, host_t* other, identification_t *my_id, identification_t *other_id, - policy_t *policy, u_int32_t rekey, bool use_natt) + child_cfg_t *config, u_int32_t rekey, bool use_natt) { static u_int32_t reqid = 0; private_child_sa_t *this = malloc_thing(private_child_sa_t); @@ -1091,12 +1087,11 @@ child_sa_t * child_sa_create(host_t *me, host_t* other, this->public.update = (status_t(*)(child_sa_t*,proposal_t*,mode_t,prf_plus_t*))update; this->public.update_hosts = (status_t (*)(child_sa_t*,host_t*,host_t*,host_diff_t,host_diff_t))update_hosts; this->public.add_policies = (status_t (*)(child_sa_t*, linked_list_t*,linked_list_t*,mode_t))add_policies; - this->public.get_my_traffic_selectors = (linked_list_t*(*)(child_sa_t*))get_my_traffic_selectors; - this->public.get_other_traffic_selectors = (linked_list_t*(*)(child_sa_t*))get_other_traffic_selectors; + this->public.get_traffic_selectors = (linked_list_t*(*)(child_sa_t*,bool))get_traffic_selectors; this->public.get_use_time = (status_t (*)(child_sa_t*,bool,time_t*))get_use_time; this->public.set_state = (void(*)(child_sa_t*,child_sa_state_t))set_state; this->public.get_state = (child_sa_state_t(*)(child_sa_t*))get_state; - this->public.get_policy = (policy_t*(*)(child_sa_t*))get_policy; + this->public.get_config = (child_cfg_t*(*)(child_sa_t*))get_config; this->public.set_virtual_ip = (void(*)(child_sa_t*,host_t*))set_virtual_ip; this->public.destroy = (void(*)(child_sa_t*))destroy; @@ -1123,8 +1118,8 @@ child_sa_t * child_sa_create(host_t *me, host_t* other, this->protocol = PROTO_NONE; this->mode = MODE_TUNNEL; this->virtual_ip = NULL; - this->policy = policy; - policy->get_ref(policy); + this->config = config; + config->get_ref(config); return &this->public; } diff --git a/src/charon/sa/child_sa.h b/src/charon/sa/child_sa.h index 216e56659..3169b975a 100644 --- a/src/charon/sa/child_sa.h +++ b/src/charon/sa/child_sa.h @@ -32,7 +32,7 @@ typedef struct child_sa_t child_sa_t; #include <crypto/prf_plus.h> #include <encoding/payloads/proposal_substructure.h> #include <config/proposal.h> -#include <config/policies/policy.h> +#include <config/child_cfg.h> /** * Where we should start with reqid enumeration @@ -101,7 +101,7 @@ extern enum_name_t *child_sa_state_names; struct child_sa_t { /** - * @brief Get the name of the policy this CHILD_SA uses. + * @brief Get the name of the config this CHILD_SA uses. * * @param this calling object * @return name @@ -214,17 +214,10 @@ struct child_sa_t { * @brief Get the traffic selectors of added policies of local host. * * @param this calling object + * @param local TRUE for own traffic selectors, FALSE for remote * @return list of traffic selectors */ - linked_list_t* (*get_my_traffic_selectors) (child_sa_t *this); - - /** - * @brief Get the traffic selectors of added policies of remote host. - * - * @param this calling object - * @return list of traffic selectors - */ - linked_list_t* (*get_other_traffic_selectors) (child_sa_t *this); + linked_list_t* (*get_traffic_selectors) (child_sa_t *this, bool local); /** * @brief Get the time of this child_sa_t's last use (i.e. last use of any of its policies) @@ -251,12 +244,12 @@ struct child_sa_t { void (*set_state) (child_sa_t *this, child_sa_state_t state); /** - * @brief Get the policy used to set up this child sa. + * @brief Get the config used to set up this child sa. * * @param this calling object - * @return policy + * @return child_cfg */ - policy_t* (*get_policy) (child_sa_t *this); + child_cfg_t* (*get_config) (child_sa_t *this); /** * @brief Set the virtual IP used received from IRAS. @@ -284,7 +277,7 @@ struct child_sa_t { * @param other remote address * @param my_id id of own peer * @param other_id id of remote peer - * @param policy policy this CHILD_SA instantiates + * @param config config to use for this CHILD_SA * @param reqid reqid of old CHILD_SA when rekeying, 0 otherwise * @param use_natt TRUE if NAT traversal is used * @return child_sa_t object @@ -293,6 +286,6 @@ struct child_sa_t { */ child_sa_t * child_sa_create(host_t *me, host_t *other, identification_t *my_id, identification_t* other_id, - policy_t *policy, u_int32_t reqid, bool use_natt); + child_cfg_t *config, u_int32_t reqid, bool use_natt); #endif /*CHILD_SA_H_*/ diff --git a/src/charon/sa/ike_sa.c b/src/charon/sa/ike_sa.c index 68aba3064..ec69f619d 100644 --- a/src/charon/sa/ike_sa.c +++ b/src/charon/sa/ike_sa.c @@ -56,13 +56,13 @@ #include <sa/tasks/child_create.h> #include <sa/tasks/child_delete.h> #include <sa/tasks/child_rekey.h> -#include <queues/jobs/retransmit_job.h> -#include <queues/jobs/delete_ike_sa_job.h> -#include <queues/jobs/send_dpd_job.h> -#include <queues/jobs/send_keepalive_job.h> -#include <queues/jobs/rekey_ike_sa_job.h> -#include <queues/jobs/route_job.h> -#include <queues/jobs/initiate_job.h> +#include <processing/jobs/retransmit_job.h> +#include <processing/jobs/delete_ike_sa_job.h> +#include <processing/jobs/send_dpd_job.h> +#include <processing/jobs/send_keepalive_job.h> +#include <processing/jobs/rekey_ike_sa_job.h> +#include <processing/jobs/route_job.h> +#include <processing/jobs/initiate_job.h> #ifndef RESOLV_CONF @@ -105,14 +105,14 @@ struct private_ike_sa_t { ike_sa_state_t state; /** - * connection used to establish this IKE_SA. + * IKE configuration used to set up this IKE_SA */ - connection_t *connection; + ike_cfg_t *ike_cfg; /** * Peer and authentication information to establish IKE_SA. */ - policy_t *policy; + peer_cfg_t *peer_cfg; /** * Juggles tasks to process messages @@ -273,79 +273,105 @@ static u_int32_t get_unique_id(private_ike_sa_t *this) */ static char *get_name(private_ike_sa_t *this) { - if (this->connection) + if (this->peer_cfg) { - return this->connection->get_name(this->connection); + return this->peer_cfg->get_name(this->peer_cfg); } return "(unnamed)"; } /** - * Implementation of ike_sa_t.get_connection + * Implementation of ike_sa_t.get_my_host. */ -static connection_t* get_connection(private_ike_sa_t *this) +static host_t *get_my_host(private_ike_sa_t *this) { - return this->connection; + return this->my_host; } /** - * Implementation of ike_sa_t.set_connection + * Implementation of ike_sa_t.set_my_host. */ -static void set_connection(private_ike_sa_t *this, connection_t *connection) +static void set_my_host(private_ike_sa_t *this, host_t *me) { - this->connection = connection; - connection->get_ref(connection); + DESTROY_IF(this->my_host); + this->my_host = me; } /** - * Implementation of ike_sa_t.get_policy + * Implementation of ike_sa_t.get_other_host. */ -static policy_t *get_policy(private_ike_sa_t *this) +static host_t *get_other_host(private_ike_sa_t *this) { - return this->policy; + return this->other_host; } /** - * Implementation of ike_sa_t.set_policy + * Implementation of ike_sa_t.set_other_host. */ -static void set_policy(private_ike_sa_t *this, policy_t *policy) +static void set_other_host(private_ike_sa_t *this, host_t *other) { - policy->get_ref(policy); - this->policy = policy; + DESTROY_IF(this->other_host); + this->other_host = other; } /** - * Implementation of ike_sa_t.get_my_host. + * Implementation of ike_sa_t.get_peer_cfg */ -static host_t *get_my_host(private_ike_sa_t *this) +static peer_cfg_t* get_peer_cfg(private_ike_sa_t *this) { - return this->my_host; + return this->peer_cfg; } /** - * Implementation of ike_sa_t.set_my_host. + * Implementation of ike_sa_t.set_peer_cfg */ -static void set_my_host(private_ike_sa_t *this, host_t *me) +static void set_peer_cfg(private_ike_sa_t *this, peer_cfg_t *peer_cfg) { - DESTROY_IF(this->my_host); - this->my_host = me; + host_t *me, *other; + identification_t *my_id, *other_id; + + peer_cfg->get_ref(peer_cfg); + this->peer_cfg = peer_cfg; + if (this->ike_cfg == NULL) + { + this->ike_cfg = peer_cfg->get_ike_cfg(peer_cfg); + this->ike_cfg->get_ref(this->ike_cfg); + } + + /* apply values, so we are ready to initate/acquire */ + if (this->my_host->is_anyaddr(this->my_host)) + { + me = this->ike_cfg->get_my_host(this->ike_cfg); + set_my_host(this, me->clone(me)); + } + if (this->other_host->is_anyaddr(this->other_host)) + { + other = this->ike_cfg->get_other_host(this->ike_cfg); + set_other_host(this, other->clone(other)); + } + my_id = this->peer_cfg->get_my_id(this->peer_cfg); + other_id = this->peer_cfg->get_other_id(this->peer_cfg); + DESTROY_IF(this->my_id); + DESTROY_IF(this->other_id); + this->my_id = my_id->clone(my_id); + this->other_id = other_id->clone(other_id); } /** - * Implementation of ike_sa_t.get_other_host. + * Implementation of ike_sa_t.get_ike_cfg */ -static host_t *get_other_host(private_ike_sa_t *this) +static ike_cfg_t *get_ike_cfg(private_ike_sa_t *this) { - return this->other_host; + return this->ike_cfg; } /** - * Implementation of ike_sa_t.set_other_host. + * Implementation of ike_sa_t.set_ike_cfg */ -static void set_other_host(private_ike_sa_t *this, host_t *other) +static void set_ike_cfg(private_ike_sa_t *this, ike_cfg_t *ike_cfg) { - DESTROY_IF(this->other_host); - this->other_host = other; + ike_cfg->get_ref(ike_cfg); + this->ike_cfg = ike_cfg; } /** @@ -356,7 +382,7 @@ static status_t send_dpd(private_ike_sa_t *this) send_dpd_job_t *job; time_t diff, delay; - delay = this->connection->get_dpd_delay(this->connection); + delay = this->peer_cfg->get_dpd_delay(this->peer_cfg); if (delay == 0) { @@ -464,9 +490,9 @@ static void set_state(private_ike_sa_t *this, ike_sa_state_t state) send_dpd(this); /* schedule rekeying/reauthentication */ - soft = this->connection->get_soft_lifetime(this->connection); - hard = this->connection->get_hard_lifetime(this->connection); - reauth = this->connection->get_reauth(this->connection); + soft = this->peer_cfg->get_lifetime(this->peer_cfg, TRUE); + hard = this->peer_cfg->get_lifetime(this->peer_cfg, FALSE); + reauth = this->peer_cfg->use_reauth(this->peer_cfg); DBG1(DBG_IKE, "scheduling %s in %ds, maximum lifetime %ds", reauth ? "reauthentication": "rekeying", soft, hard); @@ -521,7 +547,7 @@ static void reset(private_ike_sa_t *this) } /** - * Update connection host, as addresses may change (NAT) + * Update hosts, as addresses may change (NAT) */ static void update_hosts(private_ike_sa_t *this, host_t *me, host_t *other) { @@ -696,16 +722,16 @@ static status_t process_message(private_ike_sa_t *this, message_t *message) me = message->get_destination(message); other = message->get_source(message); - /* if this IKE_SA is virgin, we check for a connection */ - if (this->connection == NULL) + /* if this IKE_SA is virgin, we check for a config */ + if (this->ike_cfg == NULL) { job_t *job; - this->connection = charon->connections->get_connection_by_hosts( - charon->connections, me, other); - if (this->connection == NULL) + this->ike_cfg = charon->cfg_store->get_ike_cfg(charon->cfg_store, + me, other); + if (this->ike_cfg == NULL) { - /* no connection found for these hosts, destroy */ - DBG1(DBG_IKE, "no connection found for %H...%H, sending %N", + /* no config found for these hosts, destroy */ + DBG1(DBG_IKE, "no IKE config found for %H...%H, sending %N", me, other, notify_type_names, NO_PROPOSAL_CHOSEN); send_notify_response(this, message, NO_PROPOSAL_CHOSEN); return DESTROY_ME; @@ -717,7 +743,7 @@ static status_t process_message(private_ike_sa_t *this, message_t *message) charon->configuration)); } - /* check if message is trustworthy, and update connection information */ + /* check if message is trustworthy, and update host information */ if (this->state == IKE_CREATED || message->get_exchange_type(message) != IKE_SA_INIT) { @@ -729,46 +755,14 @@ static status_t process_message(private_ike_sa_t *this, message_t *message) } /** - * apply the connection/policy information to this IKE_SA - */ -static void apply_config(private_ike_sa_t *this, - connection_t *connection, policy_t *policy) -{ - host_t *me, *other; - identification_t *my_id, *other_id; - - if (this->connection == NULL && this->policy == NULL) - { - this->connection = connection; - connection->get_ref(connection); - this->policy = policy; - policy->get_ref(policy); - - me = connection->get_my_host(connection); - other = connection->get_other_host(connection); - my_id = policy->get_my_id(policy); - other_id = policy->get_other_id(policy); - set_my_host(this, me->clone(me)); - set_other_host(this, other->clone(other)); - DESTROY_IF(this->my_id); - DESTROY_IF(this->other_id); - this->my_id = my_id->clone(my_id); - this->other_id = other_id->clone(other_id); - } -} - -/** * Implementation of ike_sa_t.initiate. */ -static status_t initiate(private_ike_sa_t *this, - connection_t *connection, policy_t *policy) +static status_t initiate(private_ike_sa_t *this, child_cfg_t *child_cfg) { task_t *task; if (this->state == IKE_CREATED) { - /* if we aren't established/establishing, do so */ - apply_config(this, connection, policy); if (this->other_host->is_anyaddr(this->other_host)) { @@ -785,11 +779,11 @@ static status_t initiate(private_ike_sa_t *this, this->task_manager->queue_task(this->task_manager, task); task = (task_t*)ike_auth_create(&this->public, TRUE); this->task_manager->queue_task(this->task_manager, task); - task = (task_t*)ike_config_create(&this->public, policy); + task = (task_t*)ike_config_create(&this->public, TRUE); this->task_manager->queue_task(this->task_manager, task); } - task = (task_t*)child_create_create(&this->public, policy); + task = (task_t*)child_create_create(&this->public, child_cfg); this->task_manager->queue_task(this->task_manager, task); return this->task_manager->initiate(this->task_manager); @@ -800,7 +794,7 @@ static status_t initiate(private_ike_sa_t *this, */ static status_t acquire(private_ike_sa_t *this, u_int32_t reqid) { - policy_t *policy; + child_cfg_t *child_cfg; iterator_t *iterator; child_sa_t *current, *child_sa = NULL; task_t *task; @@ -833,7 +827,6 @@ static status_t acquire(private_ike_sa_t *this, u_int32_t reqid) return FAILED; } - policy = child_sa->get_policy(child_sa); if (this->state == IKE_CREATED) { @@ -845,11 +838,12 @@ static status_t acquire(private_ike_sa_t *this, u_int32_t reqid) this->task_manager->queue_task(this->task_manager, task); task = (task_t*)ike_auth_create(&this->public, TRUE); this->task_manager->queue_task(this->task_manager, task); - task = (task_t*)ike_config_create(&this->public, policy); + task = (task_t*)ike_config_create(&this->public, TRUE); this->task_manager->queue_task(this->task_manager, task); } - child_create = child_create_create(&this->public, policy); + child_cfg = child_sa->get_config(child_sa); + child_create = child_create_create(&this->public, child_cfg); child_create->use_reqid(child_create, reqid); this->task_manager->queue_task(this->task_manager, (task_t*)child_create); @@ -857,40 +851,11 @@ static status_t acquire(private_ike_sa_t *this, u_int32_t reqid) } /** - * compare two lists of traffic selectors for equality - */ -static bool ts_list_equals(linked_list_t *l1, linked_list_t *l2) -{ - bool equals = TRUE; - iterator_t *i1, *i2; - traffic_selector_t *t1, *t2; - - if (l1->get_count(l1) != l2->get_count(l2)) - { - return FALSE; - } - - i1 = l1->create_iterator(l1, TRUE); - i2 = l2->create_iterator(l2, TRUE); - while (i1->iterate(i1, (void**)&t1) && i2->iterate(i2, (void**)&t2)) - { - if (!t1->equals(t1, t2)) - { - equals = FALSE; - break; - } - } - i1->destroy(i1); - i2->destroy(i2); - return equals; -} - -/** * Implementation of ike_sa_t.route. */ -static status_t route(private_ike_sa_t *this, connection_t *connection, policy_t *policy) +static status_t route(private_ike_sa_t *this, child_cfg_t *child_cfg) { - child_sa_t *child_sa = NULL; + child_sa_t *child_sa; iterator_t *iterator; linked_list_t *my_ts, *other_ts; status_t status; @@ -901,27 +866,12 @@ static status_t route(private_ike_sa_t *this, connection_t *connection, policy_t iterator = this->child_sas->create_iterator(this->child_sas, TRUE); while (iterator->iterate(iterator, (void**)&child_sa)) { - if (child_sa->get_state(child_sa) == CHILD_ROUTED) + if (child_sa->get_state(child_sa) == CHILD_ROUTED && + streq(child_sa->get_name(child_sa), child_cfg->get_name(child_cfg))) { - linked_list_t *my_ts_conf, *other_ts_conf; - - my_ts = child_sa->get_my_traffic_selectors(child_sa); - other_ts = child_sa->get_other_traffic_selectors(child_sa); - - my_ts_conf = policy->get_my_traffic_selectors(policy, this->my_host); - other_ts_conf = policy->get_other_traffic_selectors(policy, this->other_host); - - if (ts_list_equals(my_ts, my_ts_conf) && - ts_list_equals(other_ts, other_ts_conf)) - { - iterator->destroy(iterator); - my_ts_conf->destroy_offset(my_ts_conf, offsetof(traffic_selector_t, destroy)); - other_ts_conf->destroy_offset(other_ts_conf, offsetof(traffic_selector_t, destroy)); - SIG(CHILD_ROUTE_FAILED, "CHILD_SA with such a policy already routed"); - return FAILED; - } - my_ts_conf->destroy_offset(my_ts_conf, offsetof(traffic_selector_t, destroy)); - other_ts_conf->destroy_offset(other_ts_conf, offsetof(traffic_selector_t, destroy)); + iterator->destroy(iterator); + SIG(CHILD_ROUTE_FAILED, "CHILD_SA with such a config already routed"); + return FAILED; } } iterator->destroy(iterator); @@ -934,9 +884,6 @@ static status_t route(private_ike_sa_t *this, connection_t *connection, policy_t "unable to route CHILD_SA, as its IKE_SA gets deleted"); return FAILED; case IKE_CREATED: - /* apply connection information, we need it to acquire */ - apply_config(this, connection, policy); - break; case IKE_CONNECTING: case IKE_ESTABLISHED: default: @@ -944,29 +891,37 @@ static status_t route(private_ike_sa_t *this, connection_t *connection, policy_t } /* install kernel policies */ - child_sa = child_sa_create(this->my_host, this->other_host, - this->my_id, this->other_id, policy, FALSE, 0); + child_sa = child_sa_create(this->my_host, this->other_host, this->my_id, + this->other_id, child_cfg, FALSE, 0); - my_ts = policy->get_my_traffic_selectors(policy, this->my_host); - other_ts = policy->get_other_traffic_selectors(policy, this->other_host); + my_ts = child_cfg->get_traffic_selectors(child_cfg, TRUE, NULL, + this->my_host); + other_ts = child_cfg->get_traffic_selectors(child_cfg, FALSE, NULL, + this->other_host); status = child_sa->add_policies(child_sa, my_ts, other_ts, - policy->get_mode(policy)); + child_cfg->get_mode(child_cfg)); my_ts->destroy_offset(my_ts, offsetof(traffic_selector_t, destroy)); other_ts->destroy_offset(other_ts, offsetof(traffic_selector_t, destroy)); - this->child_sas->insert_last(this->child_sas, child_sa); - SIG(CHILD_ROUTE_SUCCESS, "CHILD_SA routed"); + if (status == SUCCESS) + { + this->child_sas->insert_last(this->child_sas, child_sa); + SIG(CHILD_ROUTE_SUCCESS, "CHILD_SA routed"); + } + else + { + SIG(CHILD_ROUTE_FAILED, "routing CHILD_SA failed"); + } return status; } /** * Implementation of ike_sa_t.unroute. */ -static status_t unroute(private_ike_sa_t *this, policy_t *policy) +static status_t unroute(private_ike_sa_t *this, child_cfg_t *child_cfg) { iterator_t *iterator; - child_sa_t *child_sa = NULL; + child_sa_t *child_sa; bool found = FALSE; - linked_list_t *my_ts, *other_ts, *my_ts_conf, *other_ts_conf; SIG(CHILD_UNROUTE_START, "unrouting CHILD_SA"); @@ -974,27 +929,14 @@ static status_t unroute(private_ike_sa_t *this, policy_t *policy) iterator = this->child_sas->create_iterator(this->child_sas, TRUE); while (iterator->iterate(iterator, (void**)&child_sa)) { - if (child_sa->get_state(child_sa) == CHILD_ROUTED) + if (child_sa->get_state(child_sa) == CHILD_ROUTED && + streq(child_sa->get_name(child_sa), child_cfg->get_name(child_cfg))) { - my_ts = child_sa->get_my_traffic_selectors(child_sa); - other_ts = child_sa->get_other_traffic_selectors(child_sa); - - my_ts_conf = policy->get_my_traffic_selectors(policy, this->my_host); - other_ts_conf = policy->get_other_traffic_selectors(policy, this->other_host); - - if (ts_list_equals(my_ts, my_ts_conf) && - ts_list_equals(other_ts, other_ts_conf)) - { - iterator->remove(iterator); - SIG(CHILD_UNROUTE_SUCCESS, "CHILD_SA unrouted"); - child_sa->destroy(child_sa); - my_ts_conf->destroy_offset(my_ts_conf, offsetof(traffic_selector_t, destroy)); - other_ts_conf->destroy_offset(other_ts_conf, offsetof(traffic_selector_t, destroy)); - found = TRUE; - break; - } - my_ts_conf->destroy_offset(my_ts_conf, offsetof(traffic_selector_t, destroy)); - other_ts_conf->destroy_offset(other_ts_conf, offsetof(traffic_selector_t, destroy)); + iterator->remove(iterator); + SIG(CHILD_UNROUTE_SUCCESS, "CHILD_SA unrouted"); + child_sa->destroy(child_sa); + found = TRUE; + break; } } iterator->destroy(iterator); @@ -1021,7 +963,7 @@ static status_t retransmit(private_ike_sa_t *this, u_int32_t message_id) this->time.outbound = time(NULL); if (this->task_manager->retransmit(this->task_manager, message_id) != SUCCESS) { - policy_t *policy; + child_cfg_t *child_cfg; child_sa_t* child_sa; linked_list_t *to_route, *to_restart; iterator_t *iterator; @@ -1032,7 +974,7 @@ static status_t retransmit(private_ike_sa_t *this, u_int32_t message_id) case IKE_CONNECTING: { /* retry IKE_SA_INIT if we have multiple keyingtries */ - u_int32_t tries = this->connection->get_keyingtries(this->connection); + u_int32_t tries = this->peer_cfg->get_keyingtries(this->peer_cfg); this->keyingtry++; if (tries == 0 || tries > this->keyingtry) { @@ -1060,23 +1002,23 @@ static status_t retransmit(private_ike_sa_t *this, u_int32_t message_id) iterator = this->child_sas->create_iterator(this->child_sas, TRUE); while (iterator->iterate(iterator, (void**)&child_sa)) { - policy = child_sa->get_policy(child_sa); + child_cfg = child_sa->get_config(child_sa); if (child_sa->get_state(child_sa) == CHILD_ROUTED) { /* reroute routed CHILD_SAs */ - to_route->insert_last(to_route, policy); + to_route->insert_last(to_route, child_cfg); } else { /* use DPD action for established CHILD_SAs */ - switch (policy->get_dpd_action(policy)) + switch (this->peer_cfg->get_dpd_action(this->peer_cfg)) { case DPD_ROUTE: - to_route->insert_last(to_route, policy); + to_route->insert_last(to_route, child_cfg); break; case DPD_RESTART: - to_restart->insert_last(to_restart, policy); + to_restart->insert_last(to_restart, child_cfg); break; default: break; @@ -1094,15 +1036,15 @@ static status_t retransmit(private_ike_sa_t *this, u_int32_t message_id) new = (private_ike_sa_t*)charon->ike_sa_manager->checkout_new( charon->ike_sa_manager, TRUE); - apply_config(new, this->connection, this->policy); - /* use actual used host, not the wildcarded one in connection */ + set_peer_cfg(new, this->peer_cfg); + /* use actual used host, not the wildcarded one in config */ new->other_host->destroy(new->other_host); new->other_host = this->other_host->clone(this->other_host); /* install routes */ - while (to_route->remove_last(to_route, (void**)&policy) == SUCCESS) + while (to_route->remove_last(to_route, (void**)&child_cfg) == SUCCESS) { - route(new, new->connection, policy); + route(new, child_cfg); } /* restart children */ @@ -1114,14 +1056,14 @@ static status_t retransmit(private_ike_sa_t *this, u_int32_t message_id) new->task_manager->queue_task(new->task_manager, task); task = (task_t*)ike_cert_create(&new->public, TRUE); new->task_manager->queue_task(new->task_manager, task); - task = (task_t*)ike_config_create(&new->public, new->policy); + task = (task_t*)ike_config_create(&new->public, TRUE); new->task_manager->queue_task(new->task_manager, task); task = (task_t*)ike_auth_create(&new->public, TRUE); new->task_manager->queue_task(new->task_manager, task); - while (to_restart->remove_last(to_restart, (void**)&policy) == SUCCESS) + while (to_restart->remove_last(to_restart, (void**)&child_cfg) == SUCCESS) { - task = (task_t*)child_create_create(&new->public, policy); + task = (task_t*)child_create_create(&new->public, child_cfg); new->task_manager->queue_task(new->task_manager, task); } new->task_manager->initiate(new->task_manager); @@ -1542,14 +1484,14 @@ static void reestablish(private_ike_sa_t *this) private_ike_sa_t *other; iterator_t *iterator; child_sa_t *child_sa; - policy_t *policy; + child_cfg_t *child_cfg; task_t *task; job_t *job; other = (private_ike_sa_t*)charon->ike_sa_manager->checkout_new( charon->ike_sa_manager, TRUE); - apply_config(other, this->connection, this->policy); + set_peer_cfg(other, this->peer_cfg); other->other_host->destroy(other->other_host); other->other_host = this->other_host->clone(this->other_host); @@ -1561,7 +1503,7 @@ static void reestablish(private_ike_sa_t *this) other->task_manager->queue_task(other->task_manager, task); task = (task_t*)ike_cert_create(&other->public, TRUE); other->task_manager->queue_task(other->task_manager, task); - task = (task_t*)ike_config_create(&other->public, other->policy); + task = (task_t*)ike_config_create(&other->public, TRUE); other->task_manager->queue_task(other->task_manager, task); task = (task_t*)ike_auth_create(&other->public, TRUE); other->task_manager->queue_task(other->task_manager, task); @@ -1583,8 +1525,8 @@ static void reestablish(private_ike_sa_t *this) } default: { - policy = child_sa->get_policy(child_sa); - task = (task_t*)child_create_create(&other->public, policy); + child_cfg = child_sa->get_config(child_sa); + task = (task_t*)child_create_create(&other->public, child_cfg); other->task_manager->queue_task(other->task_manager, task); break; } @@ -1865,9 +1807,9 @@ static int print(FILE *stream, const struct printf_info *info, bool reauth = FALSE; private_ike_sa_t *this = *((private_ike_sa_t**)(args[0])); - if (this->connection) + if (this->peer_cfg) { - reauth = this->connection->get_reauth(this->connection); + reauth = this->peer_cfg->use_reauth(this->peer_cfg); } if (this == NULL) @@ -1879,15 +1821,19 @@ static int print(FILE *stream, const struct printf_info *info, this->unique_id, ike_sa_state_names, this->state, this->my_host, this->my_id, this->other_host, this->other_id); - written += fprintf(stream, "\n%12s[%d]: IKE SPIs: %J, %s in %ds", - get_name(this), this->unique_id, this->ike_sa_id, - this->connection && reauth? "reauthentication":"rekeying", - this->time.rekey - time(NULL)); - - if (info->alt) + if (this->time.rekey) { - + written += fprintf(stream, "\n%12s[%d]: IKE SPIs: %J, %s in %ds", + get_name(this), this->unique_id, this->ike_sa_id, + reauth ? "reauthentication" : "rekeying", + this->time.rekey - time(NULL)); + } + else + { + written += fprintf(stream, "\n%12s[%d]: IKE SPIs: %J, rekeying disabled", + get_name(this), this->unique_id, this->ike_sa_id); } + return written; } @@ -1931,8 +1877,8 @@ static void destroy(private_ike_sa_t *this) DESTROY_IF(this->my_id); DESTROY_IF(this->other_id); - DESTROY_IF(this->connection); - DESTROY_IF(this->policy); + DESTROY_IF(this->ike_cfg); + DESTROY_IF(this->peer_cfg); this->ike_sa_id->destroy(this->ike_sa_id); this->task_manager->destroy(this->task_manager); @@ -1952,14 +1898,14 @@ ike_sa_t * ike_sa_create(ike_sa_id_t *ike_sa_id) this->public.set_state = (void(*)(ike_sa_t*,ike_sa_state_t)) set_state; this->public.get_name = (char*(*)(ike_sa_t*))get_name; this->public.process_message = (status_t(*)(ike_sa_t*, message_t*)) process_message; - this->public.initiate = (status_t(*)(ike_sa_t*,connection_t*,policy_t*)) initiate; - this->public.route = (status_t(*)(ike_sa_t*,connection_t*,policy_t*)) route; - this->public.unroute = (status_t(*)(ike_sa_t*,policy_t*)) unroute; + this->public.initiate = (status_t(*)(ike_sa_t*,child_cfg_t*)) initiate; + this->public.route = (status_t(*)(ike_sa_t*,child_cfg_t*)) route; + this->public.unroute = (status_t(*)(ike_sa_t*,child_cfg_t*)) unroute; this->public.acquire = (status_t(*)(ike_sa_t*,u_int32_t)) acquire; - this->public.get_connection = (connection_t*(*)(ike_sa_t*))get_connection; - this->public.set_connection = (void(*)(ike_sa_t*,connection_t*))set_connection; - this->public.get_policy = (policy_t*(*)(ike_sa_t*))get_policy; - this->public.set_policy = (void(*)(ike_sa_t*,policy_t*))set_policy; + this->public.get_ike_cfg = (ike_cfg_t*(*)(ike_sa_t*))get_ike_cfg; + this->public.set_ike_cfg = (void(*)(ike_sa_t*,ike_cfg_t*))set_ike_cfg; + this->public.get_peer_cfg = (peer_cfg_t*(*)(ike_sa_t*))get_peer_cfg; + this->public.set_peer_cfg = (void(*)(ike_sa_t*,peer_cfg_t*))set_peer_cfg; this->public.get_id = (ike_sa_id_t*(*)(ike_sa_t*)) get_id; this->public.get_my_host = (host_t*(*)(ike_sa_t*)) get_my_host; this->public.set_my_host = (void(*)(ike_sa_t*,host_t*)) set_my_host; @@ -2019,8 +1965,8 @@ ike_sa_t * ike_sa_create(ike_sa_id_t *ike_sa_id) this->time.established = 0; this->time.rekey = 0; this->time.delete = 0; - this->connection = NULL; - this->policy = NULL; + this->ike_cfg = NULL; + this->peer_cfg = NULL; this->task_manager = task_manager_create(&this->public); this->unique_id = ++unique_id; this->my_virtual_ip = NULL; diff --git a/src/charon/sa/ike_sa.h b/src/charon/sa/ike_sa.h index 604ec94a9..c386f92eb 100644 --- a/src/charon/sa/ike_sa.h +++ b/src/charon/sa/ike_sa.h @@ -39,9 +39,8 @@ typedef struct ike_sa_t ike_sa_t; #include <crypto/prfs/prf.h> #include <crypto/crypters/crypter.h> #include <crypto/signers/signer.h> -#include <config/connections/connection.h> -#include <config/policies/policy.h> -#include <config/proposal.h> +#include <config/peer_cfg.h> +#include <config/ike_cfg.h> /** * @brief State of an IKE_SA. @@ -237,51 +236,49 @@ struct ike_sa_t { void (*set_other_id) (ike_sa_t *this, identification_t *other); /** - * @brief Get the connection used by this IKE_SA. + * @brief Get the config used to setup this IKE_SA. * * @param this calling object - * @return connection + * @return ike_config */ - connection_t* (*get_connection) (ike_sa_t *this); + ike_cfg_t* (*get_ike_cfg) (ike_sa_t *this); /** - * @brief Set the connection to use with this IKE_SA. + * @brief Set the config to setup this IKE_SA. * * @param this calling object - * @param connection connection to use + * @param config ike_config to use */ - void (*set_connection) (ike_sa_t *this, connection_t* connection); + void (*set_ike_cfg) (ike_sa_t *this, ike_cfg_t* config); /** - * @brief Get the policy used by this IKE_SA. + * @brief Get the peer config used by this IKE_SA. * * @param this calling object - * @return policy + * @return peer_config */ - policy_t* (*get_policy) (ike_sa_t *this); + peer_cfg_t* (*get_peer_cfg) (ike_sa_t *this); /** - * @brief Set the policy to use with this IKE_SA. + * @brief Set the peer config to use with this IKE_SA. * * @param this calling object - * @param policy policy to use + * @param config peer_config to use */ - void (*set_policy) (ike_sa_t *this, policy_t *policy); + void (*set_peer_cfg) (ike_sa_t *this, peer_cfg_t *config); /** * @brief Initiate a new connection. * - * The policy/connection is owned by the IKE_SA after the call, so - * do not modify or destroy it. + * The configs are owned by the IKE_SA after the call. * * @param this calling object - * @param connection connection to initiate - * @param policy policy to set up + * @param child_cfg child config to create CHILD from * @return * - SUCCESS if initialization started - * - DESTROY_ME if initialization failed and IKE_SA MUST be deleted + * - DESTROY_ME if initialization failed */ - status_t (*initiate) (ike_sa_t *this, connection_t *connection, policy_t *policy); + status_t (*initiate) (ike_sa_t *this, child_cfg_t *child_cfg); /** * @brief Route a policy in the kernel. @@ -290,28 +287,26 @@ struct ike_sa_t { * the kernel requests connection setup from the IKE_SA via acquire(). * * @param this calling object - * @param connection connection definition used for routing - * @param policy policy to route + * @param child_cfg child config to route * @return * - SUCCESS if routed successfully * - FAILED if routing failed */ - status_t (*route) (ike_sa_t *this, connection_t *connection, policy_t *policy); + status_t (*route) (ike_sa_t *this, child_cfg_t *child_cfg); /** * @brief Unroute a policy in the kernel previously routed. * * @param this calling object - * @param policy policy to route + * @param child_cfg child config to unroute * @return * - SUCCESS if route removed - * - DESTROY_ME if last route was removed from - * an IKE_SA which was not established + * - DESTROY_ME if last CHILD_SA was unrouted */ - status_t (*unroute) (ike_sa_t *this, policy_t *policy); + status_t (*unroute) (ike_sa_t *this, child_cfg_t *child_cfg); /** - * @brief Acquire connection setup for a policy. + * @brief Acquire connection setup for an installed kernel policy. * * If an installed policy raises an acquire, the kernel calls * this function to establish the CHILD_SA (and maybe the IKE_SA). @@ -320,7 +315,7 @@ struct ike_sa_t { * @param reqid reqid of the CHILD_SA the policy belongs to. * @return * - SUCCESS if initialization started - * - DESTROY_ME if initialization failed and IKE_SA MUST be deleted + * - DESTROY_ME if initialization failed */ status_t (*acquire) (ike_sa_t *this, u_int32_t reqid); diff --git a/src/charon/sa/ike_sa_manager.c b/src/charon/sa/ike_sa_manager.c index 791ef805e..287f049d3 100644 --- a/src/charon/sa/ike_sa_manager.c +++ b/src/charon/sa/ike_sa_manager.c @@ -363,6 +363,7 @@ static ike_sa_t *checkout_new(private_ike_sa_manager_t* this, bool initiator) pthread_mutex_unlock(&this->mutex); DBG2(DBG_MGR, "created IKE_SA: %J, %d IKE_SAs in manager", id, this->ike_sa_list->get_count(this->ike_sa_list)); + id->destroy(id); return entry->ike_sa; } diff --git a/src/charon/sa/task_manager.c b/src/charon/sa/task_manager.c index 844300735..cbdc67837 100644 --- a/src/charon/sa/task_manager.c +++ b/src/charon/sa/task_manager.c @@ -35,7 +35,7 @@ #include <sa/tasks/child_rekey.h> #include <sa/tasks/child_delete.h> #include <encoding/payloads/delete_payload.h> -#include <queues/jobs/retransmit_job.h> +#include <processing/jobs/retransmit_job.h> typedef struct exchange_t exchange_t; @@ -577,7 +577,7 @@ static status_t process_request(private_task_manager_t *this, this->passive_tasks->insert_last(this->passive_tasks, task); task = (task_t*)ike_auth_create(this->ike_sa, FALSE); this->passive_tasks->insert_last(this->passive_tasks, task); - task = (task_t*)ike_config_create(this->ike_sa, NULL); + task = (task_t*)ike_config_create(this->ike_sa, FALSE); this->passive_tasks->insert_last(this->passive_tasks, task); task = (task_t*)child_create_create(this->ike_sa, NULL); this->passive_tasks->insert_last(this->passive_tasks, task); diff --git a/src/charon/sa/tasks/child_create.c b/src/charon/sa/tasks/child_create.c index 781d679f2..5ed9791ab 100644 --- a/src/charon/sa/tasks/child_create.c +++ b/src/charon/sa/tasks/child_create.c @@ -64,9 +64,9 @@ struct private_child_create_t { chunk_t other_nonce; /** - * policy to create the CHILD_SA from + * config to create the CHILD_SA from */ - policy_t *policy; + child_cfg_t *config; /** * list of proposal candidates @@ -198,7 +198,7 @@ static status_t select_and_install(private_child_create_t *this) my_vip = this->ike_sa->get_virtual_ip(this->ike_sa, TRUE); other_vip = this->ike_sa->get_virtual_ip(this->ike_sa, FALSE); - this->proposal = this->policy->select_proposal(this->policy, this->proposals); + this->proposal = this->config->select_proposal(this->config, this->proposals); if (this->proposal == NULL) { @@ -206,28 +206,31 @@ static status_t select_and_install(private_child_create_t *this) return FAILED; } - if (this->initiator && my_vip) - { /* if we have a virtual IP, shorten our TS to the minimum */ - my_ts = this->policy->select_my_traffic_selectors(this->policy, my_ts, - my_vip); + if (my_vip == NULL) + { + my_vip = me; + } + else if (this->initiator) + { /* to setup firewall rules correctly, CHILD_SA needs the virtual IP */ this->child_sa->set_virtual_ip(this->child_sa, my_vip); } - else - { /* shorten in the host2host case only */ - my_ts = this->policy->select_my_traffic_selectors(this->policy, - my_ts, me); - } - if (other_vip) - { /* if other has a virtual IP, shorten it's traffic selectors to it */ - other_ts = this->policy->select_other_traffic_selectors(this->policy, - other_ts, other_vip); + if (other_vip == NULL) + { + other_vip = other; } - else - { /* use his host for the host2host case */ - other_ts = this->policy->select_other_traffic_selectors(this->policy, - other_ts, other); + + my_ts = this->config->get_traffic_selectors(this->config, TRUE, my_ts, + my_vip); + other_ts = this->config->get_traffic_selectors(this->config, FALSE, other_ts, + other_vip); + + if (my_ts->get_count(my_ts) == 0 || other_ts->get_count(other_ts) == 0) + { + SIG(CHILD_UP_FAILED, "no acceptable traffic selectors found"); + return FAILED; } + this->tsr->destroy_offset(this->tsr, offsetof(traffic_selector_t, destroy)); this->tsi->destroy_offset(this->tsi, offsetof(traffic_selector_t, destroy)); if (this->initiator) @@ -241,13 +244,6 @@ static status_t select_and_install(private_child_create_t *this) this->tsi = other_ts; } - if (this->tsi->get_count(this->tsi) == 0 || - this->tsr->get_count(this->tsr) == 0) - { - SIG(CHILD_UP_FAILED, "no acceptable traffic selectors found"); - return FAILED; - } - if (!this->initiator) { /* check if requested mode is acceptable, downgrade if required */ @@ -421,6 +417,7 @@ static void process_payloads(private_child_create_t *this, message_t *message) static status_t build_i(private_child_create_t *this, message_t *message) { host_t *me, *other, *vip; + peer_cfg_t *peer_cfg; switch (message->get_exchange_type(message)) { @@ -448,25 +445,29 @@ static status_t build_i(private_child_create_t *this, message_t *message) me = this->ike_sa->get_my_host(this->ike_sa); other = this->ike_sa->get_other_host(this->ike_sa); - vip = this->policy->get_virtual_ip(this->policy, NULL); + peer_cfg = this->ike_sa->get_peer_cfg(this->ike_sa); + vip = peer_cfg->get_virtual_ip(peer_cfg, NULL); if (vip) { /* propose a 0.0.0.0/0 subnet when we use virtual ip */ - this->tsi = this->policy->get_my_traffic_selectors(this->policy, NULL); + this->tsi = this->config->get_traffic_selectors(this->config, TRUE, + NULL, NULL); vip->destroy(vip); } else { /* but shorten a 0.0.0.0/0 subnet to the actual address if host2host */ - this->tsi = this->policy->get_my_traffic_selectors(this->policy, me); + this->tsi = this->config->get_traffic_selectors(this->config, TRUE, + NULL, me); } - this->tsr = this->policy->get_other_traffic_selectors(this->policy, other); - this->proposals = this->policy->get_proposals(this->policy); - this->mode = this->policy->get_mode(this->policy); + this->tsr = this->config->get_traffic_selectors(this->config, FALSE, + NULL, other); + this->proposals = this->config->get_proposals(this->config); + this->mode = this->config->get_mode(this->config); this->child_sa = child_sa_create(me, other, this->ike_sa->get_my_id(this->ike_sa), this->ike_sa->get_other_id(this->ike_sa), - this->policy, this->reqid, + this->config, this->reqid, this->ike_sa->is_natt_enabled(this->ike_sa)); if (this->child_sa->alloc(this->child_sa, this->proposals) != SUCCESS) @@ -492,6 +493,8 @@ static status_t build_i(private_child_create_t *this, message_t *message) */ static status_t process_r(private_child_create_t *this, message_t *message) { + peer_cfg_t *peer_cfg; + switch (message->get_exchange_type(message)) { case IKE_SA_INIT: @@ -517,18 +520,13 @@ static status_t process_r(private_child_create_t *this, message_t *message) return NEED_MORE; } - this->policy = charon->policies->get_policy(charon->policies, - this->ike_sa->get_my_id(this->ike_sa), - this->ike_sa->get_other_id(this->ike_sa), - this->tsr, this->tsi, - this->ike_sa->get_my_host(this->ike_sa), - this->ike_sa->get_other_host(this->ike_sa)); - - if (this->policy && this->ike_sa->get_policy(this->ike_sa) == NULL) + peer_cfg = this->ike_sa->get_peer_cfg(this->ike_sa); + if (peer_cfg) { - this->ike_sa->set_policy(this->ike_sa, this->policy); + this->config = peer_cfg->select_child_cfg(peer_cfg, this->tsr, this->tsi, + this->ike_sa->get_my_host(this->ike_sa), + this->ike_sa->get_other_host(this->ike_sa)); } - return NEED_MORE; } @@ -565,10 +563,11 @@ static status_t build_r(private_child_create_t *this, message_t *message) return SUCCESS; } - if (this->policy == NULL) + if (this->config == NULL) { - SIG(CHILD_UP_FAILED, "no acceptable policy found"); - message->add_notify(message, FALSE, NO_PROPOSAL_CHOSEN, chunk_empty); + SIG(CHILD_UP_FAILED, "traffic selectors %#R=== %#R inacceptable", + this->tsr, this->tsi); + message->add_notify(message, FALSE, TS_UNACCEPTABLE, chunk_empty); return SUCCESS; } @@ -576,12 +575,12 @@ static status_t build_r(private_child_create_t *this, message_t *message) this->ike_sa->get_other_host(this->ike_sa), this->ike_sa->get_my_id(this->ike_sa), this->ike_sa->get_other_id(this->ike_sa), - this->policy, this->reqid, + this->config, this->reqid, this->ike_sa->is_natt_enabled(this->ike_sa)); if (select_and_install(this) != SUCCESS) { - message->add_notify(message, FALSE, TS_UNACCEPTABLE, chunk_empty); + message->add_notify(message, FALSE, NO_PROPOSAL_CHOSEN, chunk_empty); return SUCCESS; } @@ -756,14 +755,14 @@ static void destroy(private_child_create_t *this) this->proposals->destroy_offset(this->proposals, offsetof(proposal_t, destroy)); } - DESTROY_IF(this->policy); + DESTROY_IF(this->config); free(this); } /* * Described in header. */ -child_create_t *child_create_create(ike_sa_t *ike_sa, policy_t *policy) +child_create_t *child_create_create(ike_sa_t *ike_sa, child_cfg_t *config) { private_child_create_t *this = malloc_thing(private_child_create_t); @@ -773,12 +772,12 @@ child_create_t *child_create_create(ike_sa_t *ike_sa, policy_t *policy) this->public.task.get_type = (task_type_t(*)(task_t*))get_type; this->public.task.migrate = (void(*)(task_t*,ike_sa_t*))migrate; this->public.task.destroy = (void(*)(task_t*))destroy; - if (policy) + if (config) { this->public.task.build = (status_t(*)(task_t*,message_t*))build_i; this->public.task.process = (status_t(*)(task_t*,message_t*))process_i; this->initiator = TRUE; - policy->get_ref(policy); + config->get_ref(config); } else { @@ -788,7 +787,7 @@ child_create_t *child_create_create(ike_sa_t *ike_sa, policy_t *policy) } this->ike_sa = ike_sa; - this->policy = policy; + this->config = config; this->my_nonce = chunk_empty; this->other_nonce = chunk_empty; this->proposals = NULL; diff --git a/src/charon/sa/tasks/child_create.h b/src/charon/sa/tasks/child_create.h index 200d37457..9f4815215 100644 --- a/src/charon/sa/tasks/child_create.h +++ b/src/charon/sa/tasks/child_create.h @@ -28,7 +28,7 @@ typedef struct child_create_t child_create_t; #include <library.h> #include <sa/ike_sa.h> #include <sa/tasks/task.h> -#include <config/policies/policy.h> +#include <config/child_cfg.h> /** * @brief Task of type CHILD_CREATE, established a new CHILD_SA. @@ -80,9 +80,9 @@ struct child_create_t { * @brief Create a new child_create task. * * @param ike_sa IKE_SA this task works for - * @param policy policy if task initiator, NULL if responder + * @param config child_cfg if task initiator, NULL if responder * @return child_create task to handle by the task_manager */ -child_create_t *child_create_create(ike_sa_t *ike_sa, policy_t *policy); +child_create_t *child_create_create(ike_sa_t *ike_sa, child_cfg_t *config); #endif /* CHILD_CREATE_H_ */ diff --git a/src/charon/sa/tasks/child_rekey.c b/src/charon/sa/tasks/child_rekey.c index 745895dbb..af0e4d3b5 100644 --- a/src/charon/sa/tasks/child_rekey.c +++ b/src/charon/sa/tasks/child_rekey.c @@ -27,7 +27,7 @@ #include <encoding/payloads/notify_payload.h> #include <sa/tasks/child_create.h> #include <sa/tasks/child_delete.h> -#include <queues/jobs/rekey_child_sa_job.h> +#include <processing/jobs/rekey_child_sa_job.h> typedef struct private_child_rekey_t private_child_rekey_t; @@ -315,8 +315,8 @@ static void destroy(private_child_rekey_t *this) */ child_rekey_t *child_rekey_create(ike_sa_t *ike_sa, child_sa_t *child_sa) { + child_cfg_t *config; private_child_rekey_t *this = malloc_thing(private_child_rekey_t); - policy_t *policy; this->public.collide = (void (*)(child_rekey_t*,task_t*))collide; this->public.task.get_type = (task_type_t(*)(task_t*))get_type; @@ -327,8 +327,8 @@ child_rekey_t *child_rekey_create(ike_sa_t *ike_sa, child_sa_t *child_sa) this->public.task.build = (status_t(*)(task_t*,message_t*))build_i; this->public.task.process = (status_t(*)(task_t*,message_t*))process_i; this->initiator = TRUE; - policy = child_sa->get_policy(child_sa); - this->child_create = child_create_create(ike_sa, policy); + config = child_sa->get_config(child_sa); + this->child_create = child_create_create(ike_sa, config); } else { diff --git a/src/charon/sa/tasks/ike_auth.c b/src/charon/sa/tasks/ike_auth.c index 541e1bb37..fa4b6a45e 100644 --- a/src/charon/sa/tasks/ike_auth.c +++ b/src/charon/sa/tasks/ike_auth.c @@ -100,18 +100,18 @@ static status_t build_auth(private_ike_auth_t *this, message_t *message) { authenticator_t *auth; auth_payload_t *auth_payload; - policy_t *policy; + peer_cfg_t *config; auth_method_t method; status_t status; /* create own authenticator and add auth payload */ - policy = this->ike_sa->get_policy(this->ike_sa); - if (!policy) + config = this->ike_sa->get_peer_cfg(this->ike_sa); + if (!config) { - SIG(IKE_UP_FAILED, "unable to authenticate, no policy found"); + SIG(IKE_UP_FAILED, "unable to authenticate, no peer config found"); return FAILED; } - method = policy->get_auth_method(policy); + method = config->get_auth_method(config); auth = authenticator_create(this->ike_sa, method); if (auth == NULL) @@ -140,15 +140,15 @@ static status_t build_id(private_ike_auth_t *this, message_t *message) { identification_t *me, *other; id_payload_t *id; - policy_t *policy; + peer_cfg_t *config; me = this->ike_sa->get_my_id(this->ike_sa); other = this->ike_sa->get_other_id(this->ike_sa); - policy = this->ike_sa->get_policy(this->ike_sa); + config = this->ike_sa->get_peer_cfg(this->ike_sa); if (me->contains_wildcards(me)) { - me = policy->get_my_id(policy); + me = config->get_my_id(config); if (me->contains_wildcards(me)) { SIG(IKE_UP_FAILED, "negotiation of own ID failed"); @@ -459,7 +459,7 @@ static status_t build_eap_r(private_ike_auth_t *this, message_t *message) */ static status_t build_i(private_ike_auth_t *this, message_t *message) { - policy_t *policy; + peer_cfg_t *config; if (message->get_exchange_type(message) == IKE_SA_INIT) { @@ -471,8 +471,8 @@ static status_t build_i(private_ike_auth_t *this, message_t *message) return FAILED; } - policy = this->ike_sa->get_policy(this->ike_sa); - if (policy->get_auth_method(policy) == AUTH_EAP) + config = this->ike_sa->get_peer_cfg(this->ike_sa); + if (config->get_auth_method(config) == AUTH_EAP) { this->eap_auth = eap_authenticator_create(this->ike_sa); } @@ -491,7 +491,9 @@ static status_t build_i(private_ike_auth_t *this, message_t *message) * Implementation of task_t.process for initiator */ static status_t process_r(private_ike_auth_t *this, message_t *message) -{ +{ + peer_cfg_t *config; + if (message->get_exchange_type(message) == IKE_SA_INIT) { return collect_other_init_data(this, message); @@ -502,6 +504,15 @@ static status_t process_r(private_ike_auth_t *this, message_t *message) return NEED_MORE; } + config = charon->cfg_store->get_peer_cfg(charon->cfg_store, + this->ike_sa->get_my_id(this->ike_sa), + this->ike_sa->get_other_id(this->ike_sa)); + if (config) + { + this->ike_sa->set_peer_cfg(this->ike_sa, config); + config->destroy(config); + } + switch (process_auth(this, message)) { case SUCCESS: @@ -522,7 +533,7 @@ static status_t process_r(private_ike_auth_t *this, message_t *message) */ static status_t build_r(private_ike_auth_t *this, message_t *message) { - policy_t *policy; + peer_cfg_t *config; eap_type_t eap_type; eap_payload_t *eap_payload; status_t status; @@ -532,10 +543,12 @@ static status_t build_r(private_ike_auth_t *this, message_t *message) return collect_my_init_data(this, message); } - policy = this->ike_sa->get_policy(this->ike_sa); - if (policy == NULL) + config = this->ike_sa->get_peer_cfg(this->ike_sa); + if (config == NULL) { - SIG(IKE_UP_FAILED, "no acceptable policy found"); + SIG(IKE_UP_FAILED, "no acceptable peer config found for %D...%D", + this->ike_sa->get_my_id(this->ike_sa), + this->ike_sa->get_other_id(this->ike_sa)); message->add_notify(message, TRUE, AUTHENTICATION_FAILED, chunk_empty); return FAILED; } @@ -567,7 +580,7 @@ static status_t build_r(private_ike_auth_t *this, message_t *message) } /* initiate EAP authenitcation */ - eap_type = policy->get_eap_type(policy); + eap_type = config->get_eap_type(config); status = this->eap_auth->initiate(this->eap_auth, eap_type, &eap_payload); message->add_payload(message, (payload_t*)eap_payload); if (status != NEED_MORE) diff --git a/src/charon/sa/tasks/ike_cert.c b/src/charon/sa/tasks/ike_cert.c index 160600742..ff1143e50 100644 --- a/src/charon/sa/tasks/ike_cert.c +++ b/src/charon/sa/tasks/ike_cert.c @@ -171,20 +171,20 @@ static void process_certs(private_ike_cert_t *this, message_t *message) */ static void build_certreqs(private_ike_cert_t *this, message_t *message) { - connection_t *connection; - policy_t *policy; + ike_cfg_t *ike_cfg; + peer_cfg_t *peer_cfg; identification_t *ca; certreq_payload_t *certreq; - connection = this->ike_sa->get_connection(this->ike_sa); + ike_cfg = this->ike_sa->get_ike_cfg(this->ike_sa); - if (connection->get_certreq_policy(connection) != CERT_NEVER_SEND) + if (ike_cfg->send_certreq(ike_cfg) != CERT_NEVER_SEND) { - policy = this->ike_sa->get_policy(this->ike_sa); + peer_cfg = this->ike_sa->get_peer_cfg(this->ike_sa); - if (policy) + if (peer_cfg) { - ca = policy->get_other_ca(policy); + ca = peer_cfg->get_other_ca(peer_cfg); if (ca && ca->get_type(ca) != ID_ANY) { @@ -212,17 +212,15 @@ static void build_certreqs(private_ike_cert_t *this, message_t *message) */ static void build_certs(private_ike_cert_t *this, message_t *message) { - policy_t *policy; - connection_t *connection; + peer_cfg_t *peer_cfg; x509_t *cert; cert_payload_t *payload; - policy = this->ike_sa->get_policy(this->ike_sa); - connection = this->ike_sa->get_connection(this->ike_sa); + peer_cfg = this->ike_sa->get_peer_cfg(this->ike_sa); - if (policy && policy->get_auth_method(policy) == AUTH_RSA) + if (peer_cfg && peer_cfg->get_auth_method(peer_cfg) == AUTH_RSA) { - switch (connection->get_cert_policy(connection)) + switch (peer_cfg->get_cert_policy(peer_cfg)) { case CERT_NEVER_SEND: break; @@ -236,7 +234,7 @@ static void build_certs(private_ike_cert_t *this, message_t *message) { /* TODO: respect CA cert request */ cert = charon->credentials->get_certificate(charon->credentials, - policy->get_my_id(policy)); + peer_cfg->get_my_id(peer_cfg)); if (cert) { payload = cert_payload_create_from_x509(cert); diff --git a/src/charon/sa/tasks/ike_config.c b/src/charon/sa/tasks/ike_config.c index ce29b9220..0fc35013b 100644 --- a/src/charon/sa/tasks/ike_config.c +++ b/src/charon/sa/tasks/ike_config.c @@ -49,11 +49,6 @@ struct private_ike_config_t { bool initiator; /** - * associated policy with virtual IP configuration - */ - policy_t *policy; - - /** * virtual ip */ host_t *virtual_ip; @@ -266,7 +261,8 @@ static status_t build_i(private_ike_config_t *this, message_t *message) if (message->get_exchange_type(message) == IKE_AUTH && message->get_payload(message, ID_INITIATOR)) { - this->virtual_ip = this->policy->get_virtual_ip(this->policy, NULL); + peer_cfg_t *config = this->ike_sa->get_peer_cfg(this->ike_sa); + this->virtual_ip = config->get_virtual_ip(config, NULL); build_payloads(this, message, CFG_REQUEST); } @@ -295,14 +291,14 @@ static status_t build_r(private_ike_config_t *this, message_t *message) if (message->get_exchange_type(message) == IKE_AUTH && message->get_payload(message, EXTENSIBLE_AUTHENTICATION) == NULL) { - this->policy = this->ike_sa->get_policy(this->ike_sa); + peer_cfg_t *config = this->ike_sa->get_peer_cfg(this->ike_sa); - if (this->policy && this->virtual_ip) + if (config && this->virtual_ip) { host_t *ip; DBG1(DBG_IKE, "peer requested virtual IP %H", this->virtual_ip); - ip = this->policy->get_virtual_ip(this->policy, this->virtual_ip); + ip = config->get_virtual_ip(config, this->virtual_ip); if (ip == NULL || ip->is_anyaddr(ip)) { DBG1(DBG_IKE, "not assigning a virtual IP to peer"); @@ -398,7 +394,7 @@ static void destroy(private_ike_config_t *this) /* * Described in header. */ -ike_config_t *ike_config_create(ike_sa_t *ike_sa, policy_t *policy) +ike_config_t *ike_config_create(ike_sa_t *ike_sa, bool initiator) { private_ike_config_t *this = malloc_thing(private_ike_config_t); @@ -406,21 +402,18 @@ ike_config_t *ike_config_create(ike_sa_t *ike_sa, policy_t *policy) this->public.task.migrate = (void(*)(task_t*,ike_sa_t*))migrate; this->public.task.destroy = (void(*)(task_t*))destroy; - if (policy) + if (initiator) { this->public.task.build = (status_t(*)(task_t*,message_t*))build_i; this->public.task.process = (status_t(*)(task_t*,message_t*))process_i; - this->initiator = TRUE; } else { this->public.task.build = (status_t(*)(task_t*,message_t*))build_r; this->public.task.process = (status_t(*)(task_t*,message_t*))process_r; - this->initiator = FALSE; } - + this->initiator = initiator; this->ike_sa = ike_sa; - this->policy = policy; this->virtual_ip = NULL; this->dns = linked_list_create(); diff --git a/src/charon/sa/tasks/ike_config.h b/src/charon/sa/tasks/ike_config.h index 0c9b961b4..a7cfddff0 100644 --- a/src/charon/sa/tasks/ike_config.h +++ b/src/charon/sa/tasks/ike_config.h @@ -28,7 +28,6 @@ typedef struct ike_config_t ike_config_t; #include <library.h> #include <sa/ike_sa.h> #include <sa/tasks/task.h> -#include <config/policies/policy.h> /** * @brief Task of type IKE_CONFIG, sets up a virtual IP and other @@ -51,9 +50,9 @@ struct ike_config_t { * @brief Create a new ike_config task. * * @param ike_sa IKE_SA this task works for - * @param policy policy for the initiator, NULL for the responder + * @param initiator TRUE for initiator * @return ike_config task to handle by the task_manager */ -ike_config_t *ike_config_create(ike_sa_t *ike_sa, policy_t *policy); +ike_config_t *ike_config_create(ike_sa_t *ike_sa, bool initiator); #endif /* IKE_CONFIG_H_ */ diff --git a/src/charon/sa/tasks/ike_delete.c b/src/charon/sa/tasks/ike_delete.c index 9c4fdac0e..68fdb7bd9 100644 --- a/src/charon/sa/tasks/ike_delete.c +++ b/src/charon/sa/tasks/ike_delete.c @@ -28,7 +28,7 @@ typedef struct private_ike_delete_t private_ike_delete_t; -/** +/**file * Private members of a ike_delete_t task. */ struct private_ike_delete_t { diff --git a/src/charon/sa/tasks/ike_init.c b/src/charon/sa/tasks/ike_init.c index 0b493666a..8165a01a2 100644 --- a/src/charon/sa/tasks/ike_init.c +++ b/src/charon/sa/tasks/ike_init.c @@ -57,9 +57,9 @@ struct private_ike_init_t { bool initiator; /** - * Connection established by this IKE_SA + * IKE config to establish */ - connection_t *connection; + ike_cfg_t *config; /** * diffie hellman group to use @@ -117,11 +117,11 @@ static void build_payloads(private_ike_init_t *this, message_t *message) id = this->ike_sa->get_id(this->ike_sa); - this->connection = this->ike_sa->get_connection(this->ike_sa); + this->config = this->ike_sa->get_ike_cfg(this->ike_sa); if (this->initiator) { - proposal_list = this->connection->get_proposals(this->connection); + proposal_list = this->config->get_proposals(this->config); if (this->old_sa) { /* include SPI of new IKE_SA when we are rekeying */ @@ -174,8 +174,8 @@ static void process_payloads(private_ike_init_t *this, message_t *message) linked_list_t *proposal_list; proposal_list = sa_payload->get_proposals(sa_payload); - this->proposal = this->connection->select_proposal( - this->connection, proposal_list); + this->proposal = this->config->select_proposal(this->config, + proposal_list); proposal_list->destroy_offset(proposal_list, offsetof(proposal_t, destroy)); break; @@ -200,8 +200,7 @@ static void process_payloads(private_ike_init_t *this, message_t *message) else { this->dh_group = dh_group; - if (!this->connection->check_dh_group(this->connection, - dh_group)) + if (!this->config->check_dh_group(this->config, dh_group)) { break; } @@ -235,9 +234,9 @@ static status_t build_i(private_ike_init_t *this, message_t *message) randomizer_t *randomizer; status_t status; - this->connection = this->ike_sa->get_connection(this->ike_sa); + this->config = this->ike_sa->get_ike_cfg(this->ike_sa); SIG(IKE_UP_START, "initiating IKE_SA to %H", - this->connection->get_other_host(this->connection)); + this->config->get_other_host(this->config)); this->ike_sa->set_state(this->ike_sa, IKE_CONNECTING); if (this->retry++ >= MAX_RETRIES) @@ -249,7 +248,7 @@ static status_t build_i(private_ike_init_t *this, message_t *message) /* if the DH group is set via use_dh_group(), we already have a DH object */ if (!this->diffie_hellman) { - this->dh_group = this->connection->get_dh_group(this->connection); + this->dh_group = this->config->get_dh_group(this->config); this->diffie_hellman = diffie_hellman_create(this->dh_group); if (this->diffie_hellman == NULL) { @@ -291,7 +290,7 @@ static status_t process_r(private_ike_init_t *this, message_t *message) { randomizer_t *randomizer; - this->connection = this->ike_sa->get_connection(this->ike_sa); + this->config = this->ike_sa->get_ike_cfg(this->ike_sa); SIG(IKE_UP_FAILED, "%H is initiating an IKE_SA", message->get_source(message)); this->ike_sa->set_state(this->ike_sa, IKE_CONNECTING); @@ -335,7 +334,7 @@ static status_t build_r(private_ike_init_t *this, message_t *message) SIG(IKE_UP_FAILED, "received inacceptable DH group (%N)", diffie_hellman_group_names, this->dh_group); - this->dh_group = this->connection->get_dh_group(this->connection); + this->dh_group = this->config->get_dh_group(this->config); dh_enc = htons(this->dh_group); chunk.ptr = (u_int8_t*)&dh_enc; chunk.len = sizeof(dh_enc); @@ -414,8 +413,7 @@ static status_t process_i(private_ike_init_t *this, message_t *message) DBG1(DBG_IKE, "peer didn't accept DH group %N, it requested" " %N", diffie_hellman_group_names, old_dh_group, diffie_hellman_group_names, this->dh_group); - if (!this->connection->check_dh_group(this->connection, - this->dh_group)) + if (!this->config->check_dh_group(this->config, this->dh_group)) { DBG1(DBG_IKE, "requested DH group %N not acceptable, " "giving up", diffie_hellman_group_names, @@ -590,7 +588,7 @@ ike_init_t *ike_init_create(ike_sa_t *ike_sa, bool initiator, ike_sa_t *old_sa) this->other_nonce = chunk_empty; this->cookie = chunk_empty; this->proposal = NULL; - this->connection = NULL; + this->config = NULL; this->old_sa = old_sa; this->retry = 0; diff --git a/src/charon/sa/tasks/ike_rekey.c b/src/charon/sa/tasks/ike_rekey.c index a33e7ee34..04dd229ea 100644 --- a/src/charon/sa/tasks/ike_rekey.c +++ b/src/charon/sa/tasks/ike_rekey.c @@ -26,8 +26,8 @@ #include <daemon.h> #include <encoding/payloads/notify_payload.h> #include <sa/tasks/ike_init.h> -#include <queues/jobs/delete_ike_sa_job.h> -#include <queues/jobs/rekey_ike_sa_job.h> +#include <processing/jobs/delete_ike_sa_job.h> +#include <processing/jobs/rekey_ike_sa_job.h> typedef struct private_ike_rekey_t private_ike_rekey_t; @@ -73,20 +73,15 @@ struct private_ike_rekey_t { */ static status_t build_i(private_ike_rekey_t *this, message_t *message) { - connection_t *connection; - policy_t *policy; + peer_cfg_t *peer_cfg; this->new_sa = charon->ike_sa_manager->checkout_new(charon->ike_sa_manager, TRUE); - connection = this->ike_sa->get_connection(this->ike_sa); - policy = this->ike_sa->get_policy(this->ike_sa); - this->new_sa->set_connection(this->new_sa, connection); - this->new_sa->set_policy(this->new_sa, policy); - + peer_cfg = this->ike_sa->get_peer_cfg(this->ike_sa); + this->new_sa->set_peer_cfg(this->new_sa, peer_cfg); this->ike_init = ike_init_create(this->new_sa, TRUE, this->ike_sa); this->ike_init->task.build(&this->ike_init->task, message); - this->ike_sa->set_state(this->ike_sa, IKE_REKEYING); return NEED_MORE; @@ -97,8 +92,7 @@ static status_t build_i(private_ike_rekey_t *this, message_t *message) */ static status_t process_r(private_ike_rekey_t *this, message_t *message) { - connection_t *connection; - policy_t *policy; + peer_cfg_t *peer_cfg; iterator_t *iterator; child_sa_t *child_sa; @@ -129,11 +123,8 @@ static status_t process_r(private_ike_rekey_t *this, message_t *message) this->new_sa = charon->ike_sa_manager->checkout_new(charon->ike_sa_manager, FALSE); - connection = this->ike_sa->get_connection(this->ike_sa); - policy = this->ike_sa->get_policy(this->ike_sa); - this->new_sa->set_connection(this->new_sa, connection); - this->new_sa->set_policy(this->new_sa, policy); - + peer_cfg = this->ike_sa->get_peer_cfg(this->ike_sa); + this->new_sa->set_peer_cfg(this->new_sa, peer_cfg); this->ike_init = ike_init_create(this->new_sa, FALSE, this->ike_sa); this->ike_init->task.process(&this->ike_init->task, message); |