convert DES and DH manuals from pod to mdoc

1 files changed, 125 insertions, 0 deletions

diff --git a/lib/libcrypto/man/DH_generate_parameters.3 b/lib/libcrypto/man/DH_generate_parameters.3
new file mode 100644
index 00000000000..431ffd634c8
--- /dev/null
+++ b/lib/libcrypto/man/DH_generate_parameters.3
@@ -0,0 +1,125 @@
+.Dd $Mdocdate: November 2 2016 $
+.Dt DH_GENERATE_PARAMETERS 3
+.Os
+.Sh NAME
+.Nm DH_generate_parameters_ex ,
+.Nm DH_generate_parameters ,
+.Nm DH_check
+.Nd generate and check Diffie-Hellman parameters
+.Sh SYNOPSIS
+.In openssl/dh.h
+.Ft int
+.Fo DH_generate_parameters_ex
+.Fa "DH *dh"
+.Fa "int prime_len"
+.Fa "int generator"
+.Fa "BN_GENCB *cb"
+.Fc
+.Ft int
+.Fo DH_check
+.Fa "DH *dh"
+.Fa "int *codes"
+.Fc
+.Pp
+Deprecated:
+.Pp
+.Ft DH *
+.Fo DH_generate_parameters
+.Fa "int prime_len"
+.Fa "int generator"
+.Fa "void (*callback)(int"
+.Fa int
+.Fa "void *)"
+.Fa "void *cb_arg"
+.Fc
+.Sh DESCRIPTION
+.Fn DH_generate_parameters_ex
+generates Diffie-Hellman parameters that can be shared among a group of
+users, and stores them in the provided
+.Vt DH
+structure.
+.Pp
+.Fa prime_len
+is the length in bits of the safe prime to be generated.
+.Fa generator
+is a small number > 1, typically 2 or 5.
+.Pp
+A callback function may be used to provide feedback about the progress
+of the key generation.
+If
+.Fa cb
+is not
+.Dv NULL ,
+it will be called as described in
+.Xr BN_generate_prime 3
+while a random prime number is generated, and when a prime has been
+found,
+.Fn BN_GENCB_call cb 3 0
+is called; see
+.Xr BN_GENCB_call 3 .
+.Pp
+.Fn DH_check
+validates Diffie-Hellman parameters.
+It checks that
+.Fa dh->p
+is a safe prime, and that
+.Fa dh->g
+is a suitable generator.
+In the case of an error, the bit flags
+.Dv DH_CHECK_P_NOT_SAFE_PRIME
+or
+.Dv DH_NOT_SUITABLE_GENERATOR
+are set in
+.Pf * Fa codes .
+.Dv DH_UNABLE_TO_CHECK_GENERATOR
+is set if the generator cannot be checked, i.e. if it does not equal 2 or 5.
+.Sh RETURN VALUES
+.Fn DH_generate_parameters_ex
+and
+.Fn DH_check
+return 1 if the check could be performed, 0 otherwise.
+.Pp
+.Fn DH_generate_parameters
+(deprecated) returns a pointer to the
+.Vt DH
+structure, or
+.Dv NULL
+if the parameter generation fails.
+.Pp
+The error codes can be obtained by
+.Xr ERR_get_error 3 .
+.Sh SEE ALSO
+.Xr dh 3 ,
+.Xr DH_free 3 ,
+.Xr ERR_get_error 3 ,
+.Xr rand 3
+.Sh HISTORY
+.Fn DH_check
+is available in all versions of SSLeay and OpenSSL.
+The
+.Fa cb_arg
+argument to
+.Fn DH_generate_parameters
+was added in SSLeay 0.9.0.
+.Pp
+In versions before OpenSSL 0.9.5,
+.Dv DH_CHECK_P_NOT_STRONG_PRIME
+is used instead of
+.Dv DH_CHECK_P_NOT_SAFE_PRIME .
+.Sh CAVEATS
+.Fn DH_generate_parameters_ex
+and
+.Fn DH_generate_parameters
+may run for several hours before finding a suitable prime.
+.Pp
+The parameters generated by
+.Fn DH_generate_parameters_ex
+and
+.Fn DH_generate_parameters
+are not to be used in signature schemes.
+.Sh BUGS
+If
+.Fa generator
+is not 2 or 5,
+.Fa dh->g Ns = Ns Fa generator
+is not a usable generator.