diff options
Diffstat (limited to 'librecrypt.h')
| -rw-r--r-- | librecrypt.h | 64 |
1 files changed, 39 insertions, 25 deletions
diff --git a/librecrypt.h b/librecrypt.h index 48d2ff7..ee94c40 100644 --- a/librecrypt.h +++ b/librecrypt.h @@ -81,6 +81,7 @@ * return `strlen(hash)` if `hash` is properly * formatted) the value 0 is stored, indicating * that a default hash size shall be used + * @param reserved Reserved for future use, should be `NULL` * @return The number of bytes, from the front of `hash`, * that make up the algorithm configuration; may be 0 * @@ -92,7 +93,7 @@ * @since 1.0 */ LIBRECRYPT_READ_STR__(1) LIBRECRYPT_NONNULL_1__ LIBRECRYPT_WUR__ LIBRECRYPT_PURE__ -size_t librecrypt_settings_prefix(const char *hash, size_t *hashsize_out); +size_t librecrypt_settings_prefix(const char *hash, size_t *hashsize_out, void *reserved); /** @@ -359,6 +360,7 @@ ssize_t librecrypt_decode(void *out_buffer, size_t size, const char *ascii, size * @param decoding 0 if the returned pointer should be useful for, * `librecrypt_encode`, otherwise it will be useful * for `librecrypt_decode` + * @param reserved Reserved for future use, should be `NULL` * @return If `decoding` is 0: * the encoding alphabet, consisting of 64 characters, * repeated 4 times; @@ -369,6 +371,8 @@ ssize_t librecrypt_decode(void *out_buffer, size_t size, const char *ascii, size * and any other character to the value `0xFF`; * but `NULL` on failure * + * @throws EINVAL `reserved` is non-`NULL` (this case will be removed + * once `reserved` as being used by the library) * @throws ENOSYS The last algorithm in `settings` is not recognised * or was disabled at compile-time * @@ -390,9 +394,10 @@ ssize_t librecrypt_decode(void *out_buffer, size_t size, const char *ascii, size * * @since 1.0 */ -LIBRECRYPT_READ_STR__(1) LIBRECRYPT_NONNULL__ LIBRECRYPT_WUR__ +LIBRECRYPT_READ_STR__(1) LIBRECRYPT_NONNULL_I__(1) LIBRECRYPT_NONNULL_I__(3) +LIBRECRYPT_NONNULL_I__(4) LIBRECRYPT_WUR__ const void *librecrypt_get_encoding(const char *settings, size_t len, char *pad_out, - int *strict_pad_out, int decoding); + int *strict_pad_out, int decoding, void *reserved); /** @@ -493,8 +498,11 @@ librecrypt_equal(const char *a, const char *b) * the number of generated bytes, or -1 on failure * @param user Passed as the third argument to `*rng` for user-defined * purposes, ignored if `rng` is `NULL` + * @param reserved Reserved for future use, should be `NULL` * @return The number of bytes that would have been written to `out_buffer`, * if `size` was sufficiently large, -1 on failure + * @throws EINVAL `reserved` is non-`NULL` (this case will be removed + * once `reserved` as being used by the library) * @throws ERANGE The expected return value is greater than {SSIZE_MAX} * @throws ENOSYS `settings` contain an algorithm that is not recognised * or was disabled at compile-time @@ -531,7 +539,8 @@ librecrypt_equal(const char *a, const char *b) */ LIBRECRYPT_WRITE_MEM__(1, 2) LIBRECRYPT_READ_STR__(3) LIBRECRYPT_WUR__ ssize_t librecrypt_realise_salts(char *restrict out_buffer, size_t size, const char *settings, - ssize_t (*rng)(void *out, size_t n, void *user), void *user); + ssize_t (*rng)(void *out, size_t n, void *user), void *user, + void *reserved); /** @@ -563,9 +572,12 @@ ssize_t librecrypt_realise_salts(char *restrict out_buffer, size_t size, const c * ignored if `gensalt` is zero * @param user Passed as the third argument to `*rng` for user-defined * purposes, ignored if `rng` is `NULL` or if `gensalt` is zero + * @param reserved Reserved for future use, should be `NULL` * @return The number of bytes that would have been written to * `out_buffer`, if `size` was sufficiently large, -1 on failure * + * @throws EINVAL `reserved` is non-`NULL` (this case will be removed + * once `reserved` as being used by the library) * @throws EINVAL `algorithm` represents a chain of algorithms * @throws ENOSYS `algorithm` represents an algorithm that is not * recognised or was disabled at compile-time @@ -599,7 +611,8 @@ ssize_t librecrypt_realise_salts(char *restrict out_buffer, size_t size, const c LIBRECRYPT_WRITE_MEM__(1, 2) LIBRECRYPT_READ_STR__(3) LIBRECRYPT_WUR__ ssize_t librecrypt_make_settings(char *out_buffer, size_t size, const char *algorithm, size_t memcost, uintmax_t timecost, int gensalt, - ssize_t (*rng)(void *out, size_t n, void *user), void *user); + ssize_t (*rng)(void *out, size_t n, void *user), void *user, + void *reserved); /** @@ -773,30 +786,31 @@ ssize_t librecrypt_crypt(char *restrict out_buffer, size_t size, const char *phr * for the given input, and that each algorithm * configuration is valid * - * @param phrase The password to hash, may contain NUL bytes; - * may be `NULL` even if `len` is non-zero - * @param len The number of bytes in `phrase`, if `phrase` is `NULL`, - * the function will check that the specified number of - * bytes is supported as well as any byte sequence unless - * `text` is non-zero - * @param text Assume the password is valid UTF-8 text (without NUL bytes) - * iff non-zero; ignored if `phrase` is non-`NULL` - * @param settings The password hash string; it is allowed for algorithm - * tuning parameters, and the hash result, to be omitted - * @return 1 if the configuration is supported, 0 otherwise, which - * means part of the string is invalid: the algorithm does - * not exist, supported was disabled at compile-time, or an - * algorithm it does not support the output of the previous - * algorithm in the chain as input; additionally a small - * number of legacy algorithms require the passphrase to - * be within a specific length range or be valid text, - * if the selected word does not match such constraints - * for the first algorithm in the chain, 0 is returned + * @param phrase The password to hash, may contain NUL bytes; + * may be `NULL` even if `len` is non-zero + * @param len The number of bytes in `phrase`, if `phrase` is `NULL`, + * the function will check that the specified number of + * bytes is supported as well as any byte sequence unless + * `text` is non-zero + * @param text Assume the password is valid UTF-8 text (without NUL bytes) + * iff non-zero; ignored if `phrase` is non-`NULL` + * @param settings The password hash string; it is allowed for algorithm + * tuning parameters, and the hash result, to be omitted + * @param reserved Reserved for future use, should be `NULL` + * @return 1 if the configuration is supported, 0 otherwise, which + * means part of the string is invalid: the algorithm does + * not exist, supported was disabled at compile-time, or an + * algorithm it does not support the output of the previous + * algorithm in the chain as input; additionally a small + * number of legacy algorithms require the passphrase to + * be within a specific length range or be valid text, + * if the selected word does not match such constraints + * for the first algorithm in the chain, 0 is returned * * This function is MT-Safe and AS-Safe */ LIBRECRYPT_READ_STR__(4) LIBRECRYPT_NONNULL_I__(4) LIBRECRYPT_WUR__ -int librecrypt_test_supported(const char *phrase, size_t len, int text, const char *settings); +int librecrypt_test_supported(const char *phrase, size_t len, int text, const char *settings, void *reserved); /** |