summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorschwarze <>2015-11-12 00:55:49 +0000
committerschwarze <>2015-11-12 00:55:49 +0000
commitd87f13d29bdce02ae37ef5da3fb9e0227724e57b (patch)
tree7050351f491582d85dae8d06f9530073074006fe
parent3681e43b7101c2171779b147addaa726f1373b2b (diff)
downloadopenbsd-d87f13d29bdce02ae37ef5da3fb9e0227724e57b.tar.gz
openbsd-d87f13d29bdce02ae37ef5da3fb9e0227724e57b.tar.bz2
openbsd-d87f13d29bdce02ae37ef5da3fb9e0227724e57b.zip
Convert the handful of manuals that had imaginary names,
give them names that really exist. This also helps jmc@'s ongoing work on improving NAME sections.
Diffstat
-rw-r--r--src/lib/libcrypto/man/ECDSA_SIG_new.3396
-rw-r--r--src/lib/libcrypto/man/Makefile192
-rw-r--r--src/lib/libcrypto/man/bn_dump.3713
-rw-r--r--src/lib/libcrypto/man/d2i_PKCS8PrivateKey_bio.397
-rw-r--r--src/lib/libcrypto/man/des_read_pw.397
-rw-r--r--src/lib/libcrypto/man/lh_new.3430
-rw-r--r--src/lib/libcrypto/man/ui_new.3384
-rw-r--r--src/lib/libssl/src/doc/crypto/bn_internal.pod238
-rw-r--r--src/lib/libssl/src/doc/crypto/d2i_PKCS8PrivateKey.pod58
-rw-r--r--src/lib/libssl/src/doc/crypto/ecdsa.pod205
-rw-r--r--src/lib/libssl/src/doc/crypto/lhash.pod303
-rw-r--r--src/lib/libssl/src/doc/crypto/ui.pod194
-rw-r--r--src/lib/libssl/src/doc/crypto/ui_compat.pod57
13 files changed, 2210 insertions, 1154 deletions
diff --git a/src/lib/libcrypto/man/ECDSA_SIG_new.3 b/src/lib/libcrypto/man/ECDSA_SIG_new.3
new file mode 100644
index 0000000000..422ccdeb42
--- /dev/null
+++ b/src/lib/libcrypto/man/ECDSA_SIG_new.3
@@ -0,0 +1,396 @@
1.Dd $Mdocdate: November 12 2015 $
2.Dt ECDSA_SIG_NEW 3
3.Os
4.Sh NAME
5.Nm ECDSA_SIG_new ,
6.Nm ECDSA_SIG_free ,
7.Nm i2d_ECDSA_SIG ,
8.Nm d2i_ECDSA_SIG ,
9.Nm ECDSA_size ,
10.Nm ECDSA_sign_setup ,
11.Nm ECDSA_sign ,
12.Nm ECDSA_sign_ex ,
13.Nm ECDSA_verify ,
14.Nm ECDSA_do_sign ,
15.Nm ECDSA_do_sign_ex ,
16.Nm ECDSA_do_verify ,
17.Nm ECDSA_OpenSSL ,
18.Nm ECDSA_get_default_method ,
19.Nm ECDSA_get_ex_data ,
20.Nm ECDSA_get_ex_new_index ,
21.Nm ECDSA_set_default_method ,
22.Nm ECDSA_set_ex_data ,
23.Nm ECDSA_set_method
24.Nd Elliptic Curve Digital Signature Algorithm
25.Sh SYNOPSIS
26.In openssl/ecdsa.h
27.Ft ECDSA_SIG*
28.Fo ECDSA_SIG_new
29.Fa void
30.Fc
31.Ft void
32.Fo ECDSA_SIG_free
33.Fa "ECDSA_SIG *sig"
34.Fc
35.Ft int
36.Fo i2d_ECDSA_SIG
37.Fa "const ECDSA_SIG *sig"
38.Fa "unsigned char **pp"
39.Fc
40.Ft ECDSA_SIG*
41.Fo d2i_ECDSA_SIG
42.Fa "ECDSA_SIG **sig"
43.Fa "const unsigned char **pp"
44.Fa "long len"
45.Fc
46.Ft ECDSA_SIG*
47.Fo ECDSA_do_sign
48.Fa "const unsigned char *dgst"
49.Fa "int dgst_len"
50.Fa "EC_KEY *eckey"
51.Fc
52.Ft ECDSA_SIG*
53.Fo ECDSA_do_sign_ex
54.Fa "const unsigned char *dgst"
55.Fa "int dgstlen"
56.Fa "const BIGNUM *kinv"
57.Fa "const BIGNUM *rp"
58.Fa "EC_KEY *eckey"
59.Fc
60.Ft int
61.Fo ECDSA_do_verify
62.Fa "const unsigned char *dgst"
63.Fa "int dgst_len"
64.Fa "const ECDSA_SIG *sig"
65.Fa "EC_KEY* eckey"
66.Fc
67.Ft int
68.Fo ECDSA_sign_setup
69.Fa "EC_KEY *eckey"
70.Fa "BN_CTX *ctx"
71.Fa "BIGNUM **kinv"
72.Fa "BIGNUM **rp"
73.Fc
74.Ft int
75.Fo ECDSA_sign
76.Fa "int type"
77.Fa "const unsigned char *dgst"
78.Fa "int dgstlen"
79.Fa "unsigned char *sig"
80.Fa "unsigned int *siglen"
81.Fa "EC_KEY *eckey"
82.Fc
83.Ft int
84.Fo ECDSA_sign_ex
85.Fa "int type"
86.Fa "const unsigned char *dgst"
87.Fa "int dgstlen"
88.Fa "unsigned char *sig"
89.Fa "unsigned int *siglen"
90.Fa "const BIGNUM *kinv"
91.Fa "const BIGNUM *rp"
92.Fa "EC_KEY *eckey"
93.Fc
94.Ft int
95.Fo ECDSA_verify
96.Fa "int type"
97.Fa "const unsigned char *dgst"
98.Fa "int dgstlen"
99.Fa "const unsigned char *sig"
100.Fa "int siglen"
101.Fa "EC_KEY *eckey"
102.Fc
103.Ft int
104.Fo ECDSA_size
105.Fa "const EC_KEY *eckey"
106.Fc
107.Ft const ECDSA_METHOD*
108.Fo ECDSA_OpenSSL
109.Fa void
110.Fc
111.Ft void
112.Fo ECDSA_set_default_method
113.Fa "const ECDSA_METHOD *meth"
114.Fc
115.Ft const ECDSA_METHOD*
116.Fo ECDSA_get_default_method
117.Fa void
118.Fc
119.Ft int
120.Fo ECDSA_set_method
121.Fa "EC_KEY *eckey"
122.Fa "const ECDSA_METHOD *meth"
123.Fc
124.Ft int
125.Fo ECDSA_get_ex_new_index
126.Fa "long argl"
127.Fa "void *argp"
128.Fa "CRYPTO_EX_new *new_func"
129.Fa "CRYPTO_EX_dup *dup_func"
130.Fa "CRYPTO_EX_free *free_func"
131.Fc
132.Ft int
133.Fo ECDSA_set_ex_data
134.Fa "EC_KEY *d"
135.Fa "int idx"
136.Fa "void *arg"
137.Fc
138.Ft void*
139.Fo ECDSA_get_ex_data
140.Fa "EC_KEY *d"
141.Fa "int idx"
142.Fc
143.Sh DESCRIPTION
144The
145.Vt ECDSA_SIG
146structure consists of two
147.Vt BIGNUM Ns s
148for the
149.Fa r
150and
151.Fa s
152value of an ECDSA signature (see X9.62 or FIPS 186-2).
153.Bd -literal -offset indent
154struct {
155 BIGNUM *r;
156 BIGNUM *s;
157} ECDSA_SIG;
158.Ed
159.Pp
160.Fn ECDSA_SIG_new
161allocates a new
162.Vt ECDSA_SIG
163structure (note: this function also allocates the
164.Vt BIGNUM Ns s )
165and initialize it.
166.Pp
167.Fn ECDSA_SIG_free
168frees the
169.Vt ECDSA_SIG
170structure
171.Fa sig .
172.Pp
173.Fn i2d_ECDSA_SIG
174creates the DER encoding of the ECDSA signature
175.Fa sig
176and writes the encoded signature to
177.Fa *pp
178(note: if
179.Fa pp
180is
181.Dv NULL ,
182.Fn i2d_ECDSA_SIG
183returns the expected length in bytes of the DER encoded signature).
184.Fn i2d_ECDSA_SIG
185returns the length of the DER encoded signature (or 0 on error).
186.Pp
187.Fn d2i_ECDSA_SIG
188decodes a DER encoded ECDSA signature and returns the decoded signature
189in a newly allocated
190.Vt ECDSA_SIG
191structure.
192.Fa *sig
193points to the buffer containing the DER encoded signature of size
194.Fa len .
195.Pp
196.Fn ECDSA_size
197returns the maximum length of a DER encoded ECDSA signature created with
198the private EC key
199.Fa eckey .
200.Pp
201.Fn ECDSA_sign_setup
202may be used to precompute parts of the signing operation.
203.Fa eckey
204is the private EC key and
205.Fa ctx
206is a pointer to a
207.Vt BN_CTX
208structure (or
209.Dv NULL ) .
210The precomputed values or returned in
211.Fa kinv
212and
213.Fa rp
214and can be used in a later call to
215.Fa ECDSA_sign_ex
216or
217.Fa ECDSA_do_sign_ex .
218.Pp
219.Fn ECDSA_sign
220is wrapper function for
221.Fa ECDSA_sign_ex
222with
223.Fa kinv
224and
225.Fa rp
226set to
227.Dv NULL .
228.Pp
229.Fn ECDSA_sign_ex
230computes a digital signature of the
231.Fa dgstlen
232bytes hash value
233.Fa dgst
234using the private EC key
235.Fa eckey
236and the optional pre-computed values
237.Fa kinv
238and
239.Fa rp .
240The DER encoded signatures is stored in
241.Fa sig
242and its length is returned in
243.Fa siglen .
244Note:
245.Fa sig
246must point to
247.Fn ECDSA_size
248bytes of memory.
249The parameter
250.Fa type
251is ignored.
252.Pp
253.Fn ECDSA_verify
254verifies that the signature in
255.Fa sig
256of size
257.Fa siglen
258is a valid ECDSA signature of the hash value
259.Fa dgst
260of size
261.Fa dgstlen
262using the public key
263.Fa eckey .
264The parameter
265.Fa type
266is ignored.
267.Pp
268.Fn ECDSA_do_sign
269is wrapper function for ECDSA_do_sign_ex with
270.Fa kinv
271and
272.Fa rp
273set to
274.Dv NULL .
275.Pp
276.Fn ECDSA_do_sign_ex
277computes a digital signature of the
278.Fa dgst_len
279bytes hash value
280.Fa dgst
281using the private key
282.Fa eckey
283and the optional pre-computed values
284.Fa kinv
285and
286.Fa rp .
287The signature is returned in a newly allocated
288.Vt ECDSA_SIG
289structure (or
290.Dv NULL
291on error).
292.Pp
293.Fn ECDSA_do_verify
294verifies that the signature
295.Fa sig
296is a valid ECDSA signature of the hash value
297.Fa dgst
298of size
299.Fa dgst_len
300using the public key
301.Fa eckey .
302.Sh RETURN VALUES
303.Fn ECDSA_size
304returns the maximum length signature or 0 on error.
305.Pp
306.Fn ECDSA_sign_setup
307and
308.Fn ECDSA_sign
309return 1 if successful or 0 on error.
310.Pp
311.Fn ECDSA_verify
312and
313.Fn ECDSA_do_verify
314return 1 for a valid signature, 0 for an invalid signature and -1 on
315error.
316The error codes can be obtained by
317.Xr ERR_get_error 3 .
318.Sh EXAMPLES
319Creating a ECDSA signature of given SHA-1 hash value using the named
320curve secp192k1.
321.Pp
322First step: Create an
323.Vt EC_KEY
324object.
325This part is
326.Em not
327ECDSA specific.
328.Bd -literal -offset indent
329int ret;
330ECDSA_SIG *sig;
331EC_KEY *eckey;
332
333eckey = EC_KEY_new_by_curve_name(NID_secp192k1);
334if (eckey == NULL) {
335 /* error */
336}
337if (!EC_KEY_generate_key(eckey)) {
338 /* error */
339}
340.Ed
341.Pp
342Second step: compute the ECDSA signature of a SHA-1 hash value using
343.Fn ECDSA_do_sign
344.Bd -literal -offset indent
345sig = ECDSA_do_sign(digest, 20, eckey);
346if (sig == NULL) {
347 /* error */
348}
349.Ed
350.Pp
351or using
352.Fn ECDSA_sign
353.Bd -literal -offset indent
354unsigned char *buffer, *pp;
355int buf_len;
356
357buf_len = ECDSA_size(eckey);
358buffer = malloc(buf_len);
359pp = buffer;
360if (!ECDSA_sign(0, dgst, dgstlen, pp, &buf_len, eckey) {
361 /* error */
362}
363.Ed
364.Pp
365Third step: Verify the created ECDSA signature using
366.Fn ECDSA_do_verify
367.Pp
368.Dl ret = ECDSA_do_verify(digest, 20, sig, eckey);
369.Pp
370or using
371.Fn ECDSA_verify
372.Pp
373.Dl ret = ECDSA_verify(0, digest, 20, buffer, buf_len, eckey);
374.Pp
375and finally evaluate the return value:
376.Bd -literal -offset indent
377if (ret == -1) {
378 /* error */
379} else if (ret == 0) {
380 /* incorrect signature */
381} else {
382 /* ret == 1 */
383 /* signature ok */
384}
385.Ed
386.Sh SEE ALSO
387.Xr dsa 3 ,
388.Xr rsa 3
389.Sh STANDARDS
390ANSI X9.62, US Federal Information Processing Standard FIPS 186-2
391(Digital Signature Standard, DSS)
392.Sh HISTORY
393The ecdsa implementation was first introduced in OpenSSL 0.9.8.
394.Sh AUTHORS
395.An Nils Larsch
396for the OpenSSL project.
diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index ecb1d51a52..86c5de26f8 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
1# $OpenBSD: Makefile,v 1.28 2015/11/11 22:14:39 jmc Exp $ 1# $OpenBSD: Makefile,v 1.29 2015/11/12 00:55:49 schwarze Exp $
2 2
3.include <bsd.own.mk> # for NOMAN 3.include <bsd.own.mk> # for NOMAN
4 4
@@ -73,8 +73,14 @@ MAN= \
73 CONF_modules_load_file.3 \ 73 CONF_modules_load_file.3 \
74 CRYPTO_set_ex_data.3 \ 74 CRYPTO_set_ex_data.3 \
75 CRYPTO_set_locking_callback.3 \ 75 CRYPTO_set_locking_callback.3 \
76 ECDSA_SIG_new.3 \
76 EVP_AEAD_CTX_init.3 \ 77 EVP_AEAD_CTX_init.3 \
78 bn_dump.3 \
77 crypto.3 \ 79 crypto.3 \
80 d2i_PKCS8PrivateKey_bio.3 \
81 des_read_pw.3 \
82 lh_new.3 \
83 ui_new.3 \
78 84
79GENMAN= \ 85GENMAN= \
80 DES_set_key.3 \ 86 DES_set_key.3 \
@@ -188,12 +194,10 @@ GENMAN= \
188 X509_new.3 \ 194 X509_new.3 \
189 X509_verify_cert.3 \ 195 X509_verify_cert.3 \
190 bn.3 \ 196 bn.3 \
191 bn_internal.3 \
192 d2i_ASN1_OBJECT.3 \ 197 d2i_ASN1_OBJECT.3 \
193 d2i_DHparams.3 \ 198 d2i_DHparams.3 \
194 d2i_DSAPublicKey.3 \ 199 d2i_DSAPublicKey.3 \
195 d2i_ECPKParameters.3 \ 200 d2i_ECPKParameters.3 \
196 d2i_PKCS8PrivateKey.3 \
197 d2i_RSAPublicKey.3 \ 201 d2i_RSAPublicKey.3 \
198 d2i_X509.3 \ 202 d2i_X509.3 \
199 d2i_X509_ALGOR.3 \ 203 d2i_X509_ALGOR.3 \
@@ -204,15 +208,11 @@ GENMAN= \
204 dh.3 \ 208 dh.3 \
205 dsa.3 \ 209 dsa.3 \
206 ec.3 \ 210 ec.3 \
207 ecdsa.3 \
208 engine.3 \ 211 engine.3 \
209 evp.3 \ 212 evp.3 \
210 i2d_PKCS7_bio_stream.3 \ 213 i2d_PKCS7_bio_stream.3 \
211 lh_stats.3 \ 214 lh_stats.3 \
212 lhash.3 \
213 rsa.3 \ 215 rsa.3 \
214 ui.3 \
215 ui_compat.3 \
216 x509.3 \ 216 x509.3 \
217 217
218MAN+= ${GENMAN} 218MAN+= ${GENMAN}
@@ -605,6 +605,23 @@ MLINKS+=\
605 EC_POINT_new.3 EC_POINT_set_compressed_coordinates_GF2m.3 \ 605 EC_POINT_new.3 EC_POINT_set_compressed_coordinates_GF2m.3 \
606 EC_POINT_new.3 EC_POINT_set_compressed_coordinates_GFp.3 \ 606 EC_POINT_new.3 EC_POINT_set_compressed_coordinates_GFp.3 \
607 EC_POINT_new.3 EC_POINT_set_to_infinity.3 \ 607 EC_POINT_new.3 EC_POINT_set_to_infinity.3 \
608 ECDSA_SIG_new.3 ECDSA_OpenSSL.3 \
609 ECDSA_SIG_new.3 ECDSA_SIG_free.3 \
610 ECDSA_SIG_new.3 ECDSA_do_sign.3 \
611 ECDSA_SIG_new.3 ECDSA_do_sign_ex.3 \
612 ECDSA_SIG_new.3 ECDSA_do_verify.3 \
613 ECDSA_SIG_new.3 ECDSA_get_default_method.3 \
614 ECDSA_SIG_new.3 ECDSA_get_ex_data.3 \
615 ECDSA_SIG_new.3 ECDSA_get_ex_new_index.3 \
616 ECDSA_SIG_new.3 ECDSA_set_default_method.3 \
617 ECDSA_SIG_new.3 ECDSA_set_ex_data.3 \
618 ECDSA_SIG_new.3 ECDSA_set_method.3 \
619 ECDSA_SIG_new.3 ECDSA_sign.3 \
620 ECDSA_SIG_new.3 ECDSA_sign_ex.3 \
621 ECDSA_SIG_new.3 ECDSA_sign_setup.3 \
622 ECDSA_SIG_new.3 ECDSA_verify.3 \
623 ECDSA_SIG_new.3 d2i_ECDSA_SIG.3 \
624 ECDSA_SIG_new.3 i2d_ECDSA_SIG.3 \
608 ERR_GET_LIB.3 ERR_GET_FUNC.3 \ 625 ERR_GET_LIB.3 ERR_GET_FUNC.3 \
609 ERR_GET_LIB.3 ERR_GET_REASON.3 \ 626 ERR_GET_LIB.3 ERR_GET_REASON.3 \
610 ERR_error_string.3 ERR_error_string_n.3 \ 627 ERR_error_string.3 ERR_error_string_n.3 \
@@ -982,38 +999,37 @@ MLINKS+=\
982 X509_VERIFY_PARAM_set_flags.3 X509_VERIFY_PARAM_set_purpose.3 \ 999 X509_VERIFY_PARAM_set_flags.3 X509_VERIFY_PARAM_set_purpose.3 \
983 X509_VERIFY_PARAM_set_flags.3 X509_VERIFY_PARAM_set_time.3 \ 1000 X509_VERIFY_PARAM_set_flags.3 X509_VERIFY_PARAM_set_time.3 \
984 X509_VERIFY_PARAM_set_flags.3 X509_VERIFY_PARAM_set_trust.3 \ 1001 X509_VERIFY_PARAM_set_flags.3 X509_VERIFY_PARAM_set_trust.3 \
985 bn_internal.3 bn_add_words.3 \ 1002 bn_dump.3 bn_add_words.3 \
986 bn_internal.3 bn_check_top.3 \ 1003 bn_dump.3 bn_check_top.3 \
987 bn_internal.3 bn_cmp_words.3 \ 1004 bn_dump.3 bn_cmp_words.3 \
988 bn_internal.3 bn_div_words.3 \ 1005 bn_dump.3 bn_div_words.3 \
989 bn_internal.3 bn_dump.3 \ 1006 bn_dump.3 bn_expand.3 \
990 bn_internal.3 bn_expand.3 \ 1007 bn_dump.3 bn_expand2.3 \
991 bn_internal.3 bn_expand2.3 \ 1008 bn_dump.3 bn_fix_top.3 \
992 bn_internal.3 bn_fix_top.3 \ 1009 bn_dump.3 bn_mul_add_words.3 \
993 bn_internal.3 bn_mul_add_words.3 \ 1010 bn_dump.3 bn_mul_comba4.3 \
994 bn_internal.3 bn_mul_comba4.3 \ 1011 bn_dump.3 bn_mul_comba8.3 \
995 bn_internal.3 bn_mul_comba8.3 \ 1012 bn_dump.3 bn_mul_high.3 \
996 bn_internal.3 bn_mul_high.3 \ 1013 bn_dump.3 bn_mul_low_normal.3 \
997 bn_internal.3 bn_mul_low_normal.3 \ 1014 bn_dump.3 bn_mul_low_recursive.3 \
998 bn_internal.3 bn_mul_low_recursive.3 \ 1015 bn_dump.3 bn_mul_normal.3 \
999 bn_internal.3 bn_mul_normal.3 \ 1016 bn_dump.3 bn_mul_part_recursive.3 \
1000 bn_internal.3 bn_mul_part_recursive.3 \ 1017 bn_dump.3 bn_mul_recursive.3 \
1001 bn_internal.3 bn_mul_recursive.3 \ 1018 bn_dump.3 bn_mul_words.3 \
1002 bn_internal.3 bn_mul_words.3 \ 1019 bn_dump.3 bn_print.3 \
1003 bn_internal.3 bn_print.3 \ 1020 bn_dump.3 bn_set_high.3 \
1004 bn_internal.3 bn_set_high.3 \ 1021 bn_dump.3 bn_set_low.3 \
1005 bn_internal.3 bn_set_low.3 \ 1022 bn_dump.3 bn_set_max.3 \
1006 bn_internal.3 bn_set_max.3 \ 1023 bn_dump.3 bn_sqr_comba4.3 \
1007 bn_internal.3 bn_sqr_comba4.3 \ 1024 bn_dump.3 bn_sqr_comba8.3 \
1008 bn_internal.3 bn_sqr_comba8.3 \ 1025 bn_dump.3 bn_sqr_normal.3 \
1009 bn_internal.3 bn_sqr_normal.3 \ 1026 bn_dump.3 bn_sqr_recursive.3 \
1010 bn_internal.3 bn_sqr_recursive.3 \ 1027 bn_dump.3 bn_sqr_words.3 \
1011 bn_internal.3 bn_sqr_words.3 \ 1028 bn_dump.3 bn_sub_words.3 \
1012 bn_internal.3 bn_sub_words.3 \ 1029 bn_dump.3 bn_wexpand.3 \
1013 bn_internal.3 bn_wexpand.3 \ 1030 bn_dump.3 mul.3 \
1014 bn_internal.3 mul.3 \ 1031 bn_dump.3 mul_add.3 \
1015 bn_internal.3 mul_add.3 \ 1032 bn_dump.3 sqr.3 \
1016 bn_internal.3 sqr.3 \
1017 d2i_ASN1_OBJECT.3 i2d_ASN1_OBJECT.3 \ 1033 d2i_ASN1_OBJECT.3 i2d_ASN1_OBJECT.3 \
1018 d2i_DHparams.3 i2d_DHparams.3 \ 1034 d2i_DHparams.3 i2d_DHparams.3 \
1019 d2i_DSAPublicKey.3 d2i_DSAPrivateKey.3 \ 1035 d2i_DSAPublicKey.3 d2i_DSAPrivateKey.3 \
@@ -1032,12 +1048,11 @@ MLINKS+=\
1032 d2i_ECPKParameters.3 i2d_ECPKParameters.3 \ 1048 d2i_ECPKParameters.3 i2d_ECPKParameters.3 \
1033 d2i_ECPKParameters.3 i2d_ECPKParameters_bio.3 \ 1049 d2i_ECPKParameters.3 i2d_ECPKParameters_bio.3 \
1034 d2i_ECPKParameters.3 i2d_ECPKParameters_fp.3 \ 1050 d2i_ECPKParameters.3 i2d_ECPKParameters_fp.3 \
1035 d2i_PKCS8PrivateKey.3 d2i_PKCS8PrivateKey_bio.3 \ 1051 d2i_PKCS8PrivateKey_bio.3 d2i_PKCS8PrivateKey_fp.3 \
1036 d2i_PKCS8PrivateKey.3 d2i_PKCS8PrivateKey_fp.3 \ 1052 d2i_PKCS8PrivateKey_bio.3 i2d_PKCS8PrivateKey_bio.3 \
1037 d2i_PKCS8PrivateKey.3 i2d_PKCS8PrivateKey_bio.3 \ 1053 d2i_PKCS8PrivateKey_bio.3 i2d_PKCS8PrivateKey_fp.3 \
1038 d2i_PKCS8PrivateKey.3 i2d_PKCS8PrivateKey_fp.3 \ 1054 d2i_PKCS8PrivateKey_bio.3 i2d_PKCS8PrivateKey_nid_bio.3 \
1039 d2i_PKCS8PrivateKey.3 i2d_PKCS8PrivateKey_nid_bio.3 \ 1055 d2i_PKCS8PrivateKey_bio.3 i2d_PKCS8PrivateKey_nid_fp.3 \
1040 d2i_PKCS8PrivateKey.3 i2d_PKCS8PrivateKey_nid_fp.3 \
1041 d2i_RSAPublicKey.3 d2i_Netscape_RSA.3 \ 1056 d2i_RSAPublicKey.3 d2i_Netscape_RSA.3 \
1042 d2i_RSAPublicKey.3 d2i_RSAPrivateKey.3 \ 1057 d2i_RSAPublicKey.3 d2i_RSAPrivateKey.3 \
1043 d2i_RSAPublicKey.3 i2d_Netscape_RSA.3 \ 1058 d2i_RSAPublicKey.3 i2d_Netscape_RSA.3 \
@@ -1060,24 +1075,9 @@ MLINKS+=\
1060 d2i_X509_REQ.3 i2d_X509_REQ.3 \ 1075 d2i_X509_REQ.3 i2d_X509_REQ.3 \
1061 d2i_X509_REQ.3 i2d_X509_REQ_bio.3 \ 1076 d2i_X509_REQ.3 i2d_X509_REQ_bio.3 \
1062 d2i_X509_REQ.3 i2d_X509_REQ_fp.3 \ 1077 d2i_X509_REQ.3 i2d_X509_REQ_fp.3 \
1063 ecdsa.3 ECDSA_OpenSSL.3 \ 1078 des_read_pw.3 des_read_2passwords.3 \
1064 ecdsa.3 ECDSA_SIG_free.3 \ 1079 des_read_pw.3 des_read_password.3 \
1065 ecdsa.3 ECDSA_SIG_new.3 \ 1080 des_read_pw.3 des_read_pw_string.3 \
1066 ecdsa.3 ECDSA_do_sign.3 \
1067 ecdsa.3 ECDSA_do_sign_ex.3 \
1068 ecdsa.3 ECDSA_do_verify.3 \
1069 ecdsa.3 ECDSA_get_default_method.3 \
1070 ecdsa.3 ECDSA_get_ex_data.3 \
1071 ecdsa.3 ECDSA_get_ex_new_index.3 \
1072 ecdsa.3 ECDSA_set_default_method.3 \
1073 ecdsa.3 ECDSA_set_ex_data.3 \
1074 ecdsa.3 ECDSA_set_method.3 \
1075 ecdsa.3 ECDSA_sign.3 \
1076 ecdsa.3 ECDSA_sign_ex.3 \
1077 ecdsa.3 ECDSA_sign_setup.3 \
1078 ecdsa.3 ECDSA_verify.3 \
1079 ecdsa.3 d2i_ECDSA_SIG.3 \
1080 ecdsa.3 i2d_ECDSA_SIG.3 \
1081 engine.3 ENGINE_add.3 \ 1081 engine.3 ENGINE_add.3 \
1082 engine.3 ENGINE_by_id.3 \ 1082 engine.3 ENGINE_by_id.3 \
1083 engine.3 ENGINE_finish.3 \ 1083 engine.3 ENGINE_finish.3 \
@@ -1088,47 +1088,41 @@ MLINKS+=\
1088 engine.3 ENGINE_init.3 \ 1088 engine.3 ENGINE_init.3 \
1089 engine.3 ENGINE_load_builtin_engines.3 \ 1089 engine.3 ENGINE_load_builtin_engines.3 \
1090 engine.3 ENGINE_remove.3 \ 1090 engine.3 ENGINE_remove.3 \
1091 lh_new.3 lh_delete.3 \
1092 lh_new.3 lh_doall.3 \
1093 lh_new.3 lh_doall_arg.3 \
1094 lh_new.3 lh_error.3 \
1095 lh_new.3 lh_free.3 \
1096 lh_new.3 lh_insert.3 \
1097 lh_new.3 lh_retrieve.3 \
1091 lh_stats.3 lh_node_stats.3 \ 1098 lh_stats.3 lh_node_stats.3 \
1092 lh_stats.3 lh_node_stats_bio.3 \ 1099 lh_stats.3 lh_node_stats_bio.3 \
1093 lh_stats.3 lh_node_usage_stats.3 \ 1100 lh_stats.3 lh_node_usage_stats.3 \
1094 lh_stats.3 lh_node_usage_stats_bio.3 \ 1101 lh_stats.3 lh_node_usage_stats_bio.3 \
1095 lh_stats.3 lh_stats_bio.3 \ 1102 lh_stats.3 lh_stats_bio.3 \
1096 lhash.3 lh_delete.3 \ 1103 ui_new.3 UI_OpenSSL.3 \
1097 lhash.3 lh_doall.3 \ 1104 ui_new.3 UI_add_error_string.3 \
1098 lhash.3 lh_doall_arg.3 \ 1105 ui_new.3 UI_add_info_string.3 \
1099 lhash.3 lh_error.3 \ 1106 ui_new.3 UI_add_input_boolean.3 \
1100 lhash.3 lh_free.3 \ 1107 ui_new.3 UI_add_input_string.3 \
1101 lhash.3 lh_insert.3 \ 1108 ui_new.3 UI_add_user_data.3 \
1102 lhash.3 lh_new.3 \ 1109 ui_new.3 UI_add_verify_string.3 \
1103 lhash.3 lh_retrieve.3 \ 1110 ui_new.3 UI_construct_prompt.3 \
1104 ui.3 UI_OpenSSL.3 \ 1111 ui_new.3 UI_ctrl.3 \
1105 ui.3 UI_add_error_string.3 \ 1112 ui_new.3 UI_dup_error_string.3 \
1106 ui.3 UI_add_info_string.3 \ 1113 ui_new.3 UI_dup_info_string.3 \
1107 ui.3 UI_add_input_boolean.3 \ 1114 ui_new.3 UI_dup_input_boolean.3 \
1108 ui.3 UI_add_input_string.3 \ 1115 ui_new.3 UI_dup_input_string.3 \
1109 ui.3 UI_add_user_data.3 \ 1116 ui_new.3 UI_dup_verify_string.3 \
1110 ui.3 UI_add_verify_string.3 \ 1117 ui_new.3 UI_free.3 \
1111 ui.3 UI_construct_prompt.3 \ 1118 ui_new.3 UI_get0_result.3 \
1112 ui.3 UI_ctrl.3 \ 1119 ui_new.3 UI_get0_user_data.3 \
1113 ui.3 UI_dup_error_string.3 \ 1120 ui_new.3 UI_get_default_method.3 \
1114 ui.3 UI_dup_info_string.3 \ 1121 ui_new.3 UI_get_method.3 \
1115 ui.3 UI_dup_input_boolean.3 \ 1122 ui_new.3 UI_new_method.3 \
1116 ui.3 UI_dup_input_string.3 \ 1123 ui_new.3 UI_process.3 \
1117 ui.3 UI_dup_verify_string.3 \ 1124 ui_new.3 UI_set_default_method.3 \
1118 ui.3 UI_free.3 \ 1125 ui_new.3 UI_set_method.3
1119 ui.3 UI_get0_result.3 \
1120 ui.3 UI_get0_user_data.3 \
1121 ui.3 UI_get_default_method.3 \
1122 ui.3 UI_get_method.3 \
1123 ui.3 UI_new.3 \
1124 ui.3 UI_new_method.3 \
1125 ui.3 UI_process.3 \
1126 ui.3 UI_set_default_method.3 \
1127 ui.3 UI_set_method.3 \
1128 ui_compat.3 des_read_2passwords.3 \
1129 ui_compat.3 des_read_password.3 \
1130 ui_compat.3 des_read_pw.3 \
1131 ui_compat.3 des_read_pw_string.3
1132 1126
1133.include <bsd.man.mk> 1127.include <bsd.man.mk>
1134.else 1128.else
diff --git a/src/lib/libcrypto/man/bn_dump.3 b/src/lib/libcrypto/man/bn_dump.3
new file mode 100644
index 0000000000..2f1bda9bb5
--- /dev/null
+++ b/src/lib/libcrypto/man/bn_dump.3
@@ -0,0 +1,713 @@
1.Dd $Mdocdate: November 12 2015 $
2.Dt BN_DUMP 3
3.Os
4.Sh NAME
5.Nm bn_mul_words ,
6.Nm bn_mul_add_words ,
7.Nm bn_sqr_words ,
8.Nm bn_div_words ,
9.Nm bn_add_words ,
10.Nm bn_sub_words ,
11.Nm bn_mul_comba4 ,
12.Nm bn_mul_comba8 ,
13.Nm bn_sqr_comba4 ,
14.Nm bn_sqr_comba8 ,
15.Nm bn_cmp_words ,
16.Nm bn_mul_normal ,
17.Nm bn_mul_low_normal ,
18.Nm bn_mul_recursive ,
19.Nm bn_mul_part_recursive ,
20.Nm bn_mul_low_recursive ,
21.Nm bn_mul_high ,
22.Nm bn_sqr_normal ,
23.Nm bn_sqr_recursive ,
24.Nm bn_expand ,
25.Nm bn_wexpand ,
26.Nm bn_expand2 ,
27.Nm bn_fix_top ,
28.Nm bn_check_top ,
29.Nm bn_print ,
30.Nm bn_dump ,
31.Nm bn_set_max ,
32.Nm bn_set_high ,
33.Nm bn_set_low ,
34.Nm sqr
35.Nd BIGNUM library internal functions
36.Sh SYNOPSIS
37.In openssl/bn.h
38.Ft BN_ULONG
39.Fo bn_mul_words
40.Fa "BN_ULONG *rp"
41.Fa "BN_ULONG *ap"
42.Fa "int num"
43.Fa "BN_ULONG w"
44.Fc
45.Ft BN_ULONG
46.Fo bn_mul_add_words
47.Fa "BN_ULONG *rp"
48.Fa "BN_ULONG *ap"
49.Fa "int num"
50.Fa "BN_ULONG w"
51.Fc
52.Ft void
53.Fo bn_sqr_words
54.Fa "BN_ULONG *rp"
55.Fa "BN_ULONG *ap"
56.Fa "int num"
57.Fc
58.Ft BN_ULONG
59.Fo bn_div_words
60.Fa "BN_ULONG h"
61.Fa "BN_ULONG l"
62.Fa "BN_ULONG d"
63.Fc
64.Ft BN_ULONG
65.Fo bn_add_words
66.Fa "BN_ULONG *rp"
67.Fa "BN_ULONG *ap"
68.Fa "BN_ULONG *bp"
69.Fa "int num"
70.Fc
71.Ft BN_ULONG
72.Fo bn_sub_words
73.Fa "BN_ULONG *rp"
74.Fa "BN_ULONG *ap"
75.Fa "BN_ULONG *bp"
76.Fa "int num"
77.Fc
78.Ft void
79.Fo bn_mul_comba4
80.Fa "BN_ULONG *r"
81.Fa "BN_ULONG *a"
82.Fa "BN_ULONG *b"
83.Fc
84.Ft void
85.Fo bn_mul_comba8
86.Fa "BN_ULONG *r"
87.Fa "BN_ULONG *a"
88.Fa "BN_ULONG *b"
89.Fc
90.Ft void
91.Fo bn_sqr_comba4
92.Fa "BN_ULONG *r"
93.Fa "BN_ULONG *a"
94.Fc
95.Ft void
96.Fo bn_sqr_comba8
97.Fa "BN_ULONG *r"
98.Fa "BN_ULONG *a"
99.Fc
100.Ft int
101.Fo bn_cmp_words
102.Fa "BN_ULONG *a"
103.Fa "BN_ULONG *b"
104.Fa "int n"
105.Fc
106.Ft void
107.Fo bn_mul_normal
108.Fa "BN_ULONG *r"
109.Fa "BN_ULONG *a"
110.Fa "int na"
111.Fa "BN_ULONG *b"
112.Fa "int nb"
113.Fc
114.Ft void
115.Fo bn_mul_low_normal
116.Fa "BN_ULONG *r"
117.Fa "BN_ULONG *a"
118.Fa "BN_ULONG *b"
119.Fa "int n"
120.Fc
121.Ft void
122.Fo bn_mul_recursive
123.Fa "BN_ULONG *r"
124.Fa "BN_ULONG *a"
125.Fa "BN_ULONG *b"
126.Fa "int n2"
127.Fa "int dna"
128.Fa "int dnb"
129.Fa "BN_ULONG *tmp"
130.Fc
131.Ft void
132.Fo bn_mul_part_recursive
133.Fa "BN_ULONG *r"
134.Fa "BN_ULONG *a"
135.Fa "BN_ULONG *b"
136.Fa "int n"
137.Fa "int tna"
138.Fa "int tnb"
139.Fa "BN_ULONG *tmp"
140.Fc
141.Ft void
142.Fo bn_mul_low_recursive
143.Fa "BN_ULONG *r"
144.Fa "BN_ULONG *a"
145.Fa "BN_ULONG *b"
146.Fa "int n2"
147.Fa "BN_ULONG *tmp"
148.Fc
149.Ft void
150.Fo bn_mul_high
151.Fa "BN_ULONG *r"
152.Fa "BN_ULONG *a"
153.Fa "BN_ULONG *b"
154.Fa "BN_ULONG *l"
155.Fa "int n2"
156.Fa "BN_ULONG *tmp"
157.Fc
158.Ft void
159.Fo bn_sqr_normal
160.Fa "BN_ULONG *r"
161.Fa "BN_ULONG *a"
162.Fa "int n"
163.Fa "BN_ULONG *tmp"
164.Fc
165.Ft void
166.Fo bn_sqr_recursive
167.Fa "BN_ULONG *r"
168.Fa "BN_ULONG *a"
169.Fa "int n2"
170.Fa "BN_ULONG *tmp"
171.Fc
172.Ft void
173.Fo mul
174.Fa "BN_ULONG r"
175.Fa "BN_ULONG a"
176.Fa "BN_ULONG w"
177.Fa "BN_ULONG c"
178.Fc
179.Ft void
180.Fo mul_add
181.Fa "BN_ULONG r"
182.Fa "BN_ULONG a"
183.Fa "BN_ULONG w"
184.Fa "BN_ULONG c"
185.Fc
186.Ft void
187.Fo sqr
188.Fa "BN_ULONG r0"
189.Fa "BN_ULONG r1"
190.Fa "BN_ULONG a"
191.Fc
192.Ft BIGNUM *
193.Fo bn_expand
194.Fa "BIGNUM *a"
195.Fa "int bits"
196.Fc
197.Ft BIGNUM *
198.Fo bn_wexpand
199.Fa "BIGNUM *a"
200.Fa "int n"
201.Fc
202.Ft BIGNUM *
203.Fo bn_expand2
204.Fa "BIGNUM *a"
205.Fa "int n"
206.Fc
207.Ft void
208.Fo bn_fix_top
209.Fa "BIGNUM *a"
210.Fc
211.Ft void
212.Fo bn_check_top
213.Fa "BIGNUM *a"
214.Fc
215.Ft void
216.Fo bn_print
217.Fa "BIGNUM *a"
218.Fc
219.Ft void
220.Fo bn_dump
221.Fa "BN_ULONG *d"
222.Fa "int n"
223.Fc
224.Ft void
225.Fo bn_set_max
226.Fa "BIGNUM *a"
227.Fc
228.Ft void
229.Fo bn_set_high
230.Fa "BIGNUM *r"
231.Fa "BIGNUM *a"
232.Fa "int n"
233.Fc
234.Ft void
235.Fo bn_set_low
236.Fa "BIGNUM *r"
237.Fa "BIGNUM *a"
238.Fa "int n"
239.Fc
240.Sh DESCRIPTION
241This page documents the internal functions used by the OpenSSL
242.Vt BIGNUM
243implementation.
244They are described here to facilitate debugging and extending the
245library.
246They are
247.Em not
248to be used by applications.
249.Ss The BIGNUM structure
250.Bd -literal
251typedef struct bignum_st BIGNUM;
252
253struct bignum_st {
254 BN_ULONG *d; /* Pointer to an array of 'BN_BITS2' bit chunks. */
255 int top; /* Index of last used d +1. */
256 /* The next are internal book keeping for bn_expand. */
257 int dmax; /* Size of the d array. */
258 int neg; /* one if the number is negative */
259 int flags;
260};
261.Ed
262.Pp
263The integer value is stored in
264.Fa d ,
265a
266.Xr malloc 3 Ap ed
267array of words
268.Pq Vt BN_ULONG ,
269least significant word first.
270A
271.Vt BN_ULONG
272can be either 16, 32 or 64 bits in size, depending on the 'number of
273bits'
274.Pq Dv BITS2
275specified in
276.In openssl/bn.h .
277.Pp
278.Fa dmax
279is the size of the
280.Fa d
281array that has been allocated.
282.Fa top
283is the number of words being used, so for a value of 4, bn.d[0]=4 and
284bn.top=1.
285.Fa neg
286is 1 if the number is negative.
287When a
288.Vt BIGNUM
289is 0, the
290.Fa d
291field can be
292.Dv NULL
293and
294.Fa top
295== 0.
296.Pp
297.Fa flags
298is a bit field of flags which are defined in
299.In openssl/bn.h .
300The flags begin with
301.Dv BN_FLG_ .
302The macros
303.Fn BN_set_flags b n
304and
305.Fn BN_get_flags b n
306exist to enable or fetch flag(s)
307.Fa n
308from a
309.Vt BIGNUM
310structure
311.Fa b .
312.Pp
313Various routines in this library require the use of temporary
314.Vt BIGNUM
315variables during their execution.
316Since dynamic memory allocation to create
317.Vt BIGNUM Ns s
318is rather expensive when used in conjunction with repeated subroutine
319calls, the
320.Vt BN_CTX
321structure is used.
322This structure contains BN_CTX_NUM
323.Vt BIGNUM Ns s,
324see
325.Xr BN_CTX_start 3 .
326.Ss Low-level arithmetic operations
327These functions are implemented in C and for several platforms in
328assembly language:
329.Pp
330.Fn bn_mul_words rp ap num w
331operates on the
332.Fa num
333word arrays
334.Fa rp
335and
336.Fa ap .
337It computes
338.Fa ap
339*
340.Fa w ,
341places the result in
342.Fa rp ,
343and returns the high word (carry).
344.Pp
345.Fn bn_mul_add_words rp ap num w
346operates on the
347.Fa num
348word arrays
349.Fa rp
350and
351.Fa ap .
352It computes
353.Fa ap
354*
355.Fa w
356+
357.Fa rp ,
358places the result in
359.Fa rp ,
360and returns the high word (carry).
361.Pp
362.Fn bn_sqr_words rp ap num
363operates on the
364.Fa num
365word array
366.Fa ap
367and the
368.Pf 2* Fa num
369word array
370.Fa ap .
371It computes
372.Fa ap
373*
374.Fa ap
375word-wise, and places the low and high bytes of the result in
376.Fa rp .
377.Pp
378.Fn bn_div_words h l d
379divides the two word number
380.Pq Fa h , Fa l
381by
382.Fa d
383and returns the result.
384.Pp
385.Fn bn_add_words rp ap bp num
386operates on the
387.Fa num
388word arrays
389.Fa ap ,
390.Fa bp
391and
392.Fa rp .
393It computes
394.Fa ap
395+
396.Fa bp ,
397places the result in
398.Fa rp ,
399and returns the high word (carry).
400.Pp
401.Fn bn_sub_words rp ap bp num
402operates on the
403.Fa num
404word arrays
405.Fa ap ,
406.Fa bp
407and
408.Fa rp .
409It computes
410.Fa ap
411-
412.Fa bp ,
413places the result in
414.Fa rp ,
415and returns the carry (1 if
416.Fa bp
417\(ra
418.Fa ap ,
4190 otherwise).
420.Pp
421.Fn bn_mul_comba4 r a b
422operates on the 4 word arrays
423.Fa a
424and
425.Fa b
426and the 8 word array
427.Fa r .
428It computes
429.Fa a Ns * Ns Fa b
430and places the result in
431.Fa r .
432.Pp
433.Fn bn_mul_comba8 r a b
434operates on the 8 word arrays
435.Fa a
436and
437.Fa b
438and the 16 word array
439.Fa r .
440It computes
441.Fa a Ns * Ns Fa b
442and places the result in
443.Fa r .
444.Pp
445.Fn bn_sqr_comba4 r a b
446operates on the 4 word arrays
447.Fa a
448and
449.Fa b
450and the 8 word array
451.Fa r .
452.Pp
453.Fn bn_sqr_comba8 r a b
454operates on the 8 word arrays
455.Fa a
456and
457.Fa b
458and the 16 word array
459.Fa r .
460.Pp
461The following functions are implemented in C:
462.Pp
463.Fn bn_cmp_words a b n
464operates on the
465.Fa n
466word arrays
467.Fa a
468and
469.Fa b .
470It returns 1, 0 and -1 if
471.Fa a
472is greater than, equal and less than
473.Fa b .
474.Pp
475.Fn bn_mul_normal r a na b nb
476operates on the
477.Fa na
478word array
479.Fa a ,
480the
481.Fa nb
482word array
483.Fa b
484and the
485.Fa na Ns + Ns Fa nb
486word array
487.Fa r .
488It computes
489.Fa a Ns * Ns Fa b
490and places the result in
491.Fa r .
492.Pp
493.Fn bn_mul_low_normal r a b n
494operates on the
495.Fa n
496word arrays
497.Fa r ,
498.Fa a
499and
500.Fa b .
501It computes the
502.Fa n
503low words of
504.Fa a Ns * Ns Fa b
505and places the result in
506.Fa r .
507.Pp
508.Fn bn_mul_recursive r a b n2 dna dnb t
509operates on the word arrays
510.Fa a
511and
512.Fa b
513of length
514.Fa n2 Ns + Ns Fa dna
515and
516.Fa n2 Ns + Ns Fa dnb
517.Pf ( Fa dna
518and
519.Fa dnb
520are currently allowed to be 0 or negative) and the
521.Pf 2* Fa n2
522word arrays
523.Fa r
524and
525.Sy t .
526.Fa n2
527must be a power of 2.
528It computes
529.Fa a Ns * Ns Fa b
530and places the result in
531.Fa r .
532.Pp
533.Fn bn_mul_part_recursive r a b n tna tnb tmp
534operates on the word arrays
535.Fa a
536and
537.Fa b
538of length
539.Fa n Ns + Ns Fa tna
540and
541.Fa n Ns + Ns Fa tnb
542and the
543.Pf 4* Fa n
544word arrays
545.Fa r
546and
547.Fa tmp .
548.Pp
549.Fn bn_mul_low_recursive r a b n2 tmp
550operates on the
551.Fa n2
552word arrays
553.Fa r
554and
555.Fa tmp
556and the
557.Fa n2 Ns /2
558word arrays
559.Fa a
560and
561.Fa b .
562.Pp
563.Fn bn_mul_high r a b l n2 tmp
564operates on the
565.Fa n2
566word arrays
567.Fa r ,
568.Fa a ,
569.Fa b
570and
571.Fa l
572(?) and the
573.Pf 3* Fa n2
574word array
575.Fa tmp .
576.Pp
577.Xr BN_mul 3
578calls
579.Fn bn_mul_normal ,
580or an optimized implementation if the factors have the same size:
581.Fn bn_mul_comba8
582is used if they are 8 words long,
583.Fn bn_mul_recursive
584if they are larger than
585.Dv BN_MULL_SIZE_NORMAL
586and the size is an exact multiple of the word size, and
587.Fn bn_mul_part_recursive
588for others that are larger than
589.Dv BN_MULL_SIZE_NORMAL .
590.Pp
591.Fn bn_sqr_normal r a n tmp
592operates on the
593.Fa n
594word array
595.Fa a
596and the
597.Pf 2* Fa n
598word arrays
599.Fa tmp
600and
601.Fa r .
602.Pp
603The implementations use the following macros which, depending on the
604architecture, may use
605.Vt long long
606C operations or inline assembler.
607They are defined in
608.Pa bn_lcl.h .
609.Pp
610.Fn mul r a w c
611computes
612.Fa w Ns * Ns Fa a Ns + Ns Fa c
613and places the low word of the result in
614.Fa r
615and the high word in
616.Fa c .
617.Pp
618.Fn mul_add r a w c
619computes
620.Fa w Ns * Ns Fa a Ns + Ns Fa r Ns + Ns Fa c
621and places the low word of the result in
622.Fa r
623and the high word in
624.Fa c .
625.Pp
626.Fn sqr r0 r1 a
627computes
628.Fa a Ns * Ns Fa a
629and places the low word of the result in
630.Fa r0
631and the high word in
632.Fa r1 .
633.Ss Size changes
634.Fn bn_expand
635ensures that
636.Fa b
637has enough space for a
638.Fa bits
639bit number.
640.Fn bn_wexpand
641ensures that
642.Fa b
643has enough space for an
644.Fa n
645word number.
646If the number has to be expanded, both macros call
647.Fn bn_expand2 ,
648which allocates a new
649.Fa d
650array and copies the data.
651They return
652.Dv NULL
653on error,
654.Fa b
655otherwise.
656.Pp
657The
658.Fn bn_fix_top
659macro reduces
660.Fa a Ns -> Ns Fa top
661to point to the most significant non-zero word plus one when
662.Fa a
663has shrunk.
664.Ss Debugging
665.Fn bn_check_top
666verifies that
667.Ql ((a)-\(ratop \(ra= 0 && (a)-\(ratop \(la= (a)-\(radmax) .
668A violation will cause the program to abort.
669.Pp
670.Fn bn_print
671prints
672.Fa a
673to
674.Dv stderr .
675.Fn bn_dump
676prints
677.Fa n
678words at
679.Fa d
680(in reverse order, i.e.
681most significant word first) to
682.Dv stderr .
683.Pp
684.Fn bn_set_max
685makes
686.Fa a
687a static number with a
688.Fa dmax
689of its current size.
690This is used by
691.Fn bn_set_low
692and
693.Fn bn_set_high
694to make
695.Fa r
696a read-only
697.Vt BIGNUM
698that contains the
699.Fa n
700low or high words of
701.Fa a .
702.Pp
703If
704.Dv BN_DEBUG
705is not defined,
706.Fn bn_check_top ,
707.Fn bn_print ,
708.Fn bn_dump
709and
710.Fn bn_set_max
711are defined as empty macros.
712.Sh SEE ALSO
713.Xr bn 3
diff --git a/src/lib/libcrypto/man/d2i_PKCS8PrivateKey_bio.3 b/src/lib/libcrypto/man/d2i_PKCS8PrivateKey_bio.3
new file mode 100644
index 0000000000..9eb5fadfab
--- /dev/null
+++ b/src/lib/libcrypto/man/d2i_PKCS8PrivateKey_bio.3
@@ -0,0 +1,97 @@
1.Dd $Mdocdate: November 12 2015 $
2.Dt D2I_PKCS8PRIVATEKEY_BIO 3
3.Os
4.Sh NAME
5.Nm d2i_PKCS8PrivateKey_bio ,
6.Nm d2i_PKCS8PrivateKey_fp ,
7.Nm i2d_PKCS8PrivateKey_bio ,
8.Nm i2d_PKCS8PrivateKey_fp ,
9.Nm i2d_PKCS8PrivateKey_nid_bio ,
10.Nm i2d_PKCS8PrivateKey_nid_fp
11.Nd PKCS#8 format private key functions
12.Sh SYNOPSIS
13.In openssl/evp.h
14.Ft EVP_PKEY *
15.Fo d2i_PKCS8PrivateKey_bio
16.Fa "BIO *bp"
17.Fa "EVP_PKEY **x"
18.Fa "pem_password_cb *cb"
19.Fa "void *u"
20.Fc
21.Ft EVP_PKEY *
22.Fo d2i_PKCS8PrivateKey_fp
23.Fa "FILE *fp"
24.Fa "EVP_PKEY **x"
25.Fa "pem_password_cb *cb"
26.Fa "void *u"
27.Fc
28.Ft int
29.Fo i2d_PKCS8PrivateKey_bio
30.Fa "BIO *bp"
31.Fa "EVP_PKEY *x"
32.Fa "const EVP_CIPHER *enc"
33.Fa "char *kstr"
34.Fa "int klen"
35.Fa "pem_password_cb *cb"
36.Fa "void *u"
37.Fc
38.Ft int
39.Fo i2d_PKCS8PrivateKey_fp
40.Fa "FILE *fp"
41.Fa "EVP_PKEY *x"
42.Fa "const EVP_CIPHER *enc"
43.Fa "char *kstr"
44.Fa "int klen"
45.Fa "pem_password_cb *cb"
46.Fa "void *u"
47.Fc
48.Ft int
49.Fo i2d_PKCS8PrivateKey_nid_bio
50.Fa "BIO *bp"
51.Fa "EVP_PKEY *x"
52.Fa "int nid"
53.Fa "char *kstr"
54.Fa "int klen"
55.Fa "pem_password_cb *cb"
56.Fa "void *u"
57.Fc
58.Ft int
59.Fo i2d_PKCS8PrivateKey_nid_fp
60.Fa "FILE *fp"
61.Fa "EVP_PKEY *x"
62.Fa "int nid"
63.Fa "char *kstr"
64.Fa "int klen"
65.Fa "pem_password_cb *cb"
66.Fa "void *u"
67.Fc
68.Sh DESCRIPTION
69The PKCS#8 functions encode and decode private keys in PKCS#8 format
70using both PKCS#5 v1.5 and PKCS#5 v2.0 password based encryption
71algorithms.
72.Pp
73Other than the use of DER as opposed to PEM these functions are
74identical to the corresponding
75.Xr pem 3
76functions.
77.Sh NOTES
78Before using these functions,
79.Xr OpenSSL_add_all_algorithms 3
80should be called to initialize the internal algorithm lookup tables.
81Otherwise errors about unknown algorithms will occur if an attempt is
82made to decrypt a private key.
83.Pp
84These functions are currently the only way to store encrypted private
85keys using DER format.
86.Pp
87Currently all the functions use
88.Vt BIO
89or
90.Vt FILE
91pointers, there are no functions which work directly on memory:
92this can be readily worked around by converting the buffers to
93memory BIOs, see
94.Xr BIO_s_mem 3
95for details.
96.Sh SEE ALSO
97.Xr pem 3
diff --git a/src/lib/libcrypto/man/des_read_pw.3 b/src/lib/libcrypto/man/des_read_pw.3
new file mode 100644
index 0000000000..e118b43793
--- /dev/null
+++ b/src/lib/libcrypto/man/des_read_pw.3
@@ -0,0 +1,97 @@
1.Dd $Mdocdate: November 12 2015 $
2.Dt DES_READ_PW 3
3.Os
4.Sh NAME
5.Nm des_read_password ,
6.Nm des_read_2passwords ,
7.Nm des_read_pw_string ,
8.Nm des_read_pw
9.Nd Compatibility user interface functions
10.Sh SYNOPSIS
11.In openssl/des_old.h
12.Ft int
13.Fo des_read_password
14.Fa "DES_cblock *key"
15.Fa "const char *prompt"
16.Fa "int verify"
17.Fc
18.Ft int
19.Fo des_read_2passwords
20.Fa "DES_cblock *key1"
21.Fa "DES_cblock *key2"
22.Fa "const char *prompt"
23.Fa "int verify"
24.Fc
25.Ft int
26.Fo des_read_pw_string
27.Fa "char *buf"
28.Fa "int length"
29.Fa "const char *prompt"
30.Fa "int verify"
31.Fc
32.Ft int
33.Fo des_read_pw
34.Fa "char *buf"
35.Fa "char *buff"
36.Fa "int size"
37.Fa "const char *prompt"
38.Fa "int verify"
39.Fc
40.Sh DESCRIPTION
41The DES library contained a few routines to prompt for passwords.
42These aren't necessarily dependent on DES, and have therefore become
43part of the UI compatibility library.
44.Pp
45.Fn des_read_pw
46writes the string specified by
47.Fa prompt
48to standard output turns echo off and reads an input string from the
49terminal.
50The string is returned in
51.Fa buf ,
52which must have space for at least
53.Fa size
54bytes.
55If
56.Fa verify
57is set, the user is asked for the password twice and unless the two
58copies match, an error is returned.
59The second password is stored in
60.Fa buff ,
61which must therefore also be at least
62.Fa size
63bytes.
64A return code of -1 indicates a system error, 1 failure due to use
65interaction, and 0 is success.
66All other functions described here use
67.Fn des_read_pw
68to do the work.
69.Pp
70.Fn des_read_pw_string
71is a variant of
72.Fn des_read_pw
73that provides a buffer for you if
74.Fa verify
75is set.
76.Pp
77.Fn des_read_password
78calls
79.Fn des_read_pw
80and converts the password to a DES key by calling
81.Xr DES_string_to_key 3 ;
82.Fn des_read_2passwords
83operates in the same way as
84.Fn des_read_password
85except that it generates two keys by using the
86.Xr DES_string_to_2key 3
87function.
88.Sh NOTES
89.Fn des_read_pw_string
90is available in the MIT Kerberos library as well, and is also available
91under the name
92.Xr EVP_read_pw_string 3 .
93.Sh SEE ALSO
94.Xr ui_new 3
95.Sh AUTHORS
96.An Richard Levitte Aq Mt richard@levitte.org
97for the OpenSSL project.
diff --git a/src/lib/libcrypto/man/lh_new.3 b/src/lib/libcrypto/man/lh_new.3
new file mode 100644
index 0000000000..2779cf9202
--- /dev/null
+++ b/src/lib/libcrypto/man/lh_new.3
@@ -0,0 +1,430 @@
1.Dd $Mdocdate: November 12 2015 $
2.Dt LH_NEW 3
3.Os
4.Sh NAME
5.Nm lh_new ,
6.Nm lh_free ,
7.Nm lh_insert ,
8.Nm lh_delete ,
9.Nm lh_retrieve ,
10.Nm lh_doall ,
11.Nm lh_doall_arg ,
12.Nm lh_error
13.Nd dynamic hash table
14.Sh SYNOPSIS
15.In openssl/lhash.h
16.Fn DECLARE_LHASH_OF <type>
17.Ft LHASH *
18.Fn lh_<type>_new void
19.Ft void
20.Fo lh_<type>_free
21.Fa "LHASH_OF(<type>) *table"
22.Fc
23.Ft <type> *
24.Fo lh_<type>_insert
25.Fa "LHASH_OF(<type>) *table"
26.Fa "<type> *data"
27.Fc
28.Ft <type> *
29.Fo lh_<type>_delete
30.Fa "LHASH_OF(<type>) *table"
31.Fa "<type> *data"
32.Fc
33.Ft <type> *
34.Fo lh_<type>_retrieve
35.Fa "LHASH_OF<type>) *table"
36.Fa "<type> *data"
37.Fc
38.Ft void
39.Fo lh_<type>_doall
40.Fa "LHASH_OF(<type>) *table"
41.Fa "LHASH_DOALL_FN_TYPE func"
42.Fc
43.Ft void
44.Fo lh_<type>_doall_arg
45.Fa "LHASH_OF(<type>) *table"
46.Fa "LHASH_DOALL_ARG_FN_TYPE func"
47.Fa "<type2>"
48.Fa "<type2> *arg"
49.Fc
50.Ft int
51.Fo lh_<type>_error
52.Fa "LHASH_OF(<type>) *table"
53.Fc
54.Ft typedef int
55.Fo (*LHASH_COMP_FN_TYPE)
56.Fa "const void *"
57.Fa "const void *"
58.Fc
59.Ft typedef unsigned long
60.Fo (*LHASH_HASH_FN_TYPE)
61.Fa "const void *"
62.Fc
63.Ft typedef void
64.Fo (*LHASH_DOALL_FN_TYPE)
65.Fa "const void *"
66.Fc
67.Ft typedef void
68.Fo (*LHASH_DOALL_ARG_FN_TYPE)
69.Fa "const void *"
70.Fa "const void *"
71.Fc
72.Sh DESCRIPTION
73This library implements type-checked dynamic hash tables.
74The hash table entries can be arbitrary structures.
75Usually they consist of key and value fields.
76.Pp
77.Fn lh_<type>_new
78creates a new
79.Vt LHASH_OF(<type>)
80structure to store arbitrary data entries, and provides the hash and
81compare callbacks to be used in organising the table's entries.
82The hash callback takes a pointer to a table entry as its argument
83and returns an unsigned long hash value for its key field.
84The hash value is normally truncated to a power of 2, so make sure that
85your hash function returns well mixed low order bits.
86The compare callback takes two arguments (pointers to two hash table
87entries), and returns 0 if their keys are equal, non-zero otherwise.
88If your hash table will contain items of some particular type and the
89hash and compare callbacks hash and compare these types, then the
90.Fn DECLARE_LHASH_HASH_FN
91and
92.Fn IMPLEMENT_LHASH_COMP_FN
93macros can be used to create callback wrappers of the prototypes
94required by
95.Fn lh_<type>_new .
96These provide per-variable casts before calling the type-specific
97callbacks written by the application author.
98These macros, as well as those used for the doall callbacks, are
99defined as;
100.Bd -literal -offset 2n
101#define DECLARE_LHASH_HASH_FN(name, o_type) \e
102 unsigned long name##_LHASH_HASH(const void *);
103#define IMPLEMENT_LHASH_HASH_FN(name, o_type) \e
104 unsigned long name##_LHASH_HASH(const void *arg) { \e
105 const o_type *a = arg; \e
106 return name##_hash(a); }
107#define LHASH_HASH_FN(name) name##_LHASH_HASH
108
109#define DECLARE_LHASH_COMP_FN(name, o_type) \e
110 int name##_LHASH_COMP(const void *, const void *);
111#define IMPLEMENT_LHASH_COMP_FN(name, o_type) \e
112 int name##_LHASH_COMP(const void *arg1, const void *arg2) { \e
113 const o_type *a = arg1; \e
114 const o_type *b = arg2; \e
115 return name##_cmp(a,b); }
116#define LHASH_COMP_FN(name) name##_LHASH_COMP
117
118#define DECLARE_LHASH_DOALL_FN(name, o_type) \e
119 void name##_LHASH_DOALL(void *);
120#define IMPLEMENT_LHASH_DOALL_FN(name, o_type) \e
121 void name##_LHASH_DOALL(void *arg) { \e
122 o_type *a = arg; \e
123 name##_doall(a); }
124#define LHASH_DOALL_FN(name) name##_LHASH_DOALL
125
126#define DECLARE_LHASH_DOALL_ARG_FN(name, o_type, a_type) \e
127 void name##_LHASH_DOALL_ARG(void *, void *);
128#define IMPLEMENT_LHASH_DOALL_ARG_FN(name, o_type, a_type) \e
129 void name##_LHASH_DOALL_ARG(void *arg1, void *arg2) { \e
130 o_type *a = arg1; \e
131 a_type *b = arg2; \e
132 name##_doall_arg(a, b); }
133#define LHASH_DOALL_ARG_FN(name) name##_LHASH_DOALL_ARG
134.Ed
135.Pp
136An example of a hash table storing (pointers to) structures of type
137\&'STUFF' could be defined as follows;
138.Bd -literal -offset 2n
139/* Calculate the hash value of 'tohash' (implemented elsewhere) */
140unsigned long STUFF_hash(const STUFF *tohash);
141/* Order 'arg1' and 'arg2' (implemented elsewhere) */
142int stuff_cmp(const STUFF *arg1, const STUFF *arg2);
143/* Create type-safe wrapper functions for use in the LHASH internals */
144static IMPLEMENT_LHASH_HASH_FN(stuff, STUFF);
145static IMPLEMENT_LHASH_COMP_FN(stuff, STUFF);
146/* ... */
147int main(int argc, char *argv[]) {
148 /* Create the new hash table using the hash/compare wrappers */
149 LHASH_OF(STUFF) *hashtable =
150 lh_STUFF_new(LHASH_HASH_FN(STUFF_hash),
151 LHASH_COMP_FN(STUFF_cmp));
152 /* ... */
153}
154.Ed
155.Pp
156.Fn lh_<type>_free
157frees the
158.Vt LHASH_OF(<type>)
159structure
160.Fa table .
161Allocated hash table entries will not be freed; consider using
162.Fn lh_<type>_doall
163to deallocate any remaining entries in the hash table (see below).
164.Pp
165.Fn lh_<type>_insert
166inserts the structure pointed to by
167.Fa data
168into
169.Fa table .
170If there already is an entry with the same key, the old value is
171replaced.
172Note that
173.Fn lh_<type>_insert
174stores pointers, the data are not copied.
175.Pp
176.Fn lh_<type>_delete
177deletes an entry from
178.Fa table .
179.Pp
180.Fn lh_<type>_retrieve
181looks up an entry in
182.Fa table .
183Normally,
184.Fa data
185is a structure with the key field(s) set; the function will return a
186pointer to a fully populated structure.
187.Pp
188.Fn lh_<type>_doall
189will, for every entry in the hash table, call
190.Fa func
191with the data item as its parameter.
192For
193.Fn lh_<type>_doall
194and
195.Fn lh_<type>_doall_arg ,
196function pointer casting should be avoided in the callbacks (see
197.Sx NOTES )
198\(em instead use the declare/implement macros to create type-checked
199wrappers that cast variables prior to calling your type-specific
200callbacks.
201An example of this is illustrated here where the callback is used to
202cleanup resources for items in the hash table prior to the hashtable
203itself being deallocated:
204.Bd -literal -offset 2n
205/* Clean up resources belonging to 'a' (this is implemented elsewhere) */
206void STUFF_cleanup_doall(STUFF *a);
207/* Implement a prototype-compatible wrapper for "STUFF_cleanup" */
208IMPLEMENT_LHASH_DOALL_FN(STUFF_cleanup, STUFF)
209 /* ... then later in the code ... */
210/* So to run "STUFF_cleanup" against all items in a hash table ... */
211lh_STUFF_doall(hashtable, LHASH_DOALL_FN(STUFF_cleanup));
212/* Then the hash table itself can be deallocated */
213lh_STUFF_free(hashtable);
214.Ed
215.Pp
216When doing this, be careful if you delete entries from the hash table in
217your callbacks: the table may decrease in size, moving the item that you
218are currently on down lower in the hash table \(em this could cause some
219entries to be skipped during the iteration.
220The second best solution to this problem is to set hash->down_load=0
221before you start (which will stop the hash table ever decreasing in
222size).
223The best solution is probably to avoid deleting items from the hash
224table inside a doall callback!
225.Pp
226.Fn lh_<type>_doall_arg
227is the same as
228.Fn lh_<type>_doall
229except that
230.Fa func
231will be called with
232.Fa arg
233as the second argument and
234.Fa func
235should be of type
236.Vt LHASH_DOALL_ARG_FN_TYPE
237(a callback prototype that is passed both the table entry and an extra
238argument).
239As with
240.Fn lh_<type>_doall ,
241you can instead choose to declare your callback with a prototype
242matching the types you are dealing with and use the declare/implement
243macros to create compatible wrappers that cast variables before calling
244your type-specific callbacks.
245An example of this is demonstrated here (printing all hash table entries
246to a BIO that is provided by the caller):
247.Bd -literal -offset 2n
248/* Print item 'a' to 'output_bio' (this is implemented elsewhere) */
249void STUFF_print_doall_arg(const STUFF *a, BIO *output_bio);
250/* Implement a prototype-compatible wrapper for "STUFF_print" */
251static IMPLEMENT_LHASH_DOALL_ARG_FN(STUFF, const STUFF, BIO)
252 /* ... then later in the code ... */
253/* Print out the entire hashtable to a particular BIO */
254lh_STUFF_doall_arg(hashtable, LHASH_DOALL_ARG_FN(STUFF_print), BIO,
255 logging_bio);
256.Ed
257.Pp
258.Fn lh_<type>_error
259can be used to determine if an error occurred in the last operation.
260.Fn lh_<type>_error
261is a macro.
262.Sh RETURN VALUES
263.Fn lh_<type>_new
264returns
265.Dv NULL
266on error, otherwise a pointer to the new
267.Vt LHASH
268structure.
269.Pp
270When a hash table entry is replaced,
271.Fn lh_<type>_insert
272returns the value being replaced.
273.Dv NULL
274is returned on normal operation and on error.
275.Pp
276.Fn lh_<type>_delete
277returns the entry being deleted.
278.Dv NULL
279is returned if there is no such value in the hash table.
280.Pp
281.Fn lh_<type>_retrieve
282returns the hash table entry if it has been found, or
283.Dv NULL
284otherwise.
285.Pp
286.Fn lh_<type>_error
287returns 1 if an error occurred in the last operation, or 0 otherwise.
288.Pp
289.Fn lh_<type>_free ,
290.Fn lh_<type>_doall ,
291and
292.Fn lh_<type>_doall_arg
293return no values.
294.Sh NOTES
295The various LHASH macros and callback types exist to make it possible to
296write type-checked code without resorting to function-prototype casting
297\(em an evil that makes application code much harder to audit/verify and
298also opens the window of opportunity for stack corruption and other
299hard-to-find bugs.
300It also, apparently, violates ANSI-C.
301.Pp
302The LHASH code regards table entries as constant data.
303As such, it internally represents
304.Fn lh_<type>_insert Ap ed
305items with a
306.Vt const void *
307pointer type.
308This is why callbacks such as those used by
309.Fn lh_<type>_doall
310and
311.Fn lh_<type>_doall_arg
312declare their prototypes with "const", even for the parameters that pass
313back the table items' data pointers \(em for consistency, user-provided
314data is "const" at all times as far as the LHASH code is concerned.
315However, as callers are themselves providing these pointers, they can
316choose whether they too should be treating all such parameters as
317constant.
318.Pp
319As an example, a hash table may be maintained by code that, for
320reasons of encapsulation, has only "const" access to the data being
321indexed in the hash table (i.e. it is returned as "const" from
322elsewhere in their code) \(em in this case the LHASH prototypes are
323appropriate as-is.
324Conversely, if the caller is responsible for the life-time of the data
325in question, then they may well wish to make modifications to table item
326passed back in the
327.Fn lh_<type>_doall
328or
329.Fn lh_<type>_doall_arg
330callbacks (see the "STUFF_cleanup" example above).
331If so, the caller can either cast the "const" away (if they're providing
332the raw callbacks themselves) or use the macros to declare/implement the
333wrapper functions without "const" types.
334.Pp
335Callers that only have "const" access to data they are indexing in a
336table, yet declare callbacks without constant types (or cast the "const"
337away themselves), are therefore creating their own risks/bugs without
338being encouraged to do so by the API.
339On a related note, those auditing code should pay special attention
340to any instances of DECLARE/IMPLEMENT_LHASH_DOALL_[ARG_]_FN macros
341that provide types without any "const" qualifiers.
342.Sh INTERNALS
343The following description is based on the SSLeay documentation:
344.Pp
345The lhash library implements a hash table described in the
346.Em Communications of the ACM
347in 1991.
348What makes this hash table different is that as the table fills,
349the hash table is increased (or decreased) in size via
350.Xr OPENSSL_realloc 3 .
351When a 'resize' is done, instead of all hashes being redistributed over
352twice as many 'buckets', one bucket is split.
353So when an 'expand' is done, there is only a minimal cost to
354redistribute some values.
355Subsequent inserts will cause more single 'bucket' redistributions but
356there will never be a sudden large cost due to redistributing all the
357\&'buckets'.
358.Pp
359The state for a particular hash table is kept in the
360.Vt LHASH
361structure.
362The decision to increase or decrease the hash table size is made
363depending on the 'load' of the hash table.
364The load is the number of items in the hash table divided by the size of
365the hash table.
366The default values are as follows.
367If (hash->up_load < load) => expand.
368if (hash->down_load > load) => contract.
369The
370.Fa up_load
371has a default value of 1 and
372.Fa down_load
373has a default value of 2.
374These numbers can be modified by the application by just playing
375with the
376.Fa up_load
377and
378.Fa down_load
379variables.
380The 'load' is kept in a form which is multiplied by 256.
381So hash->up_load=8*256 will cause a load of 8 to be set.
382.Pp
383If you are interested in performance the field to watch is
384.Fa num_comp_calls .
385The hash library keeps track of the 'hash' value for each item so when a
386lookup is done, the 'hashes' are compared, if there is a match, then a
387full compare is done, and hash->num_comp_calls is incremented.
388If num_comp_calls is not equal to num_delete plus num_retrieve it means
389that your hash function is generating hashes that are the same for
390different values.
391It is probably worth changing your hash function if this is the case
392because even if your hash table has 10 items in a 'bucket', it can be
393searched with 10
394.Vt unsigned long
395compares and 10 linked list traverses.
396This will be much less expensive that 10 calls to your compare function.
397.Pp
398.Fn lh_strhash
399is a demo string hashing function:
400.Pp
401.Dl unsigned long lh_strhash(const char *c);
402.Pp
403Since the LHASH routines would normally be passed structures, this
404routine would not normally be passed to
405.Fn lh_<type>_new ,
406rather it would be used in the function passed to
407.Fn lh_<type>_new .
408.Sh SEE ALSO
409.Xr lh_stats 3
410.Sh HISTORY
411The lhash library is available in all versions of SSLeay and OpenSSL.
412.Fn lh_<type>_error
413was added in SSLeay 0.9.1b.
414.Pp
415In OpenSSL 0.9.7, all lhash functions that were passed function pointers
416were changed for better type safety, and the function types
417.Vt LHASH_COMP_FN_TYPE ,
418.Vt LHASH_HASH_FN_TYPE ,
419.Vt LHASH_DOALL_FN_TYPE ,
420and
421.Vt LHASH_DOALL_ARG_FN_TYPE
422became available.
423.Pp
424In OpenSSL 1.0.0, the lhash interface was revamped for even better type
425checking.
426.Sh BUGS
427.Fn lh_<type>_insert
428returns
429.Dv NULL
430both for success and error.
diff --git a/src/lib/libcrypto/man/ui_new.3 b/src/lib/libcrypto/man/ui_new.3
new file mode 100644
index 0000000000..d841c212d8
--- /dev/null
+++ b/src/lib/libcrypto/man/ui_new.3
@@ -0,0 +1,384 @@
1.Dd $Mdocdate: November 12 2015 $
2.Dt UI_NEW 3
3.Os
4.Sh NAME
5.Nm UI_new ,
6.Nm UI_new_method ,
7.Nm UI_free ,
8.Nm UI_add_input_string ,
9.Nm UI_dup_input_string ,
10.Nm UI_add_verify_string ,
11.Nm UI_dup_verify_string ,
12.Nm UI_add_input_boolean ,
13.Nm UI_dup_input_boolean ,
14.Nm UI_add_info_string ,
15.Nm UI_dup_info_string ,
16.Nm UI_add_error_string ,
17.Nm UI_dup_error_string ,
18.Nm UI_construct_prompt ,
19.Nm UI_add_user_data ,
20.Nm UI_get0_user_data ,
21.Nm UI_get0_result ,
22.Nm UI_process ,
23.Nm UI_ctrl ,
24.Nm UI_set_default_method ,
25.Nm UI_get_default_method ,
26.Nm UI_get_method ,
27.Nm UI_set_method ,
28.Nm UI_OpenSSL ,
29.Nm ERR_load_UI_strings
30.Nd New User Interface
31.Sh SYNOPSIS
32.In openssl/ui.h
33.Fd typedef struct ui_st UI;
34.Fd typedef struct ui_method_st UI_METHOD;
35.Ft UI *
36.Fn UI_new void
37.Ft UI *
38.Fo UI_new_method
39.Fa "const UI_METHOD *method"
40.Fc
41.Ft void
42.Fo UI_free
43.Fa "UI *ui"
44.Fc
45.Ft int
46.Fo UI_add_input_string
47.Fa "UI *ui"
48.Fa "const char *prompt"
49.Fa "int flags"
50.Fa "char *result_buf"
51.Fa "int minsize"
52.Fa "int maxsize"
53.Fc
54.Ft int
55.Fo UI_dup_input_string
56.Fa "UI *ui"
57.Fa "const char *prompt"
58.Fa "int flags"
59.Fa "char *result_buf"
60.Fa "int minsize"
61.Fa "int maxsize"
62.Fc
63.Ft int
64.Fo UI_add_verify_string
65.Fa "UI *ui"
66.Fa "const char *prompt"
67.Fa "int flags"
68.Fa "char *result_buf"
69.Fa "int minsize"
70.Fa "int maxsize"
71.Fa "const char *test_buf"
72.Fc
73.Ft int
74.Fo UI_dup_verify_string
75.Fa "UI *ui"
76.Fa "const char *prompt"
77.Fa "int flags"
78.Fa "char *result_buf"
79.Fa "int minsize"
80.Fa "int maxsize"
81.Fa "const char *test_buf"
82.Fc
83.Ft int
84.Fo UI_add_input_boolean
85.Fa "UI *ui"
86.Fa "const char *prompt"
87.Fa "const char *action_desc"
88.Fa "const char *ok_chars"
89.Fa "const char *cancel_chars"
90.Fa "int flags"
91.Fa "char *result_buf"
92.Fc
93.Ft int
94.Fo UI_dup_input_boolean
95.Fa "UI *ui"
96.Fa "const char *prompt"
97.Fa "const char *action_desc"
98.Fa "const char *ok_chars"
99.Fa "const char *cancel_chars"
100.Fa "int flags"
101.Fa "char *result_buf"
102.Fc
103.Ft int
104.Fo UI_add_info_string
105.Fa "UI *ui"
106.Fa "const char *text"
107.Fc
108.Ft int
109.Fo UI_dup_info_string
110.Fa "UI *ui"
111.Fa "const char *text"
112.Fc
113.Ft int
114.Fo UI_add_error_string
115.Fa "UI *ui"
116.Fa "const char *text"
117.Fc
118.Ft int
119.Fo UI_dup_error_string
120.Fa "UI *ui"
121.Fa "const char *text"
122.Fc
123.Fd /* These are the possible flags. They can be OR'ed together. */
124.Fd #define UI_INPUT_FLAG_ECHO 0x01
125.Fd #define UI_INPUT_FLAG_DEFAULT_PWD 0x02
126.Ft char *
127.Fo UI_construct_prompt
128.Fa "UI *ui_method"
129.Fa "const char *object_desc"
130.Fa "const char *object_name"
131.Fc
132.Ft void *
133.Fo UI_add_user_data
134.Fa "UI *ui"
135.Fa "void *user_data"
136.Fc
137.Ft void *
138.Fo UI_get0_user_data
139.Fa "UI *ui"
140.Fc
141.Ft const char *
142.Fo UI_get0_result
143.Fa "UI *ui"
144.Fa "int i"
145.Fc
146.Ft int
147.Fo UI_process
148.Fa "UI *ui"
149.Fc
150.Ft int
151.Fo UI_ctrl
152.Fa "UI *ui"
153.Fa "int cmd"
154.Fa "long i"
155.Fa "void *p"
156.Fa "void (*f)()"
157.Fc
158.Fd #define UI_CTRL_PRINT_ERRORS 1
159.Fd #define UI_CTRL_IS_REDOABLE 2
160.Ft void
161.Fo UI_set_default_method
162.Fa "const UI_METHOD *meth"
163.Fc
164.Ft const UI_METHOD *
165.Fo UI_get_default_method
166.Fa void
167.Fc
168.Ft const UI_METHOD *
169.Fo UI_get_method
170.Fa "UI *ui"
171.Fc
172.Ft const UI_METHOD *
173.Fo UI_set_method
174.Fa "UI *ui"
175.Fa "const UI_METHOD *meth"
176.Fc
177.Ft UI_METHOD *
178.Fo UI_OpenSSL
179.Fa void
180.Fc
181.Sh DESCRIPTION
182UI stands for User Interface, and is general purpose set of routines
183to prompt the user for text-based information.
184Through user-written methods (see
185.Xr ui_create 3 Ns ),
186prompting can be done in any way imaginable, be it plain text prompting,
187through dialog boxes or from a cell phone.
188.Pp
189All the functions work through a context of the type
190.Vt UI .
191This context contains all the information needed to prompt correctly
192as well as a reference to a
193.Vt UI_METHOD ,
194which is an ordered vector of functions that carry out the actual
195prompting.
196.Pp
197The first thing to do is to create a
198.Vt UI
199with
200.Fn UI_new
201or
202.Fn UI_new_method ,
203then add information to it with the
204.Fn UI_add_*
205or
206.Fn UI_dup_*
207functions.
208Also, user-defined random data can be passed down to the underlying
209method through calls to
210.Fn UI_add_user_data .
211The default UI method doesn't care about these data, but other methods
212might.
213Finally, use
214.Fn UI_process
215to actually perform the prompting and
216.Fn UI_get0_result
217to find the result to the prompt.
218.Pp
219A
220.Vt UI
221can contain more than one prompt, which are performed in the given
222sequence.
223Each prompt gets an index number which is returned by the
224.Fn UI_add_*
225and
226.Fn UI_dup_*
227functions, and has to be used to get the corresponding result with
228.Fn UI_get0_result .
229.Pp
230The functions are as follows:
231.Pp
232.Fn UI_new
233creates a new
234.Vt UI
235using the default UI method.
236When done with this UI, it should be freed using
237.Fn UI_free .
238.Pp
239.Fn UI_new_method
240creates a new
241.Vt UI
242using the given UI method.
243When done with this UI, it should be freed using
244.Fn UI_free .
245.Pp
246.Fn UI_OpenSSL
247returns the built-in UI method (note: not the default one, since
248the default can be changed.
249See further on).
250This method is the most machine/OS dependent part of OpenSSL and
251normally generates the most problems when porting.
252.Pp
253.Fn UI_free
254removes
255.Fa ui
256from memory, along with all other pieces of memory that are connected
257to it, like duplicated input strings, results and others.
258.Pp
259.Fn UI_add_input_string
260and
261.Fn UI_add_verify_string
262add a prompt to
263.Fa ui ,
264as well as flags and a result buffer and the desired minimum and
265maximum sizes of the result.
266The given information is used to prompt for information, for example
267a password, and to verify a password (i.e. having the user enter
268it twice and check that the same string was entered twice).
269.Fn UI_add_verify_string
270takes and extra argument that should be a pointer to the result buffer
271of the input string that it's supposed to verify, or verification will
272fail.
273.Pp
274.Fn UI_add_input_boolean
275adds a prompt to
276.Fa ui
277that's supposed to be answered in a boolean way, with a single
278character for yes and a different character for no.
279A set of characters that can be used to cancel the prompt is given as
280well.
281The prompt itself is really divided in two, one part being the
282descriptive text (given through the
283.Fa prompt
284argument) and one describing the possible answers (given through the
285.Fa action_desc
286argument).
287.Pp
288.Fn UI_add_info_string
289and
290.Fn UI_add_error_string
291add strings that are shown at the same time as the prompt for extra
292information or to show an error string.
293The difference between the two is only conceptual.
294With the builtin method, there's no technical difference between them.
295Other methods may make a difference between them, however.
296.Pp
297The flags currently supported are
298.Dv UI_INPUT_FLAG_ECHO,
299which is relevant for
300.Fn UI_add_input_string
301and will have the users response be echoed (when prompting for a
302password, this flag should obviously not be used), and
303.Dv UI_INPUT_FLAG_DEFAULT_PWD ,
304which means that a default password of some sort will be used
305(completely depending on the application and the UI method).
306.Pp
307.Fn UI_dup_input_string ,
308.Fn UI_dup_verify_string ,
309.Fn UI_dup_input_boolean ,
310.Fn UI_dup_info_string ,
311and
312.Fn UI_dup_error_string
313are basically the same as their
314.Fn UI_add_*
315counterparts, except that they make their own copies of all strings.
316.Pp
317.Fn UI_construct_prompt
318is a helper function that can be used to create a prompt from two pieces
319of information: an description and a name.
320The default constructor (if there is none provided by the method used)
321creates a string "Enter
322.Em description
323for
324.Em name Ns :".
325With the description "pass phrase" and the file name "foo.key", that
326becomes "Enter pass phrase for foo.key:". Other methods may create
327whatever string and may include encodings that will be processed by the
328other method functions.
329.Pp
330.Fn UI_add_user_data
331adds a piece of memory for the method to use at any time.
332The builtin UI method doesn't care about this info.
333Note that several calls to this function doesn't add data, it replaces
334the previous blob with the one given as argument.
335.Pp
336.Fn UI_get0_user_data
337retrieves the data that has last been given to the
338.Fa ui
339with
340.Fn UI_add_user_data .
341.Pp
342.Fn UI_get0_result
343returns a pointer to the result buffer associated with the information
344indexed by
345.Fa i .
346.Pp
347.Fn UI_process
348goes through the information given so far, does all the printing and
349prompting and returns.
350.Pp
351.Fn UI_ctrl
352adds extra control for the application author.
353For now, it understands two commands:
354.Dv UI_CTRL_PRINT_ERRORS ,
355which makes
356.Fn UI_process
357print the OpenSSL error stack as part of processing the
358.Fa ui ,
359and
360.Dv UI_CTRL_IS_REDOABLE ,
361which returns a flag saying if the used
362.Fa ui
363can be used again or not.
364.Pp
365.Fn UI_set_default_method
366changes the default UI method to the one given.
367.Pp
368.Fn UI_get_default_method
369returns a pointer to the current default UI method.
370.Pp
371.Fn UI_get_method
372returns the UI method associated with a given
373.Fa ui .
374.Pp
375.Fn UI_set_method
376changes the UI method associated with a given
377.Fa ui .
378.Sh SEE ALSO
379.Xr des_read_pw 3
380.Sh HISTORY
381The UI section was first introduced in OpenSSL 0.9.7.
382.Sh AUTHORS
383.An Richard Levitte Aq Mt richard@levitte.org
384for the OpenSSL project.
diff --git a/src/lib/libssl/src/doc/crypto/bn_internal.pod b/src/lib/libssl/src/doc/crypto/bn_internal.pod
deleted file mode 100644
index 9c59ed623b..0000000000
--- a/src/lib/libssl/src/doc/crypto/bn_internal.pod
+++ /dev/null
@@ -1,238 +0,0 @@
1=pod
2
3=head1 NAME
4
5bn_mul_words, bn_mul_add_words, bn_sqr_words, bn_div_words,
6bn_add_words, bn_sub_words, bn_mul_comba4, bn_mul_comba8,
7bn_sqr_comba4, bn_sqr_comba8, bn_cmp_words, bn_mul_normal,
8bn_mul_low_normal, bn_mul_recursive, bn_mul_part_recursive,
9bn_mul_low_recursive, bn_mul_high, bn_sqr_normal, bn_sqr_recursive,
10bn_expand, bn_wexpand, bn_expand2, bn_fix_top, bn_check_top,
11bn_print, bn_dump, bn_set_max, bn_set_high, bn_set_low, sqr
12- BIGNUM library internal functions
13
14=head1 SYNOPSIS
15
16 #include <openssl/bn.h>
17
18 BN_ULONG bn_mul_words(BN_ULONG *rp, BN_ULONG *ap, int num, BN_ULONG w);
19 BN_ULONG bn_mul_add_words(BN_ULONG *rp, BN_ULONG *ap, int num,
20 BN_ULONG w);
21 void bn_sqr_words(BN_ULONG *rp, BN_ULONG *ap, int num);
22 BN_ULONG bn_div_words(BN_ULONG h, BN_ULONG l, BN_ULONG d);
23 BN_ULONG bn_add_words(BN_ULONG *rp, BN_ULONG *ap, BN_ULONG *bp,
24 int num);
25 BN_ULONG bn_sub_words(BN_ULONG *rp, BN_ULONG *ap, BN_ULONG *bp,
26 int num);
27
28 void bn_mul_comba4(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b);
29 void bn_mul_comba8(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b);
30 void bn_sqr_comba4(BN_ULONG *r, BN_ULONG *a);
31 void bn_sqr_comba8(BN_ULONG *r, BN_ULONG *a);
32
33 int bn_cmp_words(BN_ULONG *a, BN_ULONG *b, int n);
34
35 void bn_mul_normal(BN_ULONG *r, BN_ULONG *a, int na, BN_ULONG *b,
36 int nb);
37 void bn_mul_low_normal(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, int n);
38 void bn_mul_recursive(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, int n2,
39 int dna,int dnb,BN_ULONG *tmp);
40 void bn_mul_part_recursive(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b,
41 int n, int tna,int tnb, BN_ULONG *tmp);
42 void bn_mul_low_recursive(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b,
43 int n2, BN_ULONG *tmp);
44 void bn_mul_high(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, BN_ULONG *l,
45 int n2, BN_ULONG *tmp);
46
47 void bn_sqr_normal(BN_ULONG *r, BN_ULONG *a, int n, BN_ULONG *tmp);
48 void bn_sqr_recursive(BN_ULONG *r, BN_ULONG *a, int n2, BN_ULONG *tmp);
49
50 void mul(BN_ULONG r, BN_ULONG a, BN_ULONG w, BN_ULONG c);
51 void mul_add(BN_ULONG r, BN_ULONG a, BN_ULONG w, BN_ULONG c);
52 void sqr(BN_ULONG r0, BN_ULONG r1, BN_ULONG a);
53
54 BIGNUM *bn_expand(BIGNUM *a, int bits);
55 BIGNUM *bn_wexpand(BIGNUM *a, int n);
56 BIGNUM *bn_expand2(BIGNUM *a, int n);
57 void bn_fix_top(BIGNUM *a);
58
59 void bn_check_top(BIGNUM *a);
60 void bn_print(BIGNUM *a);
61 void bn_dump(BN_ULONG *d, int n);
62 void bn_set_max(BIGNUM *a);
63 void bn_set_high(BIGNUM *r, BIGNUM *a, int n);
64 void bn_set_low(BIGNUM *r, BIGNUM *a, int n);
65
66=head1 DESCRIPTION
67
68This page documents the internal functions used by the OpenSSL
69B<BIGNUM> implementation. They are described here to facilitate
70debugging and extending the library. They are I<not> to be used by
71applications.
72
73=head2 The BIGNUM structure
74
75 typedef struct bignum_st BIGNUM;
76
77 struct bignum_st
78 {
79 BN_ULONG *d; /* Pointer to an array of 'BN_BITS2' bit chunks. */
80 int top; /* Index of last used d +1. */
81 /* The next are internal book keeping for bn_expand. */
82 int dmax; /* Size of the d array. */
83 int neg; /* one if the number is negative */
84 int flags;
85 };
86
87
88The integer value is stored in B<d>, a malloc()ed array of words (B<BN_ULONG>),
89least significant word first. A B<BN_ULONG> can be either 16, 32 or 64 bits
90in size, depending on the 'number of bits' (B<BITS2>) specified in
91C<openssl/bn.h>.
92
93B<dmax> is the size of the B<d> array that has been allocated. B<top>
94is the number of words being used, so for a value of 4, bn.d[0]=4 and
95bn.top=1. B<neg> is 1 if the number is negative. When a B<BIGNUM> is
96B<0>, the B<d> field can be B<NULL> and B<top> == B<0>.
97
98B<flags> is a bit field of flags which are defined in C<openssl/bn.h>. The
99flags begin with B<BN_FLG_>. The macros BN_set_flags(b,n) and
100BN_get_flags(b,n) exist to enable or fetch flag(s) B<n> from B<BIGNUM>
101structure B<b>.
102
103Various routines in this library require the use of temporary
104B<BIGNUM> variables during their execution. Since dynamic memory
105allocation to create B<BIGNUM>s is rather expensive when used in
106conjunction with repeated subroutine calls, the B<BN_CTX> structure is
107used. This structure contains B<BN_CTX_NUM> B<BIGNUM>s, see
108L<BN_CTX_start(3)|BN_CTX_start(3)>.
109
110=head2 Low-level arithmetic operations
111
112These functions are implemented in C and for several platforms in
113assembly language:
114
115bn_mul_words(B<rp>, B<ap>, B<num>, B<w>) operates on the B<num> word
116arrays B<rp> and B<ap>. It computes B<ap> * B<w>, places the result
117in B<rp>, and returns the high word (carry).
118
119bn_mul_add_words(B<rp>, B<ap>, B<num>, B<w>) operates on the B<num>
120word arrays B<rp> and B<ap>. It computes B<ap> * B<w> + B<rp>, places
121the result in B<rp>, and returns the high word (carry).
122
123bn_sqr_words(B<rp>, B<ap>, B<n>) operates on the B<num> word array
124B<ap> and the 2*B<num> word array B<ap>. It computes B<ap> * B<ap>
125word-wise, and places the low and high bytes of the result in B<rp>.
126
127bn_div_words(B<h>, B<l>, B<d>) divides the two word number (B<h>,B<l>)
128by B<d> and returns the result.
129
130bn_add_words(B<rp>, B<ap>, B<bp>, B<num>) operates on the B<num> word
131arrays B<ap>, B<bp> and B<rp>. It computes B<ap> + B<bp>, places the
132result in B<rp>, and returns the high word (carry).
133
134bn_sub_words(B<rp>, B<ap>, B<bp>, B<num>) operates on the B<num> word
135arrays B<ap>, B<bp> and B<rp>. It computes B<ap> - B<bp>, places the
136result in B<rp>, and returns the carry (1 if B<bp> E<gt> B<ap>, 0
137otherwise).
138
139bn_mul_comba4(B<r>, B<a>, B<b>) operates on the 4 word arrays B<a> and
140B<b> and the 8 word array B<r>. It computes B<a>*B<b> and places the
141result in B<r>.
142
143bn_mul_comba8(B<r>, B<a>, B<b>) operates on the 8 word arrays B<a> and
144B<b> and the 16 word array B<r>. It computes B<a>*B<b> and places the
145result in B<r>.
146
147bn_sqr_comba4(B<r>, B<a>, B<b>) operates on the 4 word arrays B<a> and
148B<b> and the 8 word array B<r>.
149
150bn_sqr_comba8(B<r>, B<a>, B<b>) operates on the 8 word arrays B<a> and
151B<b> and the 16 word array B<r>.
152
153The following functions are implemented in C:
154
155bn_cmp_words(B<a>, B<b>, B<n>) operates on the B<n> word arrays B<a>
156and B<b>. It returns 1, 0 and -1 if B<a> is greater than, equal and
157less than B<b>.
158
159bn_mul_normal(B<r>, B<a>, B<na>, B<b>, B<nb>) operates on the B<na>
160word array B<a>, the B<nb> word array B<b> and the B<na>+B<nb> word
161array B<r>. It computes B<a>*B<b> and places the result in B<r>.
162
163bn_mul_low_normal(B<r>, B<a>, B<b>, B<n>) operates on the B<n> word
164arrays B<r>, B<a> and B<b>. It computes the B<n> low words of
165B<a>*B<b> and places the result in B<r>.
166
167bn_mul_recursive(B<r>, B<a>, B<b>, B<n2>, B<dna>, B<dnb>, B<t>) operates
168on the word arrays B<a> and B<b> of length B<n2>+B<dna> and B<n2>+B<dnb>
169(B<dna> and B<dnb> are currently allowed to be 0 or negative) and the 2*B<n2>
170word arrays B<r> and B<t>. B<n2> must be a power of 2. It computes
171B<a>*B<b> and places the result in B<r>.
172
173bn_mul_part_recursive(B<r>, B<a>, B<b>, B<n>, B<tna>, B<tnb>, B<tmp>)
174operates on the word arrays B<a> and B<b> of length B<n>+B<tna> and
175B<n>+B<tnb> and the 4*B<n> word arrays B<r> and B<tmp>.
176
177bn_mul_low_recursive(B<r>, B<a>, B<b>, B<n2>, B<tmp>) operates on the
178B<n2> word arrays B<r> and B<tmp> and the B<n2>/2 word arrays B<a>
179and B<b>.
180
181bn_mul_high(B<r>, B<a>, B<b>, B<l>, B<n2>, B<tmp>) operates on the
182B<n2> word arrays B<r>, B<a>, B<b> and B<l> (?) and the 3*B<n2> word
183array B<tmp>.
184
185BN_mul() calls bn_mul_normal(), or an optimized implementation if the
186factors have the same size: bn_mul_comba8() is used if they are 8
187words long, bn_mul_recursive() if they are larger than
188B<BN_MULL_SIZE_NORMAL> and the size is an exact multiple of the word
189size, and bn_mul_part_recursive() for others that are larger than
190B<BN_MULL_SIZE_NORMAL>.
191
192bn_sqr_normal(B<r>, B<a>, B<n>, B<tmp>) operates on the B<n> word array
193B<a> and the 2*B<n> word arrays B<tmp> and B<r>.
194
195The implementations use the following macros which, depending on the
196architecture, may use "long long" C operations or inline assembler.
197They are defined in C<bn_lcl.h>.
198
199mul(B<r>, B<a>, B<w>, B<c>) computes B<w>*B<a>+B<c> and places the
200low word of the result in B<r> and the high word in B<c>.
201
202mul_add(B<r>, B<a>, B<w>, B<c>) computes B<w>*B<a>+B<r>+B<c> and
203places the low word of the result in B<r> and the high word in B<c>.
204
205sqr(B<r0>, B<r1>, B<a>) computes B<a>*B<a> and places the low word
206of the result in B<r0> and the high word in B<r1>.
207
208=head2 Size changes
209
210bn_expand() ensures that B<b> has enough space for a B<bits> bit
211number. bn_wexpand() ensures that B<b> has enough space for an
212B<n> word number. If the number has to be expanded, both macros
213call bn_expand2(), which allocates a new B<d> array and copies the
214data. They return B<NULL> on error, B<b> otherwise.
215
216The bn_fix_top() macro reduces B<a-E<gt>top> to point to the most
217significant non-zero word plus one when B<a> has shrunk.
218
219=head2 Debugging
220
221bn_check_top() verifies that C<((a)-E<gt>top E<gt>= 0 && (a)-E<gt>top
222E<lt>= (a)-E<gt>dmax)>. A violation will cause the program to abort.
223
224bn_print() prints B<a> to stderr. bn_dump() prints B<n> words at B<d>
225(in reverse order, i.e. most significant word first) to stderr.
226
227bn_set_max() makes B<a> a static number with a B<dmax> of its current size.
228This is used by bn_set_low() and bn_set_high() to make B<r> a read-only
229B<BIGNUM> that contains the B<n> low or high words of B<a>.
230
231If B<BN_DEBUG> is not defined, bn_check_top(), bn_print(), bn_dump()
232and bn_set_max() are defined as empty macros.
233
234=head1 SEE ALSO
235
236L<bn(3)|bn(3)>
237
238=cut
diff --git a/src/lib/libssl/src/doc/crypto/d2i_PKCS8PrivateKey.pod b/src/lib/libssl/src/doc/crypto/d2i_PKCS8PrivateKey.pod
deleted file mode 100644
index fc7335c7a1..0000000000
--- a/src/lib/libssl/src/doc/crypto/d2i_PKCS8PrivateKey.pod
+++ /dev/null
@@ -1,58 +0,0 @@
1=pod
2
3=head1 NAME
4
5d2i_PKCS8PrivateKey_bio, d2i_PKCS8PrivateKey_fp, i2d_PKCS8PrivateKey_bio,
6i2d_PKCS8PrivateKey_fp, i2d_PKCS8PrivateKey_nid_bio, i2d_PKCS8PrivateKey_nid_fp
7- PKCS#8 format private key functions
8
9=head1 SYNOPSIS
10
11 #include <openssl/evp.h>
12
13 EVP_PKEY *d2i_PKCS8PrivateKey_bio(BIO *bp, EVP_PKEY **x, pem_password_cb *cb, void *u);
14 EVP_PKEY *d2i_PKCS8PrivateKey_fp(FILE *fp, EVP_PKEY **x, pem_password_cb *cb, void *u);
15
16 int i2d_PKCS8PrivateKey_bio(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc,
17 char *kstr, int klen,
18 pem_password_cb *cb, void *u);
19
20 int i2d_PKCS8PrivateKey_fp(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc,
21 char *kstr, int klen,
22 pem_password_cb *cb, void *u);
23
24 int i2d_PKCS8PrivateKey_nid_bio(BIO *bp, EVP_PKEY *x, int nid,
25 char *kstr, int klen,
26 pem_password_cb *cb, void *u);
27
28 int i2d_PKCS8PrivateKey_nid_fp(FILE *fp, EVP_PKEY *x, int nid,
29 char *kstr, int klen,
30 pem_password_cb *cb, void *u);
31
32=head1 DESCRIPTION
33
34The PKCS#8 functions encode and decode private keys in PKCS#8 format using both
35PKCS#5 v1.5 and PKCS#5 v2.0 password based encryption algorithms.
36
37Other than the use of DER as opposed to PEM these functions are identical to the
38corresponding B<PEM> function as described in the L<pem(3)|pem(3)> manual page.
39
40=head1 NOTES
41
42Before using these functions
43L<OpenSSL_add_all_algorithms(3)|OpenSSL_add_all_algorithms(3)> should be called
44to initialize the internal algorithm lookup tables otherwise errors about
45unknown algorithms will occur if an attempt is made to decrypt a private key.
46
47These functions are currently the only way to store encrypted private keys
48using DER format.
49
50Currently all the functions use BIOs or FILE pointers, there are no functions
51which work directly on memory: this can be readily worked around by converting
52the buffers to memory BIOs, see L<BIO_s_mem(3)|BIO_s_mem(3)> for details.
53
54=head1 SEE ALSO
55
56L<pem(3)|pem(3)>
57
58=cut
diff --git a/src/lib/libssl/src/doc/crypto/ecdsa.pod b/src/lib/libssl/src/doc/crypto/ecdsa.pod
deleted file mode 100644
index 9e9608155a..0000000000
--- a/src/lib/libssl/src/doc/crypto/ecdsa.pod
+++ /dev/null
@@ -1,205 +0,0 @@
1=pod
2
3=head1 NAME
4
5ECDSA_SIG_new, ECDSA_SIG_free, i2d_ECDSA_SIG, d2i_ECDSA_SIG,
6ECDSA_size, ECDSA_sign_setup, ECDSA_sign, ECDSA_sign_ex,
7ECDSA_verify, ECDSA_do_sign, ECDSA_do_sign_ex, ECDSA_do_verify,
8ECDSA_OpenSSL, ECDSA_get_default_method, ECDSA_get_ex_data,
9ECDSA_get_ex_new_index, ECDSA_set_default_method, ECDSA_set_ex_data,
10ECDSA_set_method - Elliptic Curve Digital Signature Algorithm
11
12=head1 SYNOPSIS
13
14 #include <openssl/ecdsa.h>
15
16 ECDSA_SIG* ECDSA_SIG_new(void);
17 void ECDSA_SIG_free(ECDSA_SIG *sig);
18 int i2d_ECDSA_SIG(const ECDSA_SIG *sig, unsigned char **pp);
19 ECDSA_SIG* d2i_ECDSA_SIG(ECDSA_SIG **sig, const unsigned char **pp,
20 long len);
21
22 ECDSA_SIG* ECDSA_do_sign(const unsigned char *dgst, int dgst_len,
23 EC_KEY *eckey);
24 ECDSA_SIG* ECDSA_do_sign_ex(const unsigned char *dgst, int dgstlen,
25 const BIGNUM *kinv, const BIGNUM *rp,
26 EC_KEY *eckey);
27 int ECDSA_do_verify(const unsigned char *dgst, int dgst_len,
28 const ECDSA_SIG *sig, EC_KEY* eckey);
29 int ECDSA_sign_setup(EC_KEY *eckey, BN_CTX *ctx,
30 BIGNUM **kinv, BIGNUM **rp);
31 int ECDSA_sign(int type, const unsigned char *dgst,
32 int dgstlen, unsigned char *sig,
33 unsigned int *siglen, EC_KEY *eckey);
34 int ECDSA_sign_ex(int type, const unsigned char *dgst,
35 int dgstlen, unsigned char *sig,
36 unsigned int *siglen, const BIGNUM *kinv,
37 const BIGNUM *rp, EC_KEY *eckey);
38 int ECDSA_verify(int type, const unsigned char *dgst,
39 int dgstlen, const unsigned char *sig,
40 int siglen, EC_KEY *eckey);
41 int ECDSA_size(const EC_KEY *eckey);
42
43 const ECDSA_METHOD* ECDSA_OpenSSL(void);
44 void ECDSA_set_default_method(const ECDSA_METHOD *meth);
45 const ECDSA_METHOD* ECDSA_get_default_method(void);
46 int ECDSA_set_method(EC_KEY *eckey,const ECDSA_METHOD *meth);
47
48 int ECDSA_get_ex_new_index(long argl, void *argp,
49 CRYPTO_EX_new *new_func,
50 CRYPTO_EX_dup *dup_func,
51 CRYPTO_EX_free *free_func);
52 int ECDSA_set_ex_data(EC_KEY *d, int idx, void *arg);
53 void* ECDSA_get_ex_data(EC_KEY *d, int idx);
54
55=head1 DESCRIPTION
56
57The B<ECDSA_SIG> structure consists of two BIGNUMs for the
58r and s value of a ECDSA signature (see X9.62 or FIPS 186-2).
59
60 struct
61 {
62 BIGNUM *r;
63 BIGNUM *s;
64 } ECDSA_SIG;
65
66ECDSA_SIG_new() allocates a new B<ECDSA_SIG> structure (note: this
67function also allocates the BIGNUMs) and initialize it.
68
69ECDSA_SIG_free() frees the B<ECDSA_SIG> structure B<sig>.
70
71i2d_ECDSA_SIG() creates the DER encoding of the ECDSA signature
72B<sig> and writes the encoded signature to B<*pp> (note: if B<pp>
73is NULL B<i2d_ECDSA_SIG> returns the expected length in bytes of
74the DER encoded signature). B<i2d_ECDSA_SIG> returns the length
75of the DER encoded signature (or 0 on error).
76
77d2i_ECDSA_SIG() decodes a DER encoded ECDSA signature and returns
78the decoded signature in a newly allocated B<ECDSA_SIG> structure.
79B<*sig> points to the buffer containing the DER encoded signature
80of size B<len>.
81
82ECDSA_size() returns the maximum length of a DER encoded
83ECDSA signature created with the private EC key B<eckey>.
84
85ECDSA_sign_setup() may be used to precompute parts of the
86signing operation. B<eckey> is the private EC key and B<ctx>
87is a pointer to B<BN_CTX> structure (or NULL). The precomputed
88values or returned in B<kinv> and B<rp> and can be used in a
89later call to B<ECDSA_sign_ex> or B<ECDSA_do_sign_ex>.
90
91ECDSA_sign() is wrapper function for ECDSA_sign_ex with B<kinv>
92and B<rp> set to NULL.
93
94ECDSA_sign_ex() computes a digital signature of the B<dgstlen> bytes
95hash value B<dgst> using the private EC key B<eckey> and the optional
96pre-computed values B<kinv> and B<rp>. The DER encoded signatures is
97stored in B<sig> and it's length is returned in B<sig_len>. Note: B<sig>
98must point to B<ECDSA_size> bytes of memory. The parameter B<type>
99is ignored.
100
101ECDSA_verify() verifies that the signature in B<sig> of size
102B<siglen> is a valid ECDSA signature of the hash value
103B<dgst> of size B<dgstlen> using the public key B<eckey>.
104The parameter B<type> is ignored.
105
106ECDSA_do_sign() is wrapper function for ECDSA_do_sign_ex with B<kinv>
107and B<rp> set to NULL.
108
109ECDSA_do_sign_ex() computes a digital signature of the B<dgst_len>
110bytes hash value B<dgst> using the private key B<eckey> and the
111optional pre-computed values B<kinv> and B<rp>. The signature is
112returned in a newly allocated B<ECDSA_SIG> structure (or NULL on error).
113
114ECDSA_do_verify() verifies that the signature B<sig> is a valid
115ECDSA signature of the hash value B<dgst> of size B<dgst_len>
116using the public key B<eckey>.
117
118=head1 RETURN VALUES
119
120ECDSA_size() returns the maximum length signature or 0 on error.
121
122ECDSA_sign_setup() and ECDSA_sign() return 1 if successful or 0
123on error.
124
125ECDSA_verify() and ECDSA_do_verify() return 1 for a valid
126signature, 0 for an invalid signature and -1 on error.
127The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
128
129=head1 EXAMPLES
130
131Creating a ECDSA signature of given SHA-1 hash value using the
132named curve secp192k1.
133
134First step: create a EC_KEY object (note: this part is B<not> ECDSA
135specific)
136
137 int ret;
138 ECDSA_SIG *sig;
139 EC_KEY *eckey;
140
141 eckey = EC_KEY_new_by_curve_name(NID_secp192k1);
142 if (eckey == NULL) {
143 /* error */
144 }
145 if (!EC_KEY_generate_key(eckey)) {
146 /* error */
147 }
148
149Second step: compute the ECDSA signature of a SHA-1 hash value
150using B<ECDSA_do_sign>
151
152 sig = ECDSA_do_sign(digest, 20, eckey);
153 if (sig == NULL) {
154 /* error */
155 }
156
157or using B<ECDSA_sign>
158
159 unsigned char *buffer, *pp;
160 int buf_len;
161
162 buf_len = ECDSA_size(eckey);
163 buffer = malloc(buf_len);
164 pp = buffer;
165 if (!ECDSA_sign(0, dgst, dgstlen, pp, &buf_len, eckey) {
166 /* error */
167 }
168
169Third step: verify the created ECDSA signature using B<ECDSA_do_verify>
170
171 ret = ECDSA_do_verify(digest, 20, sig, eckey);
172
173or using B<ECDSA_verify>
174
175 ret = ECDSA_verify(0, digest, 20, buffer, buf_len, eckey);
176
177and finally evaluate the return value:
178
179 if (ret == -1) {
180 /* error */
181 } else if (ret == 0) {
182 /* incorrect signature */
183 } else {
184 /* ret == 1 */
185 /* signature ok */
186 }
187
188=head1 CONFORMING TO
189
190ANSI X9.62, US Federal Information Processing Standard FIPS 186-2
191(Digital Signature Standard, DSS)
192
193=head1 SEE ALSO
194
195L<dsa(3)|dsa(3)>, L<rsa(3)|rsa(3)>
196
197=head1 HISTORY
198
199The ecdsa implementation was first introduced in OpenSSL 0.9.8
200
201=head1 AUTHOR
202
203Nils Larsch for the OpenSSL project (http://www.openssl.org).
204
205=cut
diff --git a/src/lib/libssl/src/doc/crypto/lhash.pod b/src/lib/libssl/src/doc/crypto/lhash.pod
deleted file mode 100644
index a9c44dd9ef..0000000000
--- a/src/lib/libssl/src/doc/crypto/lhash.pod
+++ /dev/null
@@ -1,303 +0,0 @@
1=pod
2
3=head1 NAME
4
5lh_new, lh_free, lh_insert, lh_delete, lh_retrieve, lh_doall, lh_doall_arg,
6lh_error - dynamic hash table
7
8=head1 SYNOPSIS
9
10 #include <openssl/lhash.h>
11
12 DECLARE_LHASH_OF(<type>);
13
14 LHASH *lh_<type>_new();
15 void lh_<type>_free(LHASH_OF(<type> *table);
16
17 <type> *lh_<type>_insert(LHASH_OF(<type> *table, <type> *data);
18 <type> *lh_<type>_delete(LHASH_OF(<type> *table, <type> *data);
19 <type> *lh_retrieve(LHASH_OF<type> *table, <type> *data);
20
21 void lh_<type>_doall(LHASH_OF(<type> *table, LHASH_DOALL_FN_TYPE func);
22 void lh_<type>_doall_arg(LHASH_OF(<type> *table, LHASH_DOALL_ARG_FN_TYPE func,
23 <type2>, <type2> *arg);
24
25 int lh_<type>_error(LHASH_OF(<type> *table);
26
27 typedef int (*LHASH_COMP_FN_TYPE)(const void *, const void *);
28 typedef unsigned long (*LHASH_HASH_FN_TYPE)(const void *);
29 typedef void (*LHASH_DOALL_FN_TYPE)(const void *);
30 typedef void (*LHASH_DOALL_ARG_FN_TYPE)(const void *, const void *);
31
32=head1 DESCRIPTION
33
34This library implements type-checked dynamic hash tables. The hash
35table entries can be arbitrary structures. Usually they consist of key
36and value fields.
37
38lh_<type>_new() creates a new B<LHASH_OF(<type>> structure to store
39arbitrary data entries, and provides the 'hash' and 'compare'
40callbacks to be used in organising the table's entries. The B<hash>
41callback takes a pointer to a table entry as its argument and returns
42an unsigned long hash value for its key field. The hash value is
43normally truncated to a power of 2, so make sure that your hash
44function returns well mixed low order bits. The B<compare> callback
45takes two arguments (pointers to two hash table entries), and returns
460 if their keys are equal, non-zero otherwise. If your hash table
47will contain items of some particular type and the B<hash> and
48B<compare> callbacks hash/compare these types, then the
49B<DECLARE_LHASH_HASH_FN> and B<IMPLEMENT_LHASH_COMP_FN> macros can be
50used to create callback wrappers of the prototypes required by
51lh_<type>_new(). These provide per-variable casts before calling the
52type-specific callbacks written by the application author. These
53macros, as well as those used for the "doall" callbacks, are defined
54as;
55
56 #define DECLARE_LHASH_HASH_FN(name, o_type) \
57 unsigned long name##_LHASH_HASH(const void *);
58 #define IMPLEMENT_LHASH_HASH_FN(name, o_type) \
59 unsigned long name##_LHASH_HASH(const void *arg) { \
60 const o_type *a = arg; \
61 return name##_hash(a); }
62 #define LHASH_HASH_FN(name) name##_LHASH_HASH
63
64 #define DECLARE_LHASH_COMP_FN(name, o_type) \
65 int name##_LHASH_COMP(const void *, const void *);
66 #define IMPLEMENT_LHASH_COMP_FN(name, o_type) \
67 int name##_LHASH_COMP(const void *arg1, const void *arg2) { \
68 const o_type *a = arg1; \
69 const o_type *b = arg2; \
70 return name##_cmp(a,b); }
71 #define LHASH_COMP_FN(name) name##_LHASH_COMP
72
73 #define DECLARE_LHASH_DOALL_FN(name, o_type) \
74 void name##_LHASH_DOALL(void *);
75 #define IMPLEMENT_LHASH_DOALL_FN(name, o_type) \
76 void name##_LHASH_DOALL(void *arg) { \
77 o_type *a = arg; \
78 name##_doall(a); }
79 #define LHASH_DOALL_FN(name) name##_LHASH_DOALL
80
81 #define DECLARE_LHASH_DOALL_ARG_FN(name, o_type, a_type) \
82 void name##_LHASH_DOALL_ARG(void *, void *);
83 #define IMPLEMENT_LHASH_DOALL_ARG_FN(name, o_type, a_type) \
84 void name##_LHASH_DOALL_ARG(void *arg1, void *arg2) { \
85 o_type *a = arg1; \
86 a_type *b = arg2; \
87 name##_doall_arg(a, b); }
88 #define LHASH_DOALL_ARG_FN(name) name##_LHASH_DOALL_ARG
89
90 An example of a hash table storing (pointers to) structures of type 'STUFF'
91 could be defined as follows;
92
93 /* Calculates the hash value of 'tohash' (implemented elsewhere) */
94 unsigned long STUFF_hash(const STUFF *tohash);
95 /* Orders 'arg1' and 'arg2' (implemented elsewhere) */
96 int stuff_cmp(const STUFF *arg1, const STUFF *arg2);
97 /* Create the type-safe wrapper functions for use in the LHASH internals */
98 static IMPLEMENT_LHASH_HASH_FN(stuff, STUFF);
99 static IMPLEMENT_LHASH_COMP_FN(stuff, STUFF);
100 /* ... */
101 int main(int argc, char *argv[]) {
102 /* Create the new hash table using the hash/compare wrappers */
103 LHASH_OF(STUFF) *hashtable = lh_STUFF_new(LHASH_HASH_FN(STUFF_hash),
104 LHASH_COMP_FN(STUFF_cmp));
105 /* ... */
106 }
107
108lh_<type>_free() frees the B<LHASH_OF(<type>> structure
109B<table>. Allocated hash table entries will not be freed; consider
110using lh_<type>_doall() to deallocate any remaining entries in the
111hash table (see below).
112
113lh_<type>_insert() inserts the structure pointed to by B<data> into
114B<table>. If there already is an entry with the same key, the old
115value is replaced. Note that lh_<type>_insert() stores pointers, the
116data are not copied.
117
118lh_<type>_delete() deletes an entry from B<table>.
119
120lh_<type>_retrieve() looks up an entry in B<table>. Normally, B<data>
121is a structure with the key field(s) set; the function will return a
122pointer to a fully populated structure.
123
124lh_<type>_doall() will, for every entry in the hash table, call
125B<func> with the data item as its parameter. For lh_<type>_doall()
126and lh_<type>_doall_arg(), function pointer casting should be avoided
127in the callbacks (see B<NOTE>) - instead use the declare/implement
128macros to create type-checked wrappers that cast variables prior to
129calling your type-specific callbacks. An example of this is
130illustrated here where the callback is used to cleanup resources for
131items in the hash table prior to the hashtable itself being
132deallocated:
133
134 /* Cleans up resources belonging to 'a' (this is implemented elsewhere) */
135 void STUFF_cleanup_doall(STUFF *a);
136 /* Implement a prototype-compatible wrapper for "STUFF_cleanup" */
137 IMPLEMENT_LHASH_DOALL_FN(STUFF_cleanup, STUFF)
138 /* ... then later in the code ... */
139 /* So to run "STUFF_cleanup" against all items in a hash table ... */
140 lh_STUFF_doall(hashtable, LHASH_DOALL_FN(STUFF_cleanup));
141 /* Then the hash table itself can be deallocated */
142 lh_STUFF_free(hashtable);
143
144When doing this, be careful if you delete entries from the hash table
145in your callbacks: the table may decrease in size, moving the item
146that you are currently on down lower in the hash table - this could
147cause some entries to be skipped during the iteration. The second
148best solution to this problem is to set hash-E<gt>down_load=0 before
149you start (which will stop the hash table ever decreasing in size).
150The best solution is probably to avoid deleting items from the hash
151table inside a "doall" callback!
152
153lh_<type>_doall_arg() is the same as lh_<type>_doall() except that
154B<func> will be called with B<arg> as the second argument and B<func>
155should be of type B<LHASH_DOALL_ARG_FN_TYPE> (a callback prototype
156that is passed both the table entry and an extra argument). As with
157lh_doall(), you can instead choose to declare your callback with a
158prototype matching the types you are dealing with and use the
159declare/implement macros to create compatible wrappers that cast
160variables before calling your type-specific callbacks. An example of
161this is demonstrated here (printing all hash table entries to a BIO
162that is provided by the caller):
163
164 /* Prints item 'a' to 'output_bio' (this is implemented elsewhere) */
165 void STUFF_print_doall_arg(const STUFF *a, BIO *output_bio);
166 /* Implement a prototype-compatible wrapper for "STUFF_print" */
167 static IMPLEMENT_LHASH_DOALL_ARG_FN(STUFF, const STUFF, BIO)
168 /* ... then later in the code ... */
169 /* Print out the entire hashtable to a particular BIO */
170 lh_STUFF_doall_arg(hashtable, LHASH_DOALL_ARG_FN(STUFF_print), BIO,
171 logging_bio);
172
173lh_<type>_error() can be used to determine if an error occurred in the last
174operation. lh_<type>_error() is a macro.
175
176=head1 RETURN VALUES
177
178lh_<type>_new() returns B<NULL> on error, otherwise a pointer to the new
179B<LHASH> structure.
180
181When a hash table entry is replaced, lh_<type>_insert() returns the value
182being replaced. B<NULL> is returned on normal operation and on error.
183
184lh_<type>_delete() returns the entry being deleted. B<NULL> is returned if
185there is no such value in the hash table.
186
187lh_<type>_retrieve() returns the hash table entry if it has been found,
188B<NULL> otherwise.
189
190lh_<type>_error() returns 1 if an error occurred in the last operation, 0
191otherwise.
192
193lh_<type>_free(), lh_<type>_doall() and lh_<type>_doall_arg() return no values.
194
195=head1 NOTE
196
197The various LHASH macros and callback types exist to make it possible
198to write type-checked code without resorting to function-prototype
199casting - an evil that makes application code much harder to
200audit/verify and also opens the window of opportunity for stack
201corruption and other hard-to-find bugs. It also, apparently, violates
202ANSI-C.
203
204The LHASH code regards table entries as constant data. As such, it
205internally represents lh_insert()'d items with a "const void *"
206pointer type. This is why callbacks such as those used by lh_doall()
207and lh_doall_arg() declare their prototypes with "const", even for the
208parameters that pass back the table items' data pointers - for
209consistency, user-provided data is "const" at all times as far as the
210LHASH code is concerned. However, as callers are themselves providing
211these pointers, they can choose whether they too should be treating
212all such parameters as constant.
213
214As an example, a hash table may be maintained by code that, for
215reasons of encapsulation, has only "const" access to the data being
216indexed in the hash table (ie. it is returned as "const" from
217elsewhere in their code) - in this case the LHASH prototypes are
218appropriate as-is. Conversely, if the caller is responsible for the
219life-time of the data in question, then they may well wish to make
220modifications to table item passed back in the lh_doall() or
221lh_doall_arg() callbacks (see the "STUFF_cleanup" example above). If
222so, the caller can either cast the "const" away (if they're providing
223the raw callbacks themselves) or use the macros to declare/implement
224the wrapper functions without "const" types.
225
226Callers that only have "const" access to data they're indexing in a
227table, yet declare callbacks without constant types (or cast the
228"const" away themselves), are therefore creating their own risks/bugs
229without being encouraged to do so by the API. On a related note,
230those auditing code should pay special attention to any instances of
231DECLARE/IMPLEMENT_LHASH_DOALL_[ARG_]_FN macros that provide types
232without any "const" qualifiers.
233
234=head1 BUGS
235
236lh_<type>_insert() returns B<NULL> both for success and error.
237
238=head1 INTERNALS
239
240The following description is based on the SSLeay documentation:
241
242The B<lhash> library implements a hash table described in the
243I<Communications of the ACM> in 1991. What makes this hash table
244different is that as the table fills, the hash table is increased (or
245decreased) in size via OPENSSL_realloc(). When a 'resize' is done, instead of
246all hashes being redistributed over twice as many 'buckets', one
247bucket is split. So when an 'expand' is done, there is only a minimal
248cost to redistribute some values. Subsequent inserts will cause more
249single 'bucket' redistributions but there will never be a sudden large
250cost due to redistributing all the 'buckets'.
251
252The state for a particular hash table is kept in the B<LHASH> structure.
253The decision to increase or decrease the hash table size is made
254depending on the 'load' of the hash table. The load is the number of
255items in the hash table divided by the size of the hash table. The
256default values are as follows. If (hash->up_load E<lt> load) =E<gt>
257expand. if (hash-E<gt>down_load E<gt> load) =E<gt> contract. The
258B<up_load> has a default value of 1 and B<down_load> has a default value
259of 2. These numbers can be modified by the application by just
260playing with the B<up_load> and B<down_load> variables. The 'load' is
261kept in a form which is multiplied by 256. So
262hash-E<gt>up_load=8*256; will cause a load of 8 to be set.
263
264If you are interested in performance the field to watch is
265num_comp_calls. The hash library keeps track of the 'hash' value for
266each item so when a lookup is done, the 'hashes' are compared, if
267there is a match, then a full compare is done, and
268hash-E<gt>num_comp_calls is incremented. If num_comp_calls is not equal
269to num_delete plus num_retrieve it means that your hash function is
270generating hashes that are the same for different values. It is
271probably worth changing your hash function if this is the case because
272even if your hash table has 10 items in a 'bucket', it can be searched
273with 10 B<unsigned long> compares and 10 linked list traverses. This
274will be much less expensive that 10 calls to your compare function.
275
276lh_strhash() is a demo string hashing function:
277
278 unsigned long lh_strhash(const char *c);
279
280Since the B<LHASH> routines would normally be passed structures, this
281routine would not normally be passed to lh_<type>_new(), rather it would be
282used in the function passed to lh_<type>_new().
283
284=head1 SEE ALSO
285
286L<lh_stats(3)|lh_stats(3)>
287
288=head1 HISTORY
289
290The B<lhash> library is available in all versions of SSLeay and OpenSSL.
291lh_error() was added in SSLeay 0.9.1b.
292
293This manpage is derived from the SSLeay documentation.
294
295In OpenSSL 0.9.7, all lhash functions that were passed function pointers
296were changed for better type safety, and the function types LHASH_COMP_FN_TYPE,
297LHASH_HASH_FN_TYPE, LHASH_DOALL_FN_TYPE and LHASH_DOALL_ARG_FN_TYPE
298became available.
299
300In OpenSSL 1.0.0, the lhash interface was revamped for even better
301type checking.
302
303=cut
diff --git a/src/lib/libssl/src/doc/crypto/ui.pod b/src/lib/libssl/src/doc/crypto/ui.pod
deleted file mode 100644
index 6df68d604a..0000000000
--- a/src/lib/libssl/src/doc/crypto/ui.pod
+++ /dev/null
@@ -1,194 +0,0 @@
1=pod
2
3=head1 NAME
4
5UI_new, UI_new_method, UI_free, UI_add_input_string, UI_dup_input_string,
6UI_add_verify_string, UI_dup_verify_string, UI_add_input_boolean,
7UI_dup_input_boolean, UI_add_info_string, UI_dup_info_string,
8UI_add_error_string, UI_dup_error_string, UI_construct_prompt,
9UI_add_user_data, UI_get0_user_data, UI_get0_result, UI_process,
10UI_ctrl, UI_set_default_method, UI_get_default_method, UI_get_method,
11UI_set_method, UI_OpenSSL, ERR_load_UI_strings - New User Interface
12
13=head1 SYNOPSIS
14
15 #include <openssl/ui.h>
16
17 typedef struct ui_st UI;
18 typedef struct ui_method_st UI_METHOD;
19
20 UI *UI_new(void);
21 UI *UI_new_method(const UI_METHOD *method);
22 void UI_free(UI *ui);
23
24 int UI_add_input_string(UI *ui, const char *prompt, int flags,
25 char *result_buf, int minsize, int maxsize);
26 int UI_dup_input_string(UI *ui, const char *prompt, int flags,
27 char *result_buf, int minsize, int maxsize);
28 int UI_add_verify_string(UI *ui, const char *prompt, int flags,
29 char *result_buf, int minsize, int maxsize, const char *test_buf);
30 int UI_dup_verify_string(UI *ui, const char *prompt, int flags,
31 char *result_buf, int minsize, int maxsize, const char *test_buf);
32 int UI_add_input_boolean(UI *ui, const char *prompt, const char *action_desc,
33 const char *ok_chars, const char *cancel_chars,
34 int flags, char *result_buf);
35 int UI_dup_input_boolean(UI *ui, const char *prompt, const char *action_desc,
36 const char *ok_chars, const char *cancel_chars,
37 int flags, char *result_buf);
38 int UI_add_info_string(UI *ui, const char *text);
39 int UI_dup_info_string(UI *ui, const char *text);
40 int UI_add_error_string(UI *ui, const char *text);
41 int UI_dup_error_string(UI *ui, const char *text);
42
43 /* These are the possible flags. They can be or'ed together. */
44 #define UI_INPUT_FLAG_ECHO 0x01
45 #define UI_INPUT_FLAG_DEFAULT_PWD 0x02
46
47 char *UI_construct_prompt(UI *ui_method,
48 const char *object_desc, const char *object_name);
49
50 void *UI_add_user_data(UI *ui, void *user_data);
51 void *UI_get0_user_data(UI *ui);
52
53 const char *UI_get0_result(UI *ui, int i);
54
55 int UI_process(UI *ui);
56
57 int UI_ctrl(UI *ui, int cmd, long i, void *p, void (*f)());
58 #define UI_CTRL_PRINT_ERRORS 1
59 #define UI_CTRL_IS_REDOABLE 2
60
61 void UI_set_default_method(const UI_METHOD *meth);
62 const UI_METHOD *UI_get_default_method(void);
63 const UI_METHOD *UI_get_method(UI *ui);
64 const UI_METHOD *UI_set_method(UI *ui, const UI_METHOD *meth);
65
66 UI_METHOD *UI_OpenSSL(void);
67
68=head1 DESCRIPTION
69
70UI stands for User Interface, and is general purpose set of routines to
71prompt the user for text-based information. Through user-written methods
72(see L<ui_create(3)|ui_create(3)>), prompting can be done in any way
73imaginable, be it plain text prompting, through dialog boxes or from a
74cell phone.
75
76All the functions work through a context of the type UI. This context
77contains all the information needed to prompt correctly as well as a
78reference to a UI_METHOD, which is an ordered vector of functions that
79carry out the actual prompting.
80
81The first thing to do is to create a UI with UI_new() or UI_new_method(),
82then add information to it with the UI_add or UI_dup functions. Also,
83user-defined random data can be passed down to the underlying method
84through calls to UI_add_user_data. The default UI method doesn't care
85about these data, but other methods might. Finally, use UI_process()
86to actually perform the prompting and UI_get0_result() to find the result
87to the prompt.
88
89A UI can contain more than one prompt, which are performed in the given
90sequence. Each prompt gets an index number which is returned by the
91UI_add and UI_dup functions, and has to be used to get the corresponding
92result with UI_get0_result().
93
94The functions are as follows:
95
96UI_new() creates a new UI using the default UI method. When done with
97this UI, it should be freed using UI_free().
98
99UI_new_method() creates a new UI using the given UI method. When done with
100this UI, it should be freed using UI_free().
101
102UI_OpenSSL() returns the built-in UI method (note: not the default one,
103since the default can be changed. See further on). This method is the
104most machine/OS dependent part of OpenSSL and normally generates the
105most problems when porting.
106
107UI_free() removes a UI from memory, along with all other pieces of memory
108that's connected to it, like duplicated input strings, results and others.
109
110UI_add_input_string() and UI_add_verify_string() add a prompt to the UI,
111as well as flags and a result buffer and the desired minimum and maximum
112sizes of the result. The given information is used to prompt for
113information, for example a password, and to verify a password (i.e. having
114the user enter it twice and check that the same string was entered twice).
115UI_add_verify_string() takes and extra argument that should be a pointer
116to the result buffer of the input string that it's supposed to verify, or
117verification will fail.
118
119UI_add_input_boolean() adds a prompt to the UI that's supposed to be answered
120in a boolean way, with a single character for yes and a different character
121for no. A set of characters that can be used to cancel the prompt is given
122as well. The prompt itself is really divided in two, one part being the
123descriptive text (given through the I<prompt> argument) and one describing
124the possible answers (given through the I<action_desc> argument).
125
126UI_add_info_string() and UI_add_error_string() add strings that are shown at
127the same time as the prompt for extra information or to show an error string.
128The difference between the two is only conceptual. With the builtin method,
129there's no technical difference between them. Other methods may make a
130difference between them, however.
131
132The flags currently supported are UI_INPUT_FLAG_ECHO, which is relevant for
133UI_add_input_string() and will have the users response be echoed (when
134prompting for a password, this flag should obviously not be used, and
135UI_INPUT_FLAG_DEFAULT_PWD, which means that a default password of some
136sort will be used (completely depending on the application and the UI
137method).
138
139UI_dup_input_string(), UI_dup_verify_string(), UI_dup_input_boolean(),
140UI_dup_info_string() and UI_dup_error_string() are basically the same
141as their UI_add counterparts, except that they make their own copies
142of all strings.
143
144UI_construct_prompt() is a helper function that can be used to create
145a prompt from two pieces of information: an description and a name.
146The default constructor (if there is none provided by the method used)
147creates a string "Enter I<description> for I<name>:". With the
148description "pass phrase" and the file name "foo.key", that becomes
149"Enter pass phrase for foo.key:". Other methods may create whatever
150string and may include encodings that will be processed by the other
151method functions.
152
153UI_add_user_data() adds a piece of memory for the method to use at any
154time. The builtin UI method doesn't care about this info. Note that several
155calls to this function doesn't add data, it replaces the previous blob
156with the one given as argument.
157
158UI_get0_user_data() retrieves the data that has last been given to the
159UI with UI_add_user_data().
160
161UI_get0_result() returns a pointer to the result buffer associated with
162the information indexed by I<i>.
163
164UI_process() goes through the information given so far, does all the printing
165and prompting and returns.
166
167UI_ctrl() adds extra control for the application author. For now, it
168understands two commands: UI_CTRL_PRINT_ERRORS, which makes UI_process()
169print the OpenSSL error stack as part of processing the UI, and
170UI_CTRL_IS_REDOABLE, which returns a flag saying if the used UI can
171be used again or not.
172
173UI_set_default_method() changes the default UI method to the one given.
174
175UI_get_default_method() returns a pointer to the current default UI method.
176
177UI_get_method() returns the UI method associated with a given UI.
178
179UI_set_method() changes the UI method associated with a given UI.
180
181=head1 SEE ALSO
182
183L<ui_create(3)|ui_create(3)>, L<ui_compat(3)|ui_compat(3)>
184
185=head1 HISTORY
186
187The UI section was first introduced in OpenSSL 0.9.7.
188
189=head1 AUTHOR
190
191Richard Levitte (richard@levitte.org) for the OpenSSL project
192(http://www.openssl.org).
193
194=cut
diff --git a/src/lib/libssl/src/doc/crypto/ui_compat.pod b/src/lib/libssl/src/doc/crypto/ui_compat.pod
deleted file mode 100644
index 4ef5465539..0000000000
--- a/src/lib/libssl/src/doc/crypto/ui_compat.pod
+++ /dev/null
@@ -1,57 +0,0 @@
1=pod
2
3=head1 NAME
4
5des_read_password, des_read_2passwords, des_read_pw_string, des_read_pw -
6Compatibility user interface functions
7
8=head1 SYNOPSIS
9
10 #include <openssl/des_old.h>
11
12 int des_read_password(DES_cblock *key,const char *prompt,int verify);
13 int des_read_2passwords(DES_cblock *key1,DES_cblock *key2,
14 const char *prompt,int verify);
15
16 int des_read_pw_string(char *buf,int length,const char *prompt,int verify);
17 int des_read_pw(char *buf,char *buff,int size,const char *prompt,int verify);
18
19=head1 DESCRIPTION
20
21The DES library contained a few routines to prompt for passwords. These
22aren't necessarily dependent on DES, and have therefore become part of the
23UI compatibility library.
24
25des_read_pw() writes the string specified by I<prompt> to standard output
26turns echo off and reads an input string from the terminal. The string is
27returned in I<buf>, which must have space for at least I<size> bytes.
28If I<verify> is set, the user is asked for the password twice and unless
29the two copies match, an error is returned. The second password is stored
30in I<buff>, which must therefore also be at least I<size> bytes. A return
31code of -1 indicates a system error, 1 failure due to use interaction, and
320 is success. All other functions described here use des_read_pw() to do
33the work.
34
35des_read_pw_string() is a variant of des_read_pw() that provides a buffer
36for you if I<verify> is set.
37
38des_read_password() calls des_read_pw() and converts the password to a
39DES key by calling DES_string_to_key(); des_read_2password() operates in
40the same way as des_read_password() except that it generates two keys
41by using the DES_string_to_2key() function.
42
43=head1 NOTES
44
45des_read_pw_string() is available in the MIT Kerberos library as well, and
46is also available under the name EVP_read_pw_string().
47
48=head1 SEE ALSO
49
50L<ui(3)|ui(3)>, L<ui_create(3)|ui_create(3)>
51
52=head1 AUTHOR
53
54Richard Levitte (richard@levitte.org) for the OpenSSL project
55(http://www.openssl.org).
56
57=cut
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-03-22 04:18:59 +0000