Add documentation for -pkeyopt_passin

Add documentation to new parameter and two examples showcasing scrypt
KDF.

Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/5697)

diff --git a/doc/man1/pkeyutl.pod b/doc/man1/pkeyutl.pod
index 664dbef3598b132d7217ff969c9644fe9bf1f3f5..a0dae86cfc85b53c54ea4f17eb365549f75519d7 100644 (file)
--- a/doc/man1/pkeyutl.pod
+++ b/doc/man1/pkeyutl.pod
@@ -29,6 +29,7 @@ B<openssl> B<pkeyutl>
 [B<-kdf algorithm>]
 [B<-kdflen length>]
 [B<-pkeyopt opt:value>]
+[B<-pkeyopt_passin opt:passarg>]
 [B<-hexdump>]
 [B<-asn1parse>]
 [B<-rand file...>]
@@ -140,6 +141,13 @@ Set the output length for KDF.
 
 Public key options specified as opt:value. See NOTES below for more details.
 
+=item B<-pkeyopt_passin opt:passarg>
+
+Allows reading a public key option B<opt> from stdin or a password source. If
+only opt is specified, the user will be prompted to enter the value on stdin.
+Alternatively, passarg can be specified which can be any value supported by
+B<PASS PHRASE ARGUMENTS> in L<openssl(1)>.
+
 =item B<-hexdump>
 
 hex dump the output data.
@@ -320,6 +328,16 @@ seed consisting of the single byte 0xFF:
  openssl pkeyutl -kdf TLS1-PRF -kdflen 48 -pkeyopt md:SHA256 \
     -pkeyopt hexsecret:ff -pkeyopt hexseed:ff -hexdump
 
+Derive a key using B<scrypt> where the password is read from command line:
+
+ openssl pkeyutl -kdf scrypt -kdflen 16 -pkeyopt_passin pass \
+    -pkeyopt hexsalt:aabbcc -pkeyopt N:16384 -pkeyopt r:8 -pkeyopt p:1
+
+Derive using the same algorithm, but read key from environment variable MYPASS:
+
+ openssl pkeyutl -kdf scrypt -kdflen 16 -pkeyopt_passin pass:env:MYPASS \
+    -pkeyopt hexsalt:aabbcc -pkeyopt N:16384 -pkeyopt r:8 -pkeyopt p:1
+
 =head1 SEE ALSO
 
 L<genpkey(1)>, L<pkey(1)>, L<rsautl(1)>