From: Tobias Brunner Date: Mon, 4 Nov 2019 14:19:16 +0000 (+0100) Subject: proposal: Fix typos and clarify things in comments X-Git-Tag: 5.8.2dr2~13 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=07083788e5b10a62c91099864d158b3fd3dd0ac9;p=thirdparty%2Fstrongswan.git proposal: Fix typos and clarify things in comments --- diff --git a/src/libstrongswan/crypto/proposal/proposal.h b/src/libstrongswan/crypto/proposal/proposal.h index f2fc4cd6cb..6a9cdba62d 100644 --- a/src/libstrongswan/crypto/proposal/proposal.h +++ b/src/libstrongswan/crypto/proposal/proposal.h @@ -1,5 +1,5 @@ /* - * Copyright (C) 2009-2018 Tobias Brunner + * Copyright (C) 2009-2019 Tobias Brunner * Copyright (C) 2006 Martin Willi * HSR Hochschule fuer Technik Rapperswil * @@ -53,7 +53,7 @@ enum protocol_id_t { extern enum_name_t *protocol_id_names; /** - * Flags for selecting proposals + * Flags for selecting proposals. */ enum proposal_selection_flag_t { /** Whether to prefer configured (default) or supplied proposals. */ @@ -67,24 +67,18 @@ enum proposal_selection_flag_t { /** * Stores a set of algorithms used for an SA. * - * A proposal stores algorithms for a specific - * protocol. It can store algorithms for one protocol. - * Proposals with multiple protocols are not supported, - * as it's not specified in RFC4301 anymore. + * A proposal stores algorithms for a specific protocol. + * Proposals with multiple protocols are not supported, as that's not specified + * in RFC 7296 anymore. */ struct proposal_t { /** * Add an algorithm to the proposal. * - * The algorithms are stored by priority, first added - * is the most preferred. - * Key size is only needed for encryption algorithms - * with variable key size (such as AES). Must be set - * to zero if key size is not specified. - * The alg parameter accepts encryption_algorithm_t, - * integrity_algorithm_t, dh_group_number_t and - * extended_sequence_numbers_t. + * The algorithms are stored by priority, first added is the most preferred. + * Key size is only needed for encryption algorithms with variable key + * size (such as AES). Must be set to zero if the key size is not specified. * * @param type kind of algorithm * @param alg identifier for algorithm @@ -94,7 +88,7 @@ struct proposal_t { uint16_t alg, uint16_t key_size); /** - * Get an enumerator over algorithms for a specific algo type. + * Get an enumerator over algorithms for a specific transform type. * * @param type kind of algorithm * @return enumerator over uint16_t alg, uint16_t key_size @@ -132,7 +126,7 @@ struct proposal_t { bool (*promote_dh_group)(proposal_t *this, diffie_hellman_group_t group); /** - * Compare two proposal, and select a matching subset. + * Compare two proposals and select a matching subset. * * If the proposals are for the same protocols (AH/ESP), they are * compared. If they have at least one algorithm of each type @@ -171,29 +165,29 @@ struct proposal_t { /** * Get the SPI of the proposal. * - * @return spi for proto + * @return SPI of the proposal */ uint64_t (*get_spi) (proposal_t *this); /** * Set the SPI of the proposal. * - * @param spi spi to set for proto + * @param spi SPI to set for proposal */ void (*set_spi) (proposal_t *this, uint64_t spi); /** - * Get the proposal number, as encoded in SA payload + * Get the proposal number, as encoded in the SA payload. * * @return proposal number */ u_int (*get_number)(proposal_t *this); /** - * Check for the eqality of two proposals. + * Check for the equality of two proposals. * * @param other other proposal to check for equality - * @return TRUE if other equal to this + * @return TRUE if proposals are equal */ bool (*equals)(proposal_t *this, proposal_t *other); @@ -212,7 +206,7 @@ struct proposal_t { }; /** - * Create a child proposal for AH, ESP or IKE. + * Create a proposal for IKE, ESP or AH. * * @param protocol protocol, such as PROTO_ESP * @param number proposal number, as encoded in SA payload @@ -221,7 +215,7 @@ struct proposal_t { proposal_t *proposal_create(protocol_id_t protocol, u_int number); /** - * Create a default proposal if nothing further specified. + * Create a default proposal. * * @param protocol protocol, such as PROTO_ESP * @return proposal_t object @@ -229,7 +223,7 @@ proposal_t *proposal_create(protocol_id_t protocol, u_int number); proposal_t *proposal_create_default(protocol_id_t protocol); /** - * Create a default proposal for supported AEAD algorithms + * Create a default proposal for supported AEAD algorithms. * * @param protocol protocol, such as PROTO_ESP * @return proposal_t object, NULL if none supported @@ -239,15 +233,21 @@ proposal_t *proposal_create_default_aead(protocol_id_t protocol); /** * Create a proposal from a string identifying the algorithms. * - * The string is in the same form as a in the ipsec.conf file. - * E.g.: aes128-sha2_256-modp2048 - * 3des-md5 - * An additional '!' at the end of the string forces this proposal, - * without it the peer may choose another algorithm we support. + * Each algorithm identifier is separated with a '-' character e.g. + * aes256-sha2-curve25519. Multiple algorithms of the same transform type can be + * given (they don't have to be grouped together), the order is preserved e.g. + * curve25519-sha2-aes256-sha1-modp3072-aes128 is the same as + * aes256-aes128-sha2-sha1-curve25519-modp3072. + * + * The proposal is validated (e.g. PROTO_IKE proposals must contain a key + * exchange method, AEAD algorithms can't be combined with classic encryption + * algorithms etc.) and in some cases modified (e.g. by adding missing PRFs for + * PROTO_IKE, or by adding noesn in PROTO_ESP/AH proposals if neither esn, nor + * noesn is contained in the string etc.). * * @param protocol protocol, such as PROTO_ESP * @param algs algorithms as string - * @return proposal_t object + * @return proposal_t object, NULL if invalid */ proposal_t *proposal_create_from_string(protocol_id_t protocol, const char *algs); @@ -267,9 +267,9 @@ proposal_t *proposal_select(linked_list_t *configured, linked_list_t *supplied, * printf hook function for proposal_t. * * Arguments are: - * proposal_t *proposal + * proposal_t* * With the #-specifier, arguments are: - * linked_list_t *list containing proposal_t* + * linked_list_t* (containing proposal_t*) */ int proposal_printf_hook(printf_hook_data_t *data, printf_hook_spec_t *spec, const void *const *args);