From 64807652223f27de23e7173e3fa6ca7eb2ff9351 Mon Sep 17 00:00:00 2001
From: iphydf <iphydf@users.noreply.github.com>
Date: Sun, 8 Jan 2017 15:18:36 +0000
Subject: Clarify that the pass key `new` function can fail.

Also clarify that passwords can be empty or NULL.
---
 toxencryptsave/toxencryptsave.api.h | 11 +++++++----
 toxencryptsave/toxencryptsave.h     | 11 +++++++----
 2 files changed, 14 insertions(+), 8 deletions(-)

(limited to 'toxencryptsave')

diff --git a/toxencryptsave/toxencryptsave.api.h b/toxencryptsave/toxencryptsave.api.h
index b0e29b50..0356d756 100644
--- a/toxencryptsave/toxencryptsave.api.h
+++ b/toxencryptsave/toxencryptsave.api.h
@@ -146,7 +146,7 @@ error for decryption {
  *
  * @param plaintext A byte array of length `plaintext_len`.
  * @param plaintext_len The length of the plain text array. Bigger than 0.
- * @param passphrase The user-provided password.
+ * @param passphrase The user-provided password. Can be empty.
  * @param passphrase_len The length of the password.
  * @param ciphertext The cipher text array to write the encrypted data to.
  *
@@ -164,7 +164,7 @@ static bool pass_encrypt(const uint8_t[plaintext_len] plaintext, const uint8_t[p
  *
  * @param ciphertext A byte array of length `ciphertext_len`.
  * @param ciphertext_len The length of the cipher text array. At least $PASS_ENCRYPTION_EXTRA_LENGTH.
- * @param passphrase The user-provided password.
+ * @param passphrase The user-provided password. Can be empty.
  * @param passphrase_len The length of the password.
  * @param plaintext The plain text array to write the decrypted data to.
  *
@@ -200,6 +200,9 @@ class pass_Key {
   /**
    * Create a new $this. The initial value of it is indeterminate. To
    * initialise it, use one of the derive_* functions below.
+   *
+   * In case of failure, this function returns NULL. The only failure mode at
+   * this time is memory allocation failure, so this function has no error code.
    */
   static this new();
 
@@ -219,7 +222,7 @@ class pass_Key {
    * a password, you also must know the random salt that was used. A
    * deterministic version of this function is $derive_with_salt.
    *
-   * @param passphrase The user-provided password.
+   * @param passphrase The user-provided password. Can be empty.
    * @param passphrase_len The length of the password.
    *
    * @return true on success.
@@ -230,7 +233,7 @@ class pass_Key {
   /**
    * Same as above, except use the given salt for deterministic key derivation.
    *
-   * @param passphrase The user-provided password.
+   * @param passphrase The user-provided password. Can be empty.
    * @param passphrase_len The length of the password.
    * @param salt An array of at least $PASS_SALT_LENGTH bytes.
    *
diff --git a/toxencryptsave/toxencryptsave.h b/toxencryptsave/toxencryptsave.h
index d03383e9..13641273 100644
--- a/toxencryptsave/toxencryptsave.h
+++ b/toxencryptsave/toxencryptsave.h
@@ -195,7 +195,7 @@ typedef enum TOX_ERR_DECRYPTION {
  *
  * @param plaintext A byte array of length `plaintext_len`.
  * @param plaintext_len The length of the plain text array. Bigger than 0.
- * @param passphrase The user-provided password.
+ * @param passphrase The user-provided password. Can be empty.
  * @param passphrase_len The length of the password.
  * @param ciphertext The cipher text array to write the encrypted data to.
  *
@@ -212,7 +212,7 @@ bool tox_pass_encrypt(const uint8_t *plaintext, size_t plaintext_len, const uint
  *
  * @param ciphertext A byte array of length `ciphertext_len`.
  * @param ciphertext_len The length of the cipher text array. At least TOX_PASS_ENCRYPTION_EXTRA_LENGTH.
- * @param passphrase The user-provided password.
+ * @param passphrase The user-provided password. Can be empty.
  * @param passphrase_len The length of the password.
  * @param plaintext The plain text array to write the decrypted data to.
  *
@@ -252,6 +252,9 @@ typedef struct Tox_Pass_Key Tox_Pass_Key;
 /**
  * Create a new Tox_Pass_Key. The initial value of it is indeterminate. To
  * initialise it, use one of the derive_* functions below.
+ *
+ * In case of failure, this function returns NULL. The only failure mode at
+ * this time is memory allocation failure, so this function has no error code.
  */
 struct Tox_Pass_Key *tox_pass_key_new(void);
 
@@ -271,7 +274,7 @@ void tox_pass_key_free(struct Tox_Pass_Key *_key);
  * a password, you also must know the random salt that was used. A
  * deterministic version of this function is tox_pass_key_derive_with_salt.
  *
- * @param passphrase The user-provided password.
+ * @param passphrase The user-provided password. Can be empty.
  * @param passphrase_len The length of the password.
  *
  * @return true on success.
@@ -282,7 +285,7 @@ bool tox_pass_key_derive(struct Tox_Pass_Key *_key, const uint8_t *passphrase, s
 /**
  * Same as above, except use the given salt for deterministic key derivation.
  *
- * @param passphrase The user-provided password.
+ * @param passphrase The user-provided password. Can be empty.
  * @param passphrase_len The length of the password.
  * @param salt An array of at least TOX_PASS_SALT_LENGTH bytes.
  *
-- 
cgit v1.2.3