From e3b3d19e5a39c36f49c2eeb7bfee3d1db22254fb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= <mpg@elzevir.fr>
Date: Thu, 13 Mar 2014 19:21:49 +0100
Subject: [PATCH] Improve doc of pk_parse_* functions

---
 include/polarssl/pk.h | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/include/polarssl/pk.h b/include/polarssl/pk.h
index 013d9736a..6f21dab52 100644
--- a/include/polarssl/pk.h
+++ b/include/polarssl/pk.h
@@ -400,6 +400,12 @@ pk_type_t pk_get_type( const pk_context *ctx );
  * \param pwd       password for decryption (optional)
  * \param pwdlen    size of the password
  *
+ * \note            On entry, ctx must be empty, either freshly initialised
+ *                  with pk_init() or reset with pk_free(). If you need a
+ *                  specific key type, check the result with pk_can_do().
+ *
+ * \note            The key is also checked for correctness.
+ *
  * \return          0 if successful, or a specific PK or PEM error code
  */
 int pk_parse_key( pk_context *ctx,
@@ -414,6 +420,12 @@ int pk_parse_key( pk_context *ctx,
  * \param key       input buffer
  * \param keylen    size of the buffer
  *
+ * \note            On entry, ctx must be empty, either freshly initialised
+ *                  with pk_init() or reset with pk_free(). If you need a
+ *                  specific key type, check the result with pk_can_do().
+ *
+ * \note            The key is also checked for correctness.
+ *
  * \return          0 if successful, or a specific PK or PEM error code
  */
 int pk_parse_public_key( pk_context *ctx,
@@ -428,6 +440,12 @@ int pk_parse_public_key( pk_context *ctx,
  * \param path      filename to read the private key from
  * \param password  password to decrypt the file (can be NULL)
  *
+ * \note            On entry, ctx must be empty, either freshly initialised
+ *                  with pk_init() or reset with pk_free(). If you need a
+ *                  specific key type, check the result with pk_can_do().
+ *
+ * \note            The key is also checked for correctness.
+ *
  * \return          0 if successful, or a specific PK or PEM error code
  */
 int pk_parse_keyfile( pk_context *ctx,
@@ -440,6 +458,12 @@ int pk_parse_keyfile( pk_context *ctx,
  * \param ctx       key to be initialized
  * \param path      filename to read the private key from
  *
+ * \note            On entry, ctx must be empty, either freshly initialised
+ *                  with pk_init() or reset with pk_free(). If you need a
+ *                  specific key type, check the result with pk_can_do().
+ *
+ * \note            The key is also checked for correctness.
+ *
  * \return          0 if successful, or a specific PK or PEM error code
  */
 int pk_parse_public_keyfile( pk_context *ctx, const char *path );