proposal: Fix typos and clarify things in comments

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);