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 f2fc4cd6cb1ddf646cd03c5f8ae0e7be6e3ff225..6a9cdba62dc1b0098bacf00cc8ee1c183bc3c530 100644 (file)
--- 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);