Mention that password verification is not fully possible
This is due to limitations in the zip file format.
Closes #209.
diff --git a/man/zip_fopen_encrypted.mdoc b/man/zip_fopen_encrypted.mdoc
index fb159ce..58319e1 100644
--- a/man/zip_fopen_encrypted.mdoc
+++ b/man/zip_fopen_encrypted.mdoc
@@ -29,7 +29,7 @@
.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
-.Dd December 18, 2017
+.Dd September 14, 2020
.Dt ZIP_FOPEN_ENCRYPTED 3
.Os
.Sh NAME
@@ -115,3 +115,15 @@
.An Dieter Baron Aq Mt dillo@nih.at
and
.An Thomas Klausner Aq Mt tk@giga.or.at
+.Sh CAVEATS
+The zip file format provides very limited possibility for password
+verification (a short hash of is compared against one byte in the zip
+archive).
+For this reason, reading a file while using an incorrect password may
+immediately fail with
+.Er ZIP_ER_WRONGPASSWD ,
+but if the mismatch is not detected, a zlib error may be returned
+later instead.
+Since zlib errors can also be caused by broken compressed data, there
+is no way to make sure if the password was incorrect or if it was
+correct, but the compressed data was invalid.
diff --git a/man/zip_set_default_password.mdoc b/man/zip_set_default_password.mdoc
index 792176c..79fb0ca 100644
--- a/man/zip_set_default_password.mdoc
+++ b/man/zip_set_default_password.mdoc
@@ -29,7 +29,7 @@
.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
-.Dd December 18, 2017
+.Dd September 14, 2020
.Dt ZIP_SET_DEFAULT_PASSWORD 3
.Os
.Sh NAME
@@ -57,6 +57,13 @@
.Xr zip_fopen 3 .
Usually, however, the same password is used for every file in an
zip archive.
+.Pp
+The password is not verified when calling this function.
+See the
+.Sx CAVEATS
+section in
+.Xr zip_fopen_encrypted 3
+for more details about password handling.
.Sh RETURN VALUES
Upon successful completion 0 is returned.
Otherwise, \-1 is returned and the error information in
