.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Crypt::PK::DH 3" .TH Crypt::PK::DH 3 2024-10-20 "perl v5.40.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME Crypt::PK::DH \- Public key cryptography based on Diffie\-Hellman .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 1 \& ### OO interface \& \& #Shared secret \& my $priv = Crypt::PK::DH\->new(\*(AqAlice_priv_dh1.key\*(Aq); \& my $pub = Crypt::PK::DH\->new(\*(AqBob_pub_dh1.key\*(Aq); \& my $shared_secret = $priv\->shared_secret($pub); \& \& #Key generation \& my $pk = Crypt::PK::DH\->new(); \& $pk\->generate_key(128); \& my $private = $pk\->export_key(\*(Aqprivate\*(Aq); \& my $public = $pk\->export_key(\*(Aqpublic\*(Aq); \& \& or \& \& my $pk = Crypt::PK::DH\->new(); \& $pk\->generate_key(\*(Aqike2048\*(Aq); \& my $private = $pk\->export_key(\*(Aqprivate\*(Aq); \& my $public = $pk\->export_key(\*(Aqpublic\*(Aq); \& \& or \& \& my $pk = Crypt::PK::DH\->new(); \& $pk\->generate_key({ p => $p, g => $g }); \& my $private = $pk\->export_key(\*(Aqprivate\*(Aq); \& my $public = $pk\->export_key(\*(Aqpublic\*(Aq); \& \& ### Functional interface \& \& #Shared secret \& my $shared_secret = dh_shared_secret(\*(AqAlice_priv_dh1.key\*(Aq, \*(AqBob_pub_dh1.key\*(Aq); .Ve .SH METHODS .IX Header "METHODS" .SS new .IX Subsection "new" .Vb 5 \& my $pk = Crypt::PK::DH\->new(); \& #or \& my $pk = Crypt::PK::DH\->new($priv_or_pub_key_filename); \& #or \& my $pk = Crypt::PK::DH\->new(\e$buffer_containing_priv_or_pub_key); .Ve .SS generate_key .IX Subsection "generate_key" Uses Yarrow-based cryptographically strong random number generator seeded with random data taken from \f(CW\*(C`/dev/random\*(C'\fR (UNIX) or \f(CW\*(C`CryptGenRandom\*(C'\fR (Win32). .PP .Vb 10 \& $pk\->generate_key($groupsize); \& ### $groupsize (in bytes) corresponds to DH parameters (p, g) predefined by libtomcrypt \& # 96 => DH\-768 \& # 128 => DH\-1024 \& # 192 => DH\-1536 \& # 256 => DH\-2048 \& # 384 => DH\-3072 \& # 512 => DH\-4096 \& # 768 => DH\-6144 \& # 1024 => DH\-8192 .Ve .PP The following variants are available since CryptX\-0.032 .PP .Vb 10 \& $pk\->generate_key($groupname) \& ### $groupname corresponds to values defined in RFC7296 and RFC3526 \& # \*(Aqike768\*(Aq => 768\-bit MODP (Group 1) \& # \*(Aqike1024\*(Aq => 1024\-bit MODP (Group 2) \& # \*(Aqike1536\*(Aq => 1536\-bit MODP (Group 5) \& # \*(Aqike2048\*(Aq => 2048\-bit MODP (Group 14) \& # \*(Aqike3072\*(Aq => 3072\-bit MODP (Group 15) \& # \*(Aqike4096\*(Aq => 4096\-bit MODP (Group 16) \& # \*(Aqike6144\*(Aq => 6144\-bit MODP (Group 17) \& # \*(Aqike8192\*(Aq => 8192\-bit MODP (Group 18) \& \& $pk\->generate_key($param_hash) \& # $param_hash is { g => $g, p => $p } \& # where $g is the generator (base) in a hex string and $p is the prime in a hex string \& \& $pk\->generate_key(\e$dh_param) \& # $dh_param is the content of DER or PEM file with DH parameters \& # e.g. openssl dhparam 2048 .Ve .SS import_key .IX Subsection "import_key" Loads private or public key (exported by "export_key"). .PP .Vb 3 \& $pk\->import_key($filename); \& #or \& $pk\->import_key(\e$buffer_containing_key); .Ve .SS import_key_raw .IX Subsection "import_key_raw" \&\fISince: CryptX\-0.032\fR .PP .Vb 5 \& $pk\->import_key_raw($raw_bytes, $type, $params) \& ### $raw_bytes is a binary string containing the key \& ### $type is either \*(Aqprivate\*(Aq or \*(Aqpublic\*(Aq \& ### $param is either a name (\*(Aqike2038\*(Aq) or hash containing the p,g values { g=>$g, p=>$p } \& ### in hex strings .Ve .SS export_key .IX Subsection "export_key" \&\fBBEWARE:\fR DH key format change \- since v0.049 it is compatible with libtomcrypt 1.18. .PP .Vb 3 \& my $private = $pk\->export_key(\*(Aqprivate\*(Aq); \& #or \& my $public = $pk\->export_key(\*(Aqpublic\*(Aq); .Ve .SS export_key_raw .IX Subsection "export_key_raw" \&\fISince: CryptX\-0.032\fR .PP .Vb 3 \& $raw_bytes = $dh\->export_key_raw(\*(Aqpublic\*(Aq) \& #or \& $raw_bytes = $dh\->export_key_raw(\*(Aqprivate\*(Aq) .Ve .SS shared_secret .IX Subsection "shared_secret" .Vb 4 \& # Alice having her priv key $pk and Bob\*(Aqs public key $pkb \& my $pk = Crypt::PK::DH\->new($priv_key_filename); \& my $pkb = Crypt::PK::DH\->new($pub_key_filename); \& my $shared_secret = $pk\->shared_secret($pkb); \& \& # Bob having his priv key $pk and Alice\*(Aqs public key $pka \& my $pk = Crypt::PK::DH\->new($priv_key_filename); \& my $pka = Crypt::PK::DH\->new($pub_key_filename); \& my $shared_secret = $pk\->shared_secret($pka); # same value as computed by Alice .Ve .SS is_private .IX Subsection "is_private" .Vb 4 \& my $rv = $pk\->is_private; \& # 1 .. private key loaded \& # 0 .. public key loaded \& # undef .. no key loaded .Ve .SS size .IX Subsection "size" .Vb 2 \& my $size = $pk\->size; \& # returns key size in bytes or undef if no key loaded .Ve .SS key2hash .IX Subsection "key2hash" .Vb 1 \& my $hash = $pk\->key2hash; \& \& # returns hash like this (or undef if no key loaded): \& { \& type => 0, # integer: 1 .. private, 0 .. public \& size => 256, # integer: key size in bytes \& x => "FBC1062F73B9A17BB8473A2F5A074911FA7F20D28FB...", #private key \& y => "AB9AAA40774D3CD476B52F82E7EE2D8A8D40CD88BF4...", #public key \& g => "2", # generator/base \& p => "FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80D...", # prime \&} .Ve .SS params2hash .IX Subsection "params2hash" \&\fISince: CryptX\-0.032\fR .PP .Vb 1 \& my $params = $pk\->params2hash; \& \& # returns hash like this (or undef if no key loaded): \& { \& g => "2", # generator/base \& p => "FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80D...", # prime \&} .Ve .SH FUNCTIONS .IX Header "FUNCTIONS" .SS dh_shared_secret .IX Subsection "dh_shared_secret" DH based shared secret generation. See method "shared_secret" below. .PP .Vb 2 \& #on Alice side \& my $shared_secret = dh_shared_secret(\*(AqAlice_priv_dh1.key\*(Aq, \*(AqBob_pub_dh1.key\*(Aq); \& \& #on Bob side \& my $shared_secret = dh_shared_secret(\*(AqBob_priv_dh1.key\*(Aq, \*(AqAlice_pub_dh1.key\*(Aq); .Ve .SH "DEPRECATED INTERFACE" .IX Header "DEPRECATED INTERFACE" The following functions/methods were removed in removed in v0.049: .PP .Vb 6 \& encrypt \& decrypt \& sign_message \& verify_message \& sign_hash \& verify_hash \& \& dh_encrypt \& dh_decrypt \& dh_sign_message \& dh_verify_message \& dh_sign_hash \& dh_verify_hash .Ve .SH "SEE ALSO" .IX Header "SEE ALSO" .IP \(bu 4