diff options
| -rw-r--r-- | lib/libcrypto/man/ECDSA_SIG_new.3 | 396 | ||||
| -rw-r--r-- | lib/libcrypto/man/Makefile | 192 | ||||
| -rw-r--r-- | lib/libcrypto/man/bn_dump.3 | 713 | ||||
| -rw-r--r-- | lib/libcrypto/man/d2i_PKCS8PrivateKey_bio.3 | 97 | ||||
| -rw-r--r-- | lib/libcrypto/man/des_read_pw.3 | 97 | ||||
| -rw-r--r-- | lib/libcrypto/man/lh_new.3 | 430 | ||||
| -rw-r--r-- | lib/libcrypto/man/ui_new.3 | 384 | ||||
| -rw-r--r-- | lib/libssl/src/doc/crypto/bn_internal.pod | 238 | ||||
| -rw-r--r-- | lib/libssl/src/doc/crypto/d2i_PKCS8PrivateKey.pod | 58 | ||||
| -rw-r--r-- | lib/libssl/src/doc/crypto/ecdsa.pod | 205 | ||||
| -rw-r--r-- | lib/libssl/src/doc/crypto/lhash.pod | 303 | ||||
| -rw-r--r-- | lib/libssl/src/doc/crypto/ui.pod | 194 | ||||
| -rw-r--r-- | lib/libssl/src/doc/crypto/ui_compat.pod | 57 |
13 files changed, 2210 insertions, 1154 deletions
diff --git a/lib/libcrypto/man/ECDSA_SIG_new.3 b/lib/libcrypto/man/ECDSA_SIG_new.3 new file mode 100644 index 00000000000..422ccdeb422 --- /dev/null +++ b/lib/libcrypto/man/ECDSA_SIG_new.3 @@ -0,0 +1,396 @@ +.Dd $Mdocdate: November 12 2015 $ +.Dt ECDSA_SIG_NEW 3 +.Os +.Sh NAME +.Nm ECDSA_SIG_new , +.Nm ECDSA_SIG_free , +.Nm i2d_ECDSA_SIG , +.Nm d2i_ECDSA_SIG , +.Nm ECDSA_size , +.Nm ECDSA_sign_setup , +.Nm ECDSA_sign , +.Nm ECDSA_sign_ex , +.Nm ECDSA_verify , +.Nm ECDSA_do_sign , +.Nm ECDSA_do_sign_ex , +.Nm ECDSA_do_verify , +.Nm ECDSA_OpenSSL , +.Nm ECDSA_get_default_method , +.Nm ECDSA_get_ex_data , +.Nm ECDSA_get_ex_new_index , +.Nm ECDSA_set_default_method , +.Nm ECDSA_set_ex_data , +.Nm ECDSA_set_method +.Nd Elliptic Curve Digital Signature Algorithm +.Sh SYNOPSIS +.In openssl/ecdsa.h +.Ft ECDSA_SIG* +.Fo ECDSA_SIG_new +.Fa void +.Fc +.Ft void +.Fo ECDSA_SIG_free +.Fa "ECDSA_SIG *sig" +.Fc +.Ft int +.Fo i2d_ECDSA_SIG +.Fa "const ECDSA_SIG *sig" +.Fa "unsigned char **pp" +.Fc +.Ft ECDSA_SIG* +.Fo d2i_ECDSA_SIG +.Fa "ECDSA_SIG **sig" +.Fa "const unsigned char **pp" +.Fa "long len" +.Fc +.Ft ECDSA_SIG* +.Fo ECDSA_do_sign +.Fa "const unsigned char *dgst" +.Fa "int dgst_len" +.Fa "EC_KEY *eckey" +.Fc +.Ft ECDSA_SIG* +.Fo ECDSA_do_sign_ex +.Fa "const unsigned char *dgst" +.Fa "int dgstlen" +.Fa "const BIGNUM *kinv" +.Fa "const BIGNUM *rp" +.Fa "EC_KEY *eckey" +.Fc +.Ft int +.Fo ECDSA_do_verify +.Fa "const unsigned char *dgst" +.Fa "int dgst_len" +.Fa "const ECDSA_SIG *sig" +.Fa "EC_KEY* eckey" +.Fc +.Ft int +.Fo ECDSA_sign_setup +.Fa "EC_KEY *eckey" +.Fa "BN_CTX *ctx" +.Fa "BIGNUM **kinv" +.Fa "BIGNUM **rp" +.Fc +.Ft int +.Fo ECDSA_sign +.Fa "int type" +.Fa "const unsigned char *dgst" +.Fa "int dgstlen" +.Fa "unsigned char *sig" +.Fa "unsigned int *siglen" +.Fa "EC_KEY *eckey" +.Fc +.Ft int +.Fo ECDSA_sign_ex +.Fa "int type" +.Fa "const unsigned char *dgst" +.Fa "int dgstlen" +.Fa "unsigned char *sig" +.Fa "unsigned int *siglen" +.Fa "const BIGNUM *kinv" +.Fa "const BIGNUM *rp" +.Fa "EC_KEY *eckey" +.Fc +.Ft int +.Fo ECDSA_verify +.Fa "int type" +.Fa "const unsigned char *dgst" +.Fa "int dgstlen" +.Fa "const unsigned char *sig" +.Fa "int siglen" +.Fa "EC_KEY *eckey" +.Fc +.Ft int +.Fo ECDSA_size +.Fa "const EC_KEY *eckey" +.Fc +.Ft const ECDSA_METHOD* +.Fo ECDSA_OpenSSL +.Fa void +.Fc +.Ft void +.Fo ECDSA_set_default_method +.Fa "const ECDSA_METHOD *meth" +.Fc +.Ft const ECDSA_METHOD* +.Fo ECDSA_get_default_method +.Fa void +.Fc +.Ft int +.Fo ECDSA_set_method +.Fa "EC_KEY *eckey" +.Fa "const ECDSA_METHOD *meth" +.Fc +.Ft int +.Fo ECDSA_get_ex_new_index +.Fa "long argl" +.Fa "void *argp" +.Fa "CRYPTO_EX_new *new_func" +.Fa "CRYPTO_EX_dup *dup_func" +.Fa "CRYPTO_EX_free *free_func" +.Fc +.Ft int +.Fo ECDSA_set_ex_data +.Fa "EC_KEY *d" +.Fa "int idx" +.Fa "void *arg" +.Fc +.Ft void* +.Fo ECDSA_get_ex_data +.Fa "EC_KEY *d" +.Fa "int idx" +.Fc +.Sh DESCRIPTION +The +.Vt ECDSA_SIG +structure consists of two +.Vt BIGNUM Ns s +for the +.Fa r +and +.Fa s +value of an ECDSA signature (see X9.62 or FIPS 186-2). +.Bd -literal -offset indent +struct { + BIGNUM *r; + BIGNUM *s; +} ECDSA_SIG; +.Ed +.Pp +.Fn ECDSA_SIG_new +allocates a new +.Vt ECDSA_SIG +structure (note: this function also allocates the +.Vt BIGNUM Ns s ) +and initialize it. +.Pp +.Fn ECDSA_SIG_free +frees the +.Vt ECDSA_SIG +structure +.Fa sig . +.Pp +.Fn i2d_ECDSA_SIG +creates the DER encoding of the ECDSA signature +.Fa sig +and writes the encoded signature to +.Fa *pp +(note: if +.Fa pp +is +.Dv NULL , +.Fn i2d_ECDSA_SIG +returns the expected length in bytes of the DER encoded signature). +.Fn i2d_ECDSA_SIG +returns the length of the DER encoded signature (or 0 on error). +.Pp +.Fn d2i_ECDSA_SIG +decodes a DER encoded ECDSA signature and returns the decoded signature +in a newly allocated +.Vt ECDSA_SIG +structure. +.Fa *sig +points to the buffer containing the DER encoded signature of size +.Fa len . +.Pp +.Fn ECDSA_size +returns the maximum length of a DER encoded ECDSA signature created with +the private EC key +.Fa eckey . +.Pp +.Fn ECDSA_sign_setup +may be used to precompute parts of the signing operation. +.Fa eckey +is the private EC key and +.Fa ctx +is a pointer to a +.Vt BN_CTX +structure (or +.Dv NULL ) . +The precomputed values or returned in +.Fa kinv +and +.Fa rp +and can be used in a later call to +.Fa ECDSA_sign_ex +or +.Fa ECDSA_do_sign_ex . +.Pp +.Fn ECDSA_sign +is wrapper function for +.Fa ECDSA_sign_ex +with +.Fa kinv +and +.Fa rp +set to +.Dv NULL . +.Pp +.Fn ECDSA_sign_ex +computes a digital signature of the +.Fa dgstlen +bytes hash value +.Fa dgst +using the private EC key +.Fa eckey +and the optional pre-computed values +.Fa kinv +and +.Fa rp . +The DER encoded signatures is stored in +.Fa sig +and its length is returned in +.Fa siglen . +Note: +.Fa sig +must point to +.Fn ECDSA_size +bytes of memory. +The parameter +.Fa type +is ignored. +.Pp +.Fn ECDSA_verify +verifies that the signature in +.Fa sig +of size +.Fa siglen +is a valid ECDSA signature of the hash value +.Fa dgst +of size +.Fa dgstlen +using the public key +.Fa eckey . +The parameter +.Fa type +is ignored. +.Pp +.Fn ECDSA_do_sign +is wrapper function for ECDSA_do_sign_ex with +.Fa kinv +and +.Fa rp +set to +.Dv NULL . +.Pp +.Fn ECDSA_do_sign_ex +computes a digital signature of the +.Fa dgst_len +bytes hash value +.Fa dgst +using the private key +.Fa eckey +and the optional pre-computed values +.Fa kinv +and +.Fa rp . +The signature is returned in a newly allocated +.Vt ECDSA_SIG +structure (or +.Dv NULL +on error). +.Pp +.Fn ECDSA_do_verify +verifies that the signature +.Fa sig +is a valid ECDSA signature of the hash value +.Fa dgst +of size +.Fa dgst_len +using the public key +.Fa eckey . +.Sh RETURN VALUES +.Fn ECDSA_size +returns the maximum length signature or 0 on error. +.Pp +.Fn ECDSA_sign_setup +and +.Fn ECDSA_sign +return 1 if successful or 0 on error. +.Pp +.Fn ECDSA_verify +and +.Fn ECDSA_do_verify +return 1 for a valid signature, 0 for an invalid signature and -1 on +error. +The error codes can be obtained by +.Xr ERR_get_error 3 . +.Sh EXAMPLES +Creating a ECDSA signature of given SHA-1 hash value using the named +curve secp192k1. +.Pp +First step: Create an +.Vt EC_KEY +object. +This part is +.Em not +ECDSA specific. +.Bd -literal -offset indent +int ret; +ECDSA_SIG *sig; +EC_KEY *eckey; + +eckey = EC_KEY_new_by_curve_name(NID_secp192k1); +if (eckey == NULL) { + /* error */ +} +if (!EC_KEY_generate_key(eckey)) { + /* error */ +} +.Ed +.Pp +Second step: compute the ECDSA signature of a SHA-1 hash value using +.Fn ECDSA_do_sign +.Bd -literal -offset indent +sig = ECDSA_do_sign(digest, 20, eckey); +if (sig == NULL) { + /* error */ +} +.Ed +.Pp +or using +.Fn ECDSA_sign +.Bd -literal -offset indent +unsigned char *buffer, *pp; +int buf_len; + +buf_len = ECDSA_size(eckey); +buffer = malloc(buf_len); +pp = buffer; +if (!ECDSA_sign(0, dgst, dgstlen, pp, &buf_len, eckey) { + /* error */ +} +.Ed +.Pp +Third step: Verify the created ECDSA signature using +.Fn ECDSA_do_verify +.Pp +.Dl ret = ECDSA_do_verify(digest, 20, sig, eckey); +.Pp +or using +.Fn ECDSA_verify +.Pp +.Dl ret = ECDSA_verify(0, digest, 20, buffer, buf_len, eckey); +.Pp +and finally evaluate the return value: +.Bd -literal -offset indent +if (ret == -1) { + /* error */ +} else if (ret == 0) { + /* incorrect signature */ +} else { + /* ret == 1 */ + /* signature ok */ +} +.Ed +.Sh SEE ALSO +.Xr dsa 3 , +.Xr rsa 3 +.Sh STANDARDS +ANSI X9.62, US Federal Information Processing Standard FIPS 186-2 +(Digital Signature Standard, DSS) +.Sh HISTORY +The ecdsa implementation was first introduced in OpenSSL 0.9.8. +.Sh AUTHORS +.An Nils Larsch +for the OpenSSL project. diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile index ecb1d51a526..86c5de26f8a 100644 --- a/lib/libcrypto/man/Makefile +++ b/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.28 2015/11/11 22:14:39 jmc Exp $ +# $OpenBSD: Makefile,v 1.29 2015/11/12 00:55:49 schwarze Exp $ .include <bsd.own.mk> # for NOMAN @@ -73,8 +73,14 @@ MAN= \ CONF_modules_load_file.3 \ CRYPTO_set_ex_data.3 \ CRYPTO_set_locking_callback.3 \ + ECDSA_SIG_new.3 \ EVP_AEAD_CTX_init.3 \ + bn_dump.3 \ crypto.3 \ + d2i_PKCS8PrivateKey_bio.3 \ + des_read_pw.3 \ + lh_new.3 \ + ui_new.3 \ GENMAN= \ DES_set_key.3 \ @@ -188,12 +194,10 @@ GENMAN= \ X509_new.3 \ X509_verify_cert.3 \ bn.3 \ - bn_internal.3 \ d2i_ASN1_OBJECT.3 \ d2i_DHparams.3 \ d2i_DSAPublicKey.3 \ d2i_ECPKParameters.3 \ - d2i_PKCS8PrivateKey.3 \ d2i_RSAPublicKey.3 \ d2i_X509.3 \ d2i_X509_ALGOR.3 \ @@ -204,15 +208,11 @@ GENMAN= \ dh.3 \ dsa.3 \ ec.3 \ - ecdsa.3 \ engine.3 \ evp.3 \ i2d_PKCS7_bio_stream.3 \ lh_stats.3 \ - lhash.3 \ rsa.3 \ - ui.3 \ - ui_compat.3 \ x509.3 \ MAN+= ${GENMAN} @@ -605,6 +605,23 @@ MLINKS+=\ EC_POINT_new.3 EC_POINT_set_compressed_coordinates_GF2m.3 \ EC_POINT_new.3 EC_POINT_set_compressed_coordinates_GFp.3 \ EC_POINT_new.3 EC_POINT_set_to_infinity.3 \ + ECDSA_SIG_new.3 ECDSA_OpenSSL.3 \ + ECDSA_SIG_new.3 ECDSA_SIG_free.3 \ + ECDSA_SIG_new.3 ECDSA_do_sign.3 \ + ECDSA_SIG_new.3 ECDSA_do_sign_ex.3 \ + ECDSA_SIG_new.3 ECDSA_do_verify.3 \ + ECDSA_SIG_new.3 ECDSA_get_default_method.3 \ + ECDSA_SIG_new.3 ECDSA_get_ex_data.3 \ + ECDSA_SIG_new.3 ECDSA_get_ex_new_index.3 \ + ECDSA_SIG_new.3 ECDSA_set_default_method.3 \ + ECDSA_SIG_new.3 ECDSA_set_ex_data.3 \ + ECDSA_SIG_new.3 ECDSA_set_method.3 \ + ECDSA_SIG_new.3 ECDSA_sign.3 \ + ECDSA_SIG_new.3 ECDSA_sign_ex.3 \ + ECDSA_SIG_new.3 ECDSA_sign_setup.3 \ + ECDSA_SIG_new.3 ECDSA_verify.3 \ + ECDSA_SIG_new.3 d2i_ECDSA_SIG.3 \ + ECDSA_SIG_new.3 i2d_ECDSA_SIG.3 \ ERR_GET_LIB.3 ERR_GET_FUNC.3 \ ERR_GET_LIB.3 ERR_GET_REASON.3 \ ERR_error_string.3 ERR_error_string_n.3 \ @@ -982,38 +999,37 @@ MLINKS+=\ X509_VERIFY_PARAM_set_flags.3 X509_VERIFY_PARAM_set_purpose.3 \ X509_VERIFY_PARAM_set_flags.3 X509_VERIFY_PARAM_set_time.3 \ X509_VERIFY_PARAM_set_flags.3 X509_VERIFY_PARAM_set_trust.3 \ - bn_internal.3 bn_add_words.3 \ - bn_internal.3 bn_check_top.3 \ - bn_internal.3 bn_cmp_words.3 \ - bn_internal.3 bn_div_words.3 \ - bn_internal.3 bn_dump.3 \ - bn_internal.3 bn_expand.3 \ - bn_internal.3 bn_expand2.3 \ - bn_internal.3 bn_fix_top.3 \ - bn_internal.3 bn_mul_add_words.3 \ - bn_internal.3 bn_mul_comba4.3 \ - bn_internal.3 bn_mul_comba8.3 \ - bn_internal.3 bn_mul_high.3 \ - bn_internal.3 bn_mul_low_normal.3 \ - bn_internal.3 bn_mul_low_recursive.3 \ - bn_internal.3 bn_mul_normal.3 \ - bn_internal.3 bn_mul_part_recursive.3 \ - bn_internal.3 bn_mul_recursive.3 \ - bn_internal.3 bn_mul_words.3 \ - bn_internal.3 bn_print.3 \ - bn_internal.3 bn_set_high.3 \ - bn_internal.3 bn_set_low.3 \ - bn_internal.3 bn_set_max.3 \ - bn_internal.3 bn_sqr_comba4.3 \ - bn_internal.3 bn_sqr_comba8.3 \ - bn_internal.3 bn_sqr_normal.3 \ - bn_internal.3 bn_sqr_recursive.3 \ - bn_internal.3 bn_sqr_words.3 \ - bn_internal.3 bn_sub_words.3 \ - bn_internal.3 bn_wexpand.3 \ - bn_internal.3 mul.3 \ - bn_internal.3 mul_add.3 \ - bn_internal.3 sqr.3 \ + bn_dump.3 bn_add_words.3 \ + bn_dump.3 bn_check_top.3 \ + bn_dump.3 bn_cmp_words.3 \ + bn_dump.3 bn_div_words.3 \ + bn_dump.3 bn_expand.3 \ + bn_dump.3 bn_expand2.3 \ + bn_dump.3 bn_fix_top.3 \ + bn_dump.3 bn_mul_add_words.3 \ + bn_dump.3 bn_mul_comba4.3 \ + bn_dump.3 bn_mul_comba8.3 \ + bn_dump.3 bn_mul_high.3 \ + bn_dump.3 bn_mul_low_normal.3 \ + bn_dump.3 bn_mul_low_recursive.3 \ + bn_dump.3 bn_mul_normal.3 \ + bn_dump.3 bn_mul_part_recursive.3 \ + bn_dump.3 bn_mul_recursive.3 \ + bn_dump.3 bn_mul_words.3 \ + bn_dump.3 bn_print.3 \ + bn_dump.3 bn_set_high.3 \ + bn_dump.3 bn_set_low.3 \ + bn_dump.3 bn_set_max.3 \ + bn_dump.3 bn_sqr_comba4.3 \ + bn_dump.3 bn_sqr_comba8.3 \ + bn_dump.3 bn_sqr_normal.3 \ + bn_dump.3 bn_sqr_recursive.3 \ + bn_dump.3 bn_sqr_words.3 \ + bn_dump.3 bn_sub_words.3 \ + bn_dump.3 bn_wexpand.3 \ + bn_dump.3 mul.3 \ + bn_dump.3 mul_add.3 \ + bn_dump.3 sqr.3 \ d2i_ASN1_OBJECT.3 i2d_ASN1_OBJECT.3 \ d2i_DHparams.3 i2d_DHparams.3 \ d2i_DSAPublicKey.3 d2i_DSAPrivateKey.3 \ @@ -1032,12 +1048,11 @@ MLINKS+=\ d2i_ECPKParameters.3 i2d_ECPKParameters.3 \ d2i_ECPKParameters.3 i2d_ECPKParameters_bio.3 \ d2i_ECPKParameters.3 i2d_ECPKParameters_fp.3 \ - d2i_PKCS8PrivateKey.3 d2i_PKCS8PrivateKey_bio.3 \ - d2i_PKCS8PrivateKey.3 d2i_PKCS8PrivateKey_fp.3 \ - d2i_PKCS8PrivateKey.3 i2d_PKCS8PrivateKey_bio.3 \ - d2i_PKCS8PrivateKey.3 i2d_PKCS8PrivateKey_fp.3 \ - d2i_PKCS8PrivateKey.3 i2d_PKCS8PrivateKey_nid_bio.3 \ - d2i_PKCS8PrivateKey.3 i2d_PKCS8PrivateKey_nid_fp.3 \ + d2i_PKCS8PrivateKey_bio.3 d2i_PKCS8PrivateKey_fp.3 \ + d2i_PKCS8PrivateKey_bio.3 i2d_PKCS8PrivateKey_bio.3 \ + d2i_PKCS8PrivateKey_bio.3 i2d_PKCS8PrivateKey_fp.3 \ + d2i_PKCS8PrivateKey_bio.3 i2d_PKCS8PrivateKey_nid_bio.3 \ + d2i_PKCS8PrivateKey_bio.3 i2d_PKCS8PrivateKey_nid_fp.3 \ d2i_RSAPublicKey.3 d2i_Netscape_RSA.3 \ d2i_RSAPublicKey.3 d2i_RSAPrivateKey.3 \ d2i_RSAPublicKey.3 i2d_Netscape_RSA.3 \ @@ -1060,24 +1075,9 @@ MLINKS+=\ d2i_X509_REQ.3 i2d_X509_REQ.3 \ d2i_X509_REQ.3 i2d_X509_REQ_bio.3 \ d2i_X509_REQ.3 i2d_X509_REQ_fp.3 \ - ecdsa.3 ECDSA_OpenSSL.3 \ - ecdsa.3 ECDSA_SIG_free.3 \ - ecdsa.3 ECDSA_SIG_new.3 \ - ecdsa.3 ECDSA_do_sign.3 \ - ecdsa.3 ECDSA_do_sign_ex.3 \ - ecdsa.3 ECDSA_do_verify.3 \ - ecdsa.3 ECDSA_get_default_method.3 \ - ecdsa.3 ECDSA_get_ex_data.3 \ - ecdsa.3 ECDSA_get_ex_new_index.3 \ - ecdsa.3 ECDSA_set_default_method.3 \ - ecdsa.3 ECDSA_set_ex_data.3 \ - ecdsa.3 ECDSA_set_method.3 \ - ecdsa.3 ECDSA_sign.3 \ - ecdsa.3 ECDSA_sign_ex.3 \ - ecdsa.3 ECDSA_sign_setup.3 \ - ecdsa.3 ECDSA_verify.3 \ - ecdsa.3 d2i_ECDSA_SIG.3 \ - ecdsa.3 i2d_ECDSA_SIG.3 \ + des_read_pw.3 des_read_2passwords.3 \ + des_read_pw.3 des_read_password.3 \ + des_read_pw.3 des_read_pw_string.3 \ engine.3 ENGINE_add.3 \ engine.3 ENGINE_by_id.3 \ engine.3 ENGINE_finish.3 \ @@ -1088,47 +1088,41 @@ MLINKS+=\ engine.3 ENGINE_init.3 \ engine.3 ENGINE_load_builtin_engines.3 \ engine.3 ENGINE_remove.3 \ + lh_new.3 lh_delete.3 \ + lh_new.3 lh_doall.3 \ + lh_new.3 lh_doall_arg.3 \ + lh_new.3 lh_error.3 \ + lh_new.3 lh_free.3 \ + lh_new.3 lh_insert.3 \ + lh_new.3 lh_retrieve.3 \ lh_stats.3 lh_node_stats.3 \ lh_stats.3 lh_node_stats_bio.3 \ lh_stats.3 lh_node_usage_stats.3 \ lh_stats.3 lh_node_usage_stats_bio.3 \ lh_stats.3 lh_stats_bio.3 \ - lhash.3 lh_delete.3 \ - lhash.3 lh_doall.3 \ - lhash.3 lh_doall_arg.3 \ - lhash.3 lh_error.3 \ - lhash.3 lh_free.3 \ - lhash.3 lh_insert.3 \ - lhash.3 lh_new.3 \ - lhash.3 lh_retrieve.3 \ - ui.3 UI_OpenSSL.3 \ - ui.3 UI_add_error_string.3 \ - ui.3 UI_add_info_string.3 \ - ui.3 UI_add_input_boolean.3 \ - ui.3 UI_add_input_string.3 \ - ui.3 UI_add_user_data.3 \ - ui.3 UI_add_verify_string.3 \ - ui.3 UI_construct_prompt.3 \ - ui.3 UI_ctrl.3 \ - ui.3 UI_dup_error_string.3 \ - ui.3 UI_dup_info_string.3 \ - ui.3 UI_dup_input_boolean.3 \ - ui.3 UI_dup_input_string.3 \ - ui.3 UI_dup_verify_string.3 \ - ui.3 UI_free.3 \ - ui.3 UI_get0_result.3 \ - ui.3 UI_get0_user_data.3 \ - ui.3 UI_get_default_method.3 \ - ui.3 UI_get_method.3 \ - ui.3 UI_new.3 \ - ui.3 UI_new_method.3 \ - ui.3 UI_process.3 \ - ui.3 UI_set_default_method.3 \ - ui.3 UI_set_method.3 \ - ui_compat.3 des_read_2passwords.3 \ - ui_compat.3 des_read_password.3 \ - ui_compat.3 des_read_pw.3 \ - ui_compat.3 des_read_pw_string.3 + ui_new.3 UI_OpenSSL.3 \ + ui_new.3 UI_add_error_string.3 \ + ui_new.3 UI_add_info_string.3 \ + ui_new.3 UI_add_input_boolean.3 \ + ui_new.3 UI_add_input_string.3 \ + ui_new.3 UI_add_user_data.3 \ + ui_new.3 UI_add_verify_string.3 \ + ui_new.3 UI_construct_prompt.3 \ + ui_new.3 UI_ctrl.3 \ + ui_new.3 UI_dup_error_string.3 \ + ui_new.3 UI_dup_info_string.3 \ + ui_new.3 UI_dup_input_boolean.3 \ + ui_new.3 UI_dup_input_string.3 \ + ui_new.3 UI_dup_verify_string.3 \ + ui_new.3 UI_free.3 \ + ui_new.3 UI_get0_result.3 \ + ui_new.3 UI_get0_user_data.3 \ + ui_new.3 UI_get_default_method.3 \ + ui_new.3 UI_get_method.3 \ + ui_new.3 UI_new_method.3 \ + ui_new.3 UI_process.3 \ + ui_new.3 UI_set_default_method.3 \ + ui_new.3 UI_set_method.3 .include <bsd.man.mk> .else diff --git a/lib/libcrypto/man/bn_dump.3 b/lib/libcrypto/man/bn_dump.3 new file mode 100644 index 00000000000..2f1bda9bb52 --- /dev/null +++ b/lib/libcrypto/man/bn_dump.3 @@ -0,0 +1,713 @@ +.Dd $Mdocdate: November 12 2015 $ +.Dt BN_DUMP 3 +.Os +.Sh NAME +.Nm bn_mul_words , +.Nm bn_mul_add_words , +.Nm bn_sqr_words , +.Nm bn_div_words , +.Nm bn_add_words , +.Nm bn_sub_words , +.Nm bn_mul_comba4 , +.Nm bn_mul_comba8 , +.Nm bn_sqr_comba4 , +.Nm bn_sqr_comba8 , +.Nm bn_cmp_words , +.Nm bn_mul_normal , +.Nm bn_mul_low_normal , +.Nm bn_mul_recursive , +.Nm bn_mul_part_recursive , +.Nm bn_mul_low_recursive , +.Nm bn_mul_high , +.Nm bn_sqr_normal , +.Nm bn_sqr_recursive , +.Nm bn_expand , +.Nm bn_wexpand , +.Nm bn_expand2 , +.Nm bn_fix_top , +.Nm bn_check_top , +.Nm bn_print , +.Nm bn_dump , +.Nm bn_set_max , +.Nm bn_set_high , +.Nm bn_set_low , +.Nm sqr +.Nd BIGNUM library internal functions +.Sh SYNOPSIS +.In openssl/bn.h +.Ft BN_ULONG +.Fo bn_mul_words +.Fa "BN_ULONG *rp" +.Fa "BN_ULONG *ap" +.Fa "int num" +.Fa "BN_ULONG w" +.Fc +.Ft BN_ULONG +.Fo bn_mul_add_words +.Fa "BN_ULONG *rp" +.Fa "BN_ULONG *ap" +.Fa "int num" +.Fa "BN_ULONG w" +.Fc +.Ft void +.Fo bn_sqr_words +.Fa "BN_ULONG *rp" +.Fa "BN_ULONG *ap" +.Fa "int num" +.Fc +.Ft BN_ULONG +.Fo bn_div_words +.Fa "BN_ULONG h" +.Fa "BN_ULONG l" +.Fa "BN_ULONG d" +.Fc +.Ft BN_ULONG +.Fo bn_add_words +.Fa "BN_ULONG *rp" +.Fa "BN_ULONG *ap" +.Fa "BN_ULONG *bp" +.Fa "int num" +.Fc +.Ft BN_ULONG +.Fo bn_sub_words +.Fa "BN_ULONG *rp" +.Fa "BN_ULONG *ap" +.Fa "BN_ULONG *bp" +.Fa "int num" +.Fc +.Ft void +.Fo bn_mul_comba4 +.Fa "BN_ULONG *r" +.Fa "BN_ULONG *a" +.Fa "BN_ULONG *b" +.Fc +.Ft void +.Fo bn_mul_comba8 +.Fa "BN_ULONG *r" +.Fa "BN_ULONG *a" +.Fa "BN_ULONG *b" +.Fc +.Ft void +.Fo bn_sqr_comba4 +.Fa "BN_ULONG *r" +.Fa "BN_ULONG *a" +.Fc +.Ft void +.Fo bn_sqr_comba8 +.Fa "BN_ULONG *r" +.Fa "BN_ULONG *a" +.Fc +.Ft int +.Fo bn_cmp_words +.Fa "BN_ULONG *a" +.Fa "BN_ULONG *b" +.Fa "int n" +.Fc +.Ft void +.Fo bn_mul_normal +.Fa "BN_ULONG *r" +.Fa "BN_ULONG *a" +.Fa "int na" +.Fa "BN_ULONG *b" +.Fa "int nb" +.Fc +.Ft void +.Fo bn_mul_low_normal +.Fa "BN_ULONG *r" +.Fa "BN_ULONG *a" +.Fa "BN_ULONG *b" +.Fa "int n" +.Fc +.Ft void +.Fo bn_mul_recursive +.Fa "BN_ULONG *r" +.Fa "BN_ULONG *a" +.Fa "BN_ULONG *b" +.Fa "int n2" +.Fa "int dna" +.Fa "int dnb" +.Fa "BN_ULONG *tmp" +.Fc +.Ft void +.Fo bn_mul_part_recursive +.Fa "BN_ULONG *r" +.Fa "BN_ULONG *a" +.Fa "BN_ULONG *b" +.Fa "int n" +.Fa "int tna" +.Fa "int tnb" +.Fa "BN_ULONG *tmp" +.Fc +.Ft void +.Fo bn_mul_low_recursive +.Fa "BN_ULONG *r" +.Fa "BN_ULONG *a" +.Fa "BN_ULONG *b" +.Fa "int n2" +.Fa "BN_ULONG *tmp" +.Fc +.Ft void +.Fo bn_mul_high +.Fa "BN_ULONG *r" +.Fa "BN_ULONG *a" +.Fa "BN_ULONG *b" +.Fa "BN_ULONG *l" +.Fa "int n2" +.Fa "BN_ULONG *tmp" +.Fc +.Ft void +.Fo bn_sqr_normal +.Fa "BN_ULONG *r" +.Fa "BN_ULONG *a" +.Fa "int n" +.Fa "BN_ULONG *tmp" +.Fc +.Ft void +.Fo bn_sqr_recursive +.Fa "BN_ULONG *r" +.Fa "BN_ULONG *a" +.Fa "int n2" +.Fa "BN_ULONG *tmp" +.Fc +.Ft void +.Fo mul +.Fa "BN_ULONG r" +.Fa "BN_ULONG a" +.Fa "BN_ULONG w" +.Fa "BN_ULONG c" +.Fc +.Ft void +.Fo mul_add +.Fa "BN_ULONG r" +.Fa "BN_ULONG a" +.Fa "BN_ULONG w" +.Fa "BN_ULONG c" +.Fc +.Ft void +.Fo sqr +.Fa "BN_ULONG r0" +.Fa "BN_ULONG r1" +.Fa "BN_ULONG a" +.Fc +.Ft BIGNUM * +.Fo bn_expand +.Fa "BIGNUM *a" +.Fa "int bits" +.Fc +.Ft BIGNUM * +.Fo bn_wexpand +.Fa "BIGNUM *a" +.Fa "int n" +.Fc +.Ft BIGNUM * +.Fo bn_expand2 +.Fa "BIGNUM *a" +.Fa "int n" +.Fc +.Ft void +.Fo bn_fix_top +.Fa "BIGNUM *a" +.Fc +.Ft void +.Fo bn_check_top +.Fa "BIGNUM *a" +.Fc +.Ft void +.Fo bn_print +.Fa "BIGNUM *a" +.Fc +.Ft void +.Fo bn_dump +.Fa "BN_ULONG *d" +.Fa "int n" +.Fc +.Ft void +.Fo bn_set_max +.Fa "BIGNUM *a" +.Fc +.Ft void +.Fo bn_set_high +.Fa "BIGNUM *r" +.Fa "BIGNUM *a" +.Fa "int n" +.Fc +.Ft void +.Fo bn_set_low +.Fa "BIGNUM *r" +.Fa "BIGNUM *a" +.Fa "int n" +.Fc +.Sh DESCRIPTION +This page documents the internal functions used by the OpenSSL +.Vt BIGNUM +implementation. +They are described here to facilitate debugging and extending the +library. +They are +.Em not +to be used by applications. +.Ss The BIGNUM structure +.Bd -literal +typedef struct bignum_st BIGNUM; + +struct bignum_st { + BN_ULONG *d; /* Pointer to an array of 'BN_BITS2' bit chunks. */ + int top; /* Index of last used d +1. */ + /* The next are internal book keeping for bn_expand. */ + int dmax; /* Size of the d array. */ + int neg; /* one if the number is negative */ + int flags; +}; +.Ed +.Pp +The integer value is stored in +.Fa d , +a +.Xr malloc 3 Ap ed +array of words +.Pq Vt BN_ULONG , +least significant word first. +A +.Vt BN_ULONG +can be either 16, 32 or 64 bits in size, depending on the 'number of +bits' +.Pq Dv BITS2 +specified in +.In openssl/bn.h . +.Pp +.Fa dmax +is the size of the +.Fa d +array that has been allocated. +.Fa top +is the number of words being used, so for a value of 4, bn.d[0]=4 and +bn.top=1. +.Fa neg +is 1 if the number is negative. +When a +.Vt BIGNUM +is 0, the +.Fa d +field can be +.Dv NULL +and +.Fa top +== 0. +.Pp +.Fa flags +is a bit field of flags which are defined in +.In openssl/bn.h . +The flags begin with +.Dv BN_FLG_ . +The macros +.Fn BN_set_flags b n +and +.Fn BN_get_flags b n +exist to enable or fetch flag(s) +.Fa n +from a +.Vt BIGNUM +structure +.Fa b . +.Pp +Various routines in this library require the use of temporary +.Vt BIGNUM +variables during their execution. +Since dynamic memory allocation to create +.Vt BIGNUM Ns s +is rather expensive when used in conjunction with repeated subroutine +calls, the +.Vt BN_CTX +structure is used. +This structure contains BN_CTX_NUM +.Vt BIGNUM Ns s, +see +.Xr BN_CTX_start 3 . +.Ss Low-level arithmetic operations +These functions are implemented in C and for several platforms in +assembly language: +.Pp +.Fn bn_mul_words rp ap num w +operates on the +.Fa num +word arrays +.Fa rp +and +.Fa ap . +It computes +.Fa ap +* +.Fa w , +places the result in +.Fa rp , +and returns the high word (carry). +.Pp +.Fn bn_mul_add_words rp ap num w +operates on the +.Fa num +word arrays +.Fa rp +and +.Fa ap . +It computes +.Fa ap +* +.Fa w ++ +.Fa rp , +places the result in +.Fa rp , +and returns the high word (carry). +.Pp +.Fn bn_sqr_words rp ap num +operates on the +.Fa num +word array +.Fa ap +and the +.Pf 2* Fa num +word array +.Fa ap . +It computes +.Fa ap +* +.Fa ap +word-wise, and places the low and high bytes of the result in +.Fa rp . +.Pp +.Fn bn_div_words h l d +divides the two word number +.Pq Fa h , Fa l +by +.Fa d +and returns the result. +.Pp +.Fn bn_add_words rp ap bp num +operates on the +.Fa num +word arrays +.Fa ap , +.Fa bp +and +.Fa rp . +It computes +.Fa ap ++ +.Fa bp , +places the result in +.Fa rp , +and returns the high word (carry). +.Pp +.Fn bn_sub_words rp ap bp num +operates on the +.Fa num +word arrays +.Fa ap , +.Fa bp +and +.Fa rp . +It computes +.Fa ap +- +.Fa bp , +places the result in +.Fa rp , +and returns the carry (1 if +.Fa bp +\(ra +.Fa ap , +0 otherwise). +.Pp +.Fn bn_mul_comba4 r a b +operates on the 4 word arrays +.Fa a +and +.Fa b +and the 8 word array +.Fa r . +It computes +.Fa a Ns * Ns Fa b +and places the result in +.Fa r . +.Pp +.Fn bn_mul_comba8 r a b +operates on the 8 word arrays +.Fa a +and +.Fa b +and the 16 word array +.Fa r . +It computes +.Fa a Ns * Ns Fa b +and places the result in +.Fa r . +.Pp +.Fn bn_sqr_comba4 r a b +operates on the 4 word arrays +.Fa a +and +.Fa b +and the 8 word array +.Fa r . +.Pp +.Fn bn_sqr_comba8 r a b +operates on the 8 word arrays +.Fa a +and +.Fa b +and the 16 word array +.Fa r . +.Pp +The following functions are implemented in C: +.Pp +.Fn bn_cmp_words a b n +operates on the +.Fa n +word arrays +.Fa a +and +.Fa b . +It returns 1, 0 and -1 if +.Fa a +is greater than, equal and less than +.Fa b . +.Pp +.Fn bn_mul_normal r a na b nb +operates on the +.Fa na +word array +.Fa a , +the +.Fa nb +word array +.Fa b +and the +.Fa na Ns + Ns Fa nb +word array +.Fa r . +It computes +.Fa a Ns * Ns Fa b +and places the result in +.Fa r . +.Pp +.Fn bn_mul_low_normal r a b n +operates on the +.Fa n +word arrays +.Fa r , +.Fa a +and +.Fa b . +It computes the +.Fa n +low words of +.Fa a Ns * Ns Fa b +and places the result in +.Fa r . +.Pp +.Fn bn_mul_recursive r a b n2 dna dnb t +operates on the word arrays +.Fa a +and +.Fa b +of length +.Fa n2 Ns + Ns Fa dna +and +.Fa n2 Ns + Ns Fa dnb +.Pf ( Fa dna +and +.Fa dnb +are currently allowed to be 0 or negative) and the +.Pf 2* Fa n2 +word arrays +.Fa r +and +.Sy t . +.Fa n2 +must be a power of 2. +It computes +.Fa a Ns * Ns Fa b +and places the result in +.Fa r . +.Pp +.Fn bn_mul_part_recursive r a b n tna tnb tmp +operates on the word arrays +.Fa a +and +.Fa b +of length +.Fa n Ns + Ns Fa tna +and +.Fa n Ns + Ns Fa tnb +and the +.Pf 4* Fa n +word arrays +.Fa r +and +.Fa tmp . +.Pp +.Fn bn_mul_low_recursive r a b n2 tmp +operates on the +.Fa n2 +word arrays +.Fa r +and +.Fa tmp +and the +.Fa n2 Ns /2 +word arrays +.Fa a +and +.Fa b . +.Pp +.Fn bn_mul_high r a b l n2 tmp +operates on the +.Fa n2 +word arrays +.Fa r , +.Fa a , +.Fa b +and +.Fa l +(?) and the +.Pf 3* Fa n2 +word array +.Fa tmp . +.Pp +.Xr BN_mul 3 +calls +.Fn bn_mul_normal , +or an optimized implementation if the factors have the same size: +.Fn bn_mul_comba8 +is used if they are 8 words long, +.Fn bn_mul_recursive +if they are larger than +.Dv BN_MULL_SIZE_NORMAL +and the size is an exact multiple of the word size, and +.Fn bn_mul_part_recursive +for others that are larger than +.Dv BN_MULL_SIZE_NORMAL . +.Pp +.Fn bn_sqr_normal r a n tmp +operates on the +.Fa n +word array +.Fa a +and the +.Pf 2* Fa n +word arrays +.Fa tmp +and +.Fa r . +.Pp +The implementations use the following macros which, depending on the +architecture, may use +.Vt long long +C operations or inline assembler. +They are defined in +.Pa bn_lcl.h . +.Pp +.Fn mul r a w c +computes +.Fa w Ns * Ns Fa a Ns + Ns Fa c +and places the low word of the result in +.Fa r +and the high word in +.Fa c . +.Pp +.Fn mul_add r a w c +computes +.Fa w Ns * Ns Fa a Ns + Ns Fa r Ns + Ns Fa c +and places the low word of the result in +.Fa r +and the high word in +.Fa c . +.Pp +.Fn sqr r0 r1 a +computes +.Fa a Ns * Ns Fa a +and places the low word of the result in +.Fa r0 +and the high word in +.Fa r1 . +.Ss Size changes +.Fn bn_expand +ensures that +.Fa b +has enough space for a +.Fa bits +bit number. +.Fn bn_wexpand +ensures that +.Fa b +has enough space for an +.Fa n +word number. +If the number has to be expanded, both macros call +.Fn bn_expand2 , +which allocates a new +.Fa d +array and copies the data. +They return +.Dv NULL +on error, +.Fa b +otherwise. +.Pp +The +.Fn bn_fix_top +macro reduces +.Fa a Ns -> Ns Fa top +to point to the most significant non-zero word plus one when +.Fa a +has shrunk. +.Ss Debugging +.Fn bn_check_top +verifies that +.Ql ((a)-\(ratop \(ra= 0 && (a)-\(ratop \(la= (a)-\(radmax) . +A violation will cause the program to abort. +.Pp +.Fn bn_print +prints +.Fa a +to +.Dv stderr . +.Fn bn_dump +prints +.Fa n +words at +.Fa d +(in reverse order, i.e. +most significant word first) to +.Dv stderr . +.Pp +.Fn bn_set_max +makes +.Fa a +a static number with a +.Fa dmax +of its current size. +This is used by +.Fn bn_set_low +and +.Fn bn_set_high +to make +.Fa r +a read-only +.Vt BIGNUM +that contains the +.Fa n +low or high words of +.Fa a . +.Pp +If +.Dv BN_DEBUG +is not defined, +.Fn bn_check_top , +.Fn bn_print , +.Fn bn_dump +and +.Fn bn_set_max +are defined as empty macros. +.Sh SEE ALSO +.Xr bn 3 diff --git a/lib/libcrypto/man/d2i_PKCS8PrivateKey_bio.3 b/lib/libcrypto/man/d2i_PKCS8PrivateKey_bio.3 new file mode 100644 index 00000000000..9eb5fadfab6 --- /dev/null +++ b/lib/libcrypto/man/d2i_PKCS8PrivateKey_bio.3 @@ -0,0 +1,97 @@ +.Dd $Mdocdate: November 12 2015 $ +.Dt D2I_PKCS8PRIVATEKEY_BIO 3 +.Os +.Sh NAME +.Nm d2i_PKCS8PrivateKey_bio , +.Nm d2i_PKCS8PrivateKey_fp , +.Nm i2d_PKCS8PrivateKey_bio , +.Nm i2d_PKCS8PrivateKey_fp , +.Nm i2d_PKCS8PrivateKey_nid_bio , +.Nm i2d_PKCS8PrivateKey_nid_fp +.Nd PKCS#8 format private key functions +.Sh SYNOPSIS +.In openssl/evp.h +.Ft EVP_PKEY * +.Fo d2i_PKCS8PrivateKey_bio +.Fa "BIO *bp" +.Fa "EVP_PKEY **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft EVP_PKEY * +.Fo d2i_PKCS8PrivateKey_fp +.Fa "FILE *fp" +.Fa "EVP_PKEY **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo i2d_PKCS8PrivateKey_bio +.Fa "BIO *bp" +.Fa "EVP_PKEY *x" +.Fa "const EVP_CIPHER *enc" +.Fa "char *kstr" +.Fa "int klen" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo i2d_PKCS8PrivateKey_fp +.Fa "FILE *fp" +.Fa "EVP_PKEY *x" +.Fa "const EVP_CIPHER *enc" +.Fa "char *kstr" +.Fa "int klen" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo i2d_PKCS8PrivateKey_nid_bio +.Fa "BIO *bp" +.Fa "EVP_PKEY *x" +.Fa "int nid" +.Fa "char *kstr" +.Fa "int klen" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo i2d_PKCS8PrivateKey_nid_fp +.Fa "FILE *fp" +.Fa "EVP_PKEY *x" +.Fa "int nid" +.Fa "char *kstr" +.Fa "int klen" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Sh DESCRIPTION +The PKCS#8 functions encode and decode private keys in PKCS#8 format +using both PKCS#5 v1.5 and PKCS#5 v2.0 password based encryption +algorithms. +.Pp +Other than the use of DER as opposed to PEM these functions are +identical to the corresponding +.Xr pem 3 +functions. +.Sh NOTES +Before using these functions, +.Xr OpenSSL_add_all_algorithms 3 +should be called to initialize the internal algorithm lookup tables. +Otherwise errors about unknown algorithms will occur if an attempt is +made to decrypt a private key. +.Pp +These functions are currently the only way to store encrypted private +keys using DER format. +.Pp +Currently all the functions use +.Vt BIO +or +.Vt FILE +pointers, there are no functions which work directly on memory: +this can be readily worked around by converting the buffers to +memory BIOs, see +.Xr BIO_s_mem 3 +for details. +.Sh SEE ALSO +.Xr pem 3 diff --git a/lib/libcrypto/man/des_read_pw.3 b/lib/libcrypto/man/des_read_pw.3 new file mode 100644 index 00000000000..e118b437933 --- /dev/null +++ b/lib/libcrypto/man/des_read_pw.3 @@ -0,0 +1,97 @@ +.Dd $Mdocdate: November 12 2015 $ +.Dt DES_READ_PW 3 +.Os +.Sh NAME +.Nm des_read_password , +.Nm des_read_2passwords , +.Nm des_read_pw_string , +.Nm des_read_pw +.Nd Compatibility user interface functions +.Sh SYNOPSIS +.In openssl/des_old.h +.Ft int +.Fo des_read_password +.Fa "DES_cblock *key" +.Fa "const char *prompt" +.Fa "int verify" +.Fc +.Ft int +.Fo des_read_2passwords +.Fa "DES_cblock *key1" +.Fa "DES_cblock *key2" +.Fa "const char *prompt" +.Fa "int verify" +.Fc +.Ft int +.Fo des_read_pw_string +.Fa "char *buf" +.Fa "int length" +.Fa "const char *prompt" +.Fa "int verify" +.Fc +.Ft int +.Fo des_read_pw +.Fa "char *buf" +.Fa "char *buff" +.Fa "int size" +.Fa "const char *prompt" +.Fa "int verify" +.Fc +.Sh DESCRIPTION +The DES library contained a few routines to prompt for passwords. +These aren't necessarily dependent on DES, and have therefore become +part of the UI compatibility library. +.Pp +.Fn des_read_pw +writes the string specified by +.Fa prompt +to standard output turns echo off and reads an input string from the +terminal. +The string is returned in +.Fa buf , +which must have space for at least +.Fa size +bytes. +If +.Fa verify +is set, the user is asked for the password twice and unless the two +copies match, an error is returned. +The second password is stored in +.Fa buff , +which must therefore also be at least +.Fa size +bytes. +A return code of -1 indicates a system error, 1 failure due to use +interaction, and 0 is success. +All other functions described here use +.Fn des_read_pw +to do the work. +.Pp +.Fn des_read_pw_string +is a variant of +.Fn des_read_pw +that provides a buffer for you if +.Fa verify +is set. +.Pp +.Fn des_read_password +calls +.Fn des_read_pw +and converts the password to a DES key by calling +.Xr DES_string_to_key 3 ; +.Fn des_read_2passwords +operates in the same way as +.Fn des_read_password +except that it generates two keys by using the +.Xr DES_string_to_2key 3 +function. +.Sh NOTES +.Fn des_read_pw_string +is available in the MIT Kerberos library as well, and is also available +under the name +.Xr EVP_read_pw_string 3 . +.Sh SEE ALSO +.Xr ui_new 3 +.Sh AUTHORS +.An Richard Levitte Aq Mt richard@levitte.org +for the OpenSSL project. diff --git a/lib/libcrypto/man/lh_new.3 b/lib/libcrypto/man/lh_new.3 new file mode 100644 index 00000000000..2779cf9202b --- /dev/null +++ b/lib/libcrypto/man/lh_new.3 @@ -0,0 +1,430 @@ +.Dd $Mdocdate: November 12 2015 $ +.Dt LH_NEW 3 +.Os +.Sh NAME +.Nm lh_new , +.Nm lh_free , +.Nm lh_insert , +.Nm lh_delete , +.Nm lh_retrieve , +.Nm lh_doall , +.Nm lh_doall_arg , +.Nm lh_error +.Nd dynamic hash table +.Sh SYNOPSIS +.In openssl/lhash.h +.Fn DECLARE_LHASH_OF <type> +.Ft LHASH * +.Fn lh_<type>_new void +.Ft void +.Fo lh_<type>_free +.Fa "LHASH_OF(<type>) *table" +.Fc +.Ft <type> * +.Fo lh_<type>_insert +.Fa "LHASH_OF(<type>) *table" +.Fa "<type> *data" +.Fc +.Ft <type> * +.Fo lh_<type>_delete +.Fa "LHASH_OF(<type>) *table" +.Fa "<type> *data" +.Fc +.Ft <type> * +.Fo lh_<type>_retrieve +.Fa "LHASH_OF<type>) *table" +.Fa "<type> *data" +.Fc +.Ft void +.Fo lh_<type>_doall +.Fa "LHASH_OF(<type>) *table" +.Fa "LHASH_DOALL_FN_TYPE func" +.Fc +.Ft void +.Fo lh_<type>_doall_arg +.Fa "LHASH_OF(<type>) *table" +.Fa "LHASH_DOALL_ARG_FN_TYPE func" +.Fa "<type2>" +.Fa "<type2> *arg" +.Fc +.Ft int +.Fo lh_<type>_error +.Fa "LHASH_OF(<type>) *table" +.Fc +.Ft typedef int +.Fo (*LHASH_COMP_FN_TYPE) +.Fa "const void *" +.Fa "const void *" +.Fc +.Ft typedef unsigned long +.Fo (*LHASH_HASH_FN_TYPE) +.Fa "const void *" +.Fc +.Ft typedef void +.Fo (*LHASH_DOALL_FN_TYPE) +.Fa "const void *" +.Fc +.Ft typedef void +.Fo (*LHASH_DOALL_ARG_FN_TYPE) +.Fa "const void *" +.Fa "const void *" +.Fc +.Sh DESCRIPTION +This library implements type-checked dynamic hash tables. +The hash table entries can be arbitrary structures. +Usually they consist of key and value fields. +.Pp +.Fn lh_<type>_new +creates a new +.Vt LHASH_OF(<type>) +structure to store arbitrary data entries, and provides the hash and +compare callbacks to be used in organising the table's entries. +The hash callback takes a pointer to a table entry as its argument +and returns an unsigned long hash value for its key field. +The hash value is normally truncated to a power of 2, so make sure that +your hash function returns well mixed low order bits. +The compare callback takes two arguments (pointers to two hash table +entries), and returns 0 if their keys are equal, non-zero otherwise. +If your hash table will contain items of some particular type and the +hash and compare callbacks hash and compare these types, then the +.Fn DECLARE_LHASH_HASH_FN +and +.Fn IMPLEMENT_LHASH_COMP_FN +macros can be used to create callback wrappers of the prototypes +required by +.Fn lh_<type>_new . +These provide per-variable casts before calling the type-specific +callbacks written by the application author. +These macros, as well as those used for the doall callbacks, are +defined as; +.Bd -literal -offset 2n +#define DECLARE_LHASH_HASH_FN(name, o_type) \e + unsigned long name##_LHASH_HASH(const void *); +#define IMPLEMENT_LHASH_HASH_FN(name, o_type) \e + unsigned long name##_LHASH_HASH(const void *arg) { \e + const o_type *a = arg; \e + return name##_hash(a); } +#define LHASH_HASH_FN(name) name##_LHASH_HASH + +#define DECLARE_LHASH_COMP_FN(name, o_type) \e + int name##_LHASH_COMP(const void *, const void *); +#define IMPLEMENT_LHASH_COMP_FN(name, o_type) \e + int name##_LHASH_COMP(const void *arg1, const void *arg2) { \e + const o_type *a = arg1; \e + const o_type *b = arg2; \e + return name##_cmp(a,b); } +#define LHASH_COMP_FN(name) name##_LHASH_COMP + +#define DECLARE_LHASH_DOALL_FN(name, o_type) \e + void name##_LHASH_DOALL(void *); +#define IMPLEMENT_LHASH_DOALL_FN(name, o_type) \e + void name##_LHASH_DOALL(void *arg) { \e + o_type *a = arg; \e + name##_doall(a); } +#define LHASH_DOALL_FN(name) name##_LHASH_DOALL + +#define DECLARE_LHASH_DOALL_ARG_FN(name, o_type, a_type) \e + void name##_LHASH_DOALL_ARG(void *, void *); +#define IMPLEMENT_LHASH_DOALL_ARG_FN(name, o_type, a_type) \e + void name##_LHASH_DOALL_ARG(void *arg1, void *arg2) { \e + o_type *a = arg1; \e + a_type *b = arg2; \e + name##_doall_arg(a, b); } +#define LHASH_DOALL_ARG_FN(name) name##_LHASH_DOALL_ARG +.Ed +.Pp +An example of a hash table storing (pointers to) structures of type +\&'STUFF' could be defined as follows; +.Bd -literal -offset 2n +/* Calculate the hash value of 'tohash' (implemented elsewhere) */ +unsigned long STUFF_hash(const STUFF *tohash); +/* Order 'arg1' and 'arg2' (implemented elsewhere) */ +int stuff_cmp(const STUFF *arg1, const STUFF *arg2); +/* Create type-safe wrapper functions for use in the LHASH internals */ +static IMPLEMENT_LHASH_HASH_FN(stuff, STUFF); +static IMPLEMENT_LHASH_COMP_FN(stuff, STUFF); +/* ... */ +int main(int argc, char *argv[]) { + /* Create the new hash table using the hash/compare wrappers */ + LHASH_OF(STUFF) *hashtable = + lh_STUFF_new(LHASH_HASH_FN(STUFF_hash), + LHASH_COMP_FN(STUFF_cmp)); + /* ... */ +} +.Ed +.Pp +.Fn lh_<type>_free +frees the +.Vt LHASH_OF(<type>) +structure +.Fa table . +Allocated hash table entries will not be freed; consider using +.Fn lh_<type>_doall +to deallocate any remaining entries in the hash table (see below). +.Pp +.Fn lh_<type>_insert +inserts the structure pointed to by +.Fa data +into +.Fa table . +If there already is an entry with the same key, the old value is +replaced. +Note that +.Fn lh_<type>_insert +stores pointers, the data are not copied. +.Pp +.Fn lh_<type>_delete +deletes an entry from +.Fa table . +.Pp +.Fn lh_<type>_retrieve +looks up an entry in +.Fa table . +Normally, +.Fa data +is a structure with the key field(s) set; the function will return a +pointer to a fully populated structure. +.Pp +.Fn lh_<type>_doall +will, for every entry in the hash table, call +.Fa func +with the data item as its parameter. +For +.Fn lh_<type>_doall +and +.Fn lh_<type>_doall_arg , +function pointer casting should be avoided in the callbacks (see +.Sx NOTES ) +\(em instead use the declare/implement macros to create type-checked +wrappers that cast variables prior to calling your type-specific +callbacks. +An example of this is illustrated here where the callback is used to +cleanup resources for items in the hash table prior to the hashtable +itself being deallocated: +.Bd -literal -offset 2n +/* Clean up resources belonging to 'a' (this is implemented elsewhere) */ +void STUFF_cleanup_doall(STUFF *a); +/* Implement a prototype-compatible wrapper for "STUFF_cleanup" */ +IMPLEMENT_LHASH_DOALL_FN(STUFF_cleanup, STUFF) + /* ... then later in the code ... */ +/* So to run "STUFF_cleanup" against all items in a hash table ... */ +lh_STUFF_doall(hashtable, LHASH_DOALL_FN(STUFF_cleanup)); +/* Then the hash table itself can be deallocated */ +lh_STUFF_free(hashtable); +.Ed +.Pp +When doing this, be careful if you delete entries from the hash table in +your callbacks: the table may decrease in size, moving the item that you +are currently on down lower in the hash table \(em this could cause some +entries to be skipped during the iteration. +The second best solution to this problem is to set hash->down_load=0 +before you start (which will stop the hash table ever decreasing in +size). +The best solution is probably to avoid deleting items from the hash +table inside a doall callback! +.Pp +.Fn lh_<type>_doall_arg +is the same as +.Fn lh_<type>_doall +except that +.Fa func +will be called with +.Fa arg +as the second argument and +.Fa func +should be of type +.Vt LHASH_DOALL_ARG_FN_TYPE +(a callback prototype that is passed both the table entry and an extra +argument). +As with +.Fn lh_<type>_doall , +you can instead choose to declare your callback with a prototype +matching the types you are dealing with and use the declare/implement +macros to create compatible wrappers that cast variables before calling +your type-specific callbacks. +An example of this is demonstrated here (printing all hash table entries +to a BIO that is provided by the caller): +.Bd -literal -offset 2n +/* Print item 'a' to 'output_bio' (this is implemented elsewhere) */ +void STUFF_print_doall_arg(const STUFF *a, BIO *output_bio); +/* Implement a prototype-compatible wrapper for "STUFF_print" */ +static IMPLEMENT_LHASH_DOALL_ARG_FN(STUFF, const STUFF, BIO) + /* ... then later in the code ... */ +/* Print out the entire hashtable to a particular BIO */ +lh_STUFF_doall_arg(hashtable, LHASH_DOALL_ARG_FN(STUFF_print), BIO, + logging_bio); +.Ed +.Pp +.Fn lh_<type>_error +can be used to determine if an error occurred in the last operation. +.Fn lh_<type>_error +is a macro. +.Sh RETURN VALUES +.Fn lh_<type>_new +returns +.Dv NULL +on error, otherwise a pointer to the new +.Vt LHASH +structure. +.Pp +When a hash table entry is replaced, +.Fn lh_<type>_insert +returns the value being replaced. +.Dv NULL +is returned on normal operation and on error. +.Pp +.Fn lh_<type>_delete +returns the entry being deleted. +.Dv NULL +is returned if there is no such value in the hash table. +.Pp +.Fn lh_<type>_retrieve +returns the hash table entry if it has been found, or +.Dv NULL +otherwise. +.Pp +.Fn lh_<type>_error +returns 1 if an error occurred in the last operation, or 0 otherwise. +.Pp +.Fn lh_<type>_free , +.Fn lh_<type>_doall , +and +.Fn lh_<type>_doall_arg +return no values. +.Sh NOTES +The various LHASH macros and callback types exist to make it possible to +write type-checked code without resorting to function-prototype casting +\(em an evil that makes application code much harder to audit/verify and +also opens the window of opportunity for stack corruption and other +hard-to-find bugs. +It also, apparently, violates ANSI-C. +.Pp +The LHASH code regards table entries as constant data. +As such, it internally represents +.Fn lh_<type>_insert Ap ed +items with a +.Vt const void * +pointer type. +This is why callbacks such as those used by +.Fn lh_<type>_doall +and +.Fn lh_<type>_doall_arg +declare their prototypes with "const", even for the parameters that pass +back the table items' data pointers \(em for consistency, user-provided +data is "const" at all times as far as the LHASH code is concerned. +However, as callers are themselves providing these pointers, they can +choose whether they too should be treating all such parameters as +constant. +.Pp +As an example, a hash table may be maintained by code that, for +reasons of encapsulation, has only "const" access to the data being +indexed in the hash table (i.e. it is returned as "const" from +elsewhere in their code) \(em in this case the LHASH prototypes are +appropriate as-is. +Conversely, if the caller is responsible for the life-time of the data +in question, then they may well wish to make modifications to table item +passed back in the +.Fn lh_<type>_doall +or +.Fn lh_<type>_doall_arg +callbacks (see the "STUFF_cleanup" example above). +If so, the caller can either cast the "const" away (if they're providing +the raw callbacks themselves) or use the macros to declare/implement the +wrapper functions without "const" types. +.Pp +Callers that only have "const" access to data they are indexing in a +table, yet declare callbacks without constant types (or cast the "const" +away themselves), are therefore creating their own risks/bugs without +being encouraged to do so by the API. +On a related note, those auditing code should pay special attention +to any instances of DECLARE/IMPLEMENT_LHASH_DOALL_[ARG_]_FN macros +that provide types without any "const" qualifiers. +.Sh INTERNALS +The following description is based on the SSLeay documentation: +.Pp +The lhash library implements a hash table described in the +.Em Communications of the ACM +in 1991. +What makes this hash table different is that as the table fills, +the hash table is increased (or decreased) in size via +.Xr OPENSSL_realloc 3 . +When a 'resize' is done, instead of all hashes being redistributed over +twice as many 'buckets', one bucket is split. +So when an 'expand' is done, there is only a minimal cost to +redistribute some values. +Subsequent inserts will cause more single 'bucket' redistributions but +there will never be a sudden large cost due to redistributing all the +\&'buckets'. +.Pp +The state for a particular hash table is kept in the +.Vt LHASH +structure. +The decision to increase or decrease the hash table size is made +depending on the 'load' of the hash table. +The load is the number of items in the hash table divided by the size of +the hash table. +The default values are as follows. +If (hash->up_load < load) => expand. +if (hash->down_load > load) => contract. +The +.Fa up_load +has a default value of 1 and +.Fa down_load +has a default value of 2. +These numbers can be modified by the application by just playing +with the +.Fa up_load +and +.Fa down_load +variables. +The 'load' is kept in a form which is multiplied by 256. +So hash->up_load=8*256 will cause a load of 8 to be set. +.Pp +If you are interested in performance the field to watch is +.Fa num_comp_calls . +The hash library keeps track of the 'hash' value for each item so when a +lookup is done, the 'hashes' are compared, if there is a match, then a +full compare is done, and hash->num_comp_calls is incremented. +If num_comp_calls is not equal to num_delete plus num_retrieve it means +that your hash function is generating hashes that are the same for +different values. +It is probably worth changing your hash function if this is the case +because even if your hash table has 10 items in a 'bucket', it can be +searched with 10 +.Vt unsigned long +compares and 10 linked list traverses. +This will be much less expensive that 10 calls to your compare function. +.Pp +.Fn lh_strhash +is a demo string hashing function: +.Pp +.Dl unsigned long lh_strhash(const char *c); +.Pp +Since the LHASH routines would normally be passed structures, this +routine would not normally be passed to +.Fn lh_<type>_new , +rather it would be used in the function passed to +.Fn lh_<type>_new . +.Sh SEE ALSO +.Xr lh_stats 3 +.Sh HISTORY +The lhash library is available in all versions of SSLeay and OpenSSL. +.Fn lh_<type>_error +was added in SSLeay 0.9.1b. +.Pp +In OpenSSL 0.9.7, all lhash functions that were passed function pointers +were changed for better type safety, and the function types +.Vt LHASH_COMP_FN_TYPE , +.Vt LHASH_HASH_FN_TYPE , +.Vt LHASH_DOALL_FN_TYPE , +and +.Vt LHASH_DOALL_ARG_FN_TYPE +became available. +.Pp +In OpenSSL 1.0.0, the lhash interface was revamped for even better type +checking. +.Sh BUGS +.Fn lh_<type>_insert +returns +.Dv NULL +both for success and error. diff --git a/lib/libcrypto/man/ui_new.3 b/lib/libcrypto/man/ui_new.3 new file mode 100644 index 00000000000..d841c212d8d --- /dev/null +++ b/lib/libcrypto/man/ui_new.3 @@ -0,0 +1,384 @@ +.Dd $Mdocdate: November 12 2015 $ +.Dt UI_NEW 3 +.Os +.Sh NAME +.Nm UI_new , +.Nm UI_new_method , +.Nm UI_free , +.Nm UI_add_input_string , +.Nm UI_dup_input_string , +.Nm UI_add_verify_string , +.Nm UI_dup_verify_string , +.Nm UI_add_input_boolean , +.Nm UI_dup_input_boolean , +.Nm UI_add_info_string , +.Nm UI_dup_info_string , +.Nm UI_add_error_string , +.Nm UI_dup_error_string , +.Nm UI_construct_prompt , +.Nm UI_add_user_data , +.Nm UI_get0_user_data , +.Nm UI_get0_result , +.Nm UI_process , +.Nm UI_ctrl , +.Nm UI_set_default_method , +.Nm UI_get_default_method , +.Nm UI_get_method , +.Nm UI_set_method , +.Nm UI_OpenSSL , +.Nm ERR_load_UI_strings +.Nd New User Interface +.Sh SYNOPSIS +.In openssl/ui.h +.Fd typedef struct ui_st UI; +.Fd typedef struct ui_method_st UI_METHOD; +.Ft UI * +.Fn UI_new void +.Ft UI * +.Fo UI_new_method +.Fa "const UI_METHOD *method" +.Fc +.Ft void +.Fo UI_free +.Fa "UI *ui" +.Fc +.Ft int +.Fo UI_add_input_string +.Fa "UI *ui" +.Fa "const char *prompt" +.Fa "int flags" +.Fa "char *result_buf" +.Fa "int minsize" +.Fa "int maxsize" +.Fc +.Ft int +.Fo UI_dup_input_string +.Fa "UI *ui" +.Fa "const char *prompt" +.Fa "int flags" +.Fa "char *result_buf" +.Fa "int minsize" +.Fa "int maxsize" +.Fc +.Ft int +.Fo UI_add_verify_string +.Fa "UI *ui" +.Fa "const char *prompt" +.Fa "int flags" +.Fa "char *result_buf" +.Fa "int minsize" +.Fa "int maxsize" +.Fa "const char *test_buf" +.Fc +.Ft int +.Fo UI_dup_verify_string +.Fa "UI *ui" +.Fa "const char *prompt" +.Fa "int flags" +.Fa "char *result_buf" +.Fa "int minsize" +.Fa "int maxsize" +.Fa "const char *test_buf" +.Fc +.Ft int +.Fo UI_add_input_boolean +.Fa "UI *ui" +.Fa "const char *prompt" +.Fa "const char *action_desc" +.Fa "const char *ok_chars" +.Fa "const char *cancel_chars" +.Fa "int flags" +.Fa "char *result_buf" +.Fc +.Ft int +.Fo UI_dup_input_boolean +.Fa "UI *ui" +.Fa "const char *prompt" +.Fa "const char *action_desc" +.Fa "const char *ok_chars" +.Fa "const char *cancel_chars" +.Fa "int flags" +.Fa "char *result_buf" +.Fc +.Ft int +.Fo UI_add_info_string +.Fa "UI *ui" +.Fa "const char *text" +.Fc +.Ft int +.Fo UI_dup_info_string +.Fa "UI *ui" +.Fa "const char *text" +.Fc +.Ft int +.Fo UI_add_error_string +.Fa "UI *ui" +.Fa "const char *text" +.Fc +.Ft int +.Fo UI_dup_error_string +.Fa "UI *ui" +.Fa "const char *text" +.Fc +.Fd /* These are the possible flags. They can be OR'ed together. */ +.Fd #define UI_INPUT_FLAG_ECHO 0x01 +.Fd #define UI_INPUT_FLAG_DEFAULT_PWD 0x02 +.Ft char * +.Fo UI_construct_prompt +.Fa "UI *ui_method" +.Fa "const char *object_desc" +.Fa "const char *object_name" +.Fc +.Ft void * +.Fo UI_add_user_data +.Fa "UI *ui" +.Fa "void *user_data" +.Fc +.Ft void * +.Fo UI_get0_user_data +.Fa "UI *ui" +.Fc +.Ft const char * +.Fo UI_get0_result +.Fa "UI *ui" +.Fa "int i" +.Fc +.Ft int +.Fo UI_process +.Fa "UI *ui" +.Fc +.Ft int +.Fo UI_ctrl +.Fa "UI *ui" +.Fa "int cmd" +.Fa "long i" +.Fa "void *p" +.Fa "void (*f)()" +.Fc +.Fd #define UI_CTRL_PRINT_ERRORS 1 +.Fd #define UI_CTRL_IS_REDOABLE 2 +.Ft void +.Fo UI_set_default_method +.Fa "const UI_METHOD *meth" +.Fc +.Ft const UI_METHOD * +.Fo UI_get_default_method +.Fa void +.Fc +.Ft const UI_METHOD * +.Fo UI_get_method +.Fa "UI *ui" +.Fc +.Ft const UI_METHOD * +.Fo UI_set_method +.Fa "UI *ui" +.Fa "const UI_METHOD *meth" +.Fc +.Ft UI_METHOD * +.Fo UI_OpenSSL +.Fa void +.Fc +.Sh DESCRIPTION +UI stands for User Interface, and is general purpose set of routines +to prompt the user for text-based information. +Through user-written methods (see +.Xr ui_create 3 Ns ), +prompting can be done in any way imaginable, be it plain text prompting, +through dialog boxes or from a cell phone. +.Pp +All the functions work through a context of the type +.Vt UI . +This context contains all the information needed to prompt correctly +as well as a reference to a +.Vt UI_METHOD , +which is an ordered vector of functions that carry out the actual +prompting. +.Pp +The first thing to do is to create a +.Vt UI +with +.Fn UI_new +or +.Fn UI_new_method , +then add information to it with the +.Fn UI_add_* +or +.Fn UI_dup_* +functions. +Also, user-defined random data can be passed down to the underlying +method through calls to +.Fn UI_add_user_data . +The default UI method doesn't care about these data, but other methods +might. +Finally, use +.Fn UI_process +to actually perform the prompting and +.Fn UI_get0_result +to find the result to the prompt. +.Pp +A +.Vt UI +can contain more than one prompt, which are performed in the given +sequence. +Each prompt gets an index number which is returned by the +.Fn UI_add_* +and +.Fn UI_dup_* +functions, and has to be used to get the corresponding result with +.Fn UI_get0_result . +.Pp +The functions are as follows: +.Pp +.Fn UI_new +creates a new +.Vt UI +using the default UI method. +When done with this UI, it should be freed using +.Fn UI_free . +.Pp +.Fn UI_new_method +creates a new +.Vt UI +using the given UI method. +When done with this UI, it should be freed using +.Fn UI_free . +.Pp +.Fn UI_OpenSSL +returns the built-in UI method (note: not the default one, since +the default can be changed. +See further on). +This method is the most machine/OS dependent part of OpenSSL and +normally generates the most problems when porting. +.Pp +.Fn UI_free +removes +.Fa ui +from memory, along with all other pieces of memory that are connected +to it, like duplicated input strings, results and others. +.Pp +.Fn UI_add_input_string +and +.Fn UI_add_verify_string +add a prompt to +.Fa ui , +as well as flags and a result buffer and the desired minimum and +maximum sizes of the result. +The given information is used to prompt for information, for example +a password, and to verify a password (i.e. having the user enter +it twice and check that the same string was entered twice). +.Fn UI_add_verify_string +takes and extra argument that should be a pointer to the result buffer +of the input string that it's supposed to verify, or verification will +fail. +.Pp +.Fn UI_add_input_boolean +adds a prompt to +.Fa ui +that's supposed to be answered in a boolean way, with a single +character for yes and a different character for no. +A set of characters that can be used to cancel the prompt is given as +well. +The prompt itself is really divided in two, one part being the +descriptive text (given through the +.Fa prompt +argument) and one describing the possible answers (given through the +.Fa action_desc +argument). +.Pp +.Fn UI_add_info_string +and +.Fn UI_add_error_string +add strings that are shown at the same time as the prompt for extra +information or to show an error string. +The difference between the two is only conceptual. +With the builtin method, there's no technical difference between them. +Other methods may make a difference between them, however. +.Pp +The flags currently supported are +.Dv UI_INPUT_FLAG_ECHO, +which is relevant for +.Fn UI_add_input_string +and will have the users response be echoed (when prompting for a +password, this flag should obviously not be used), and +.Dv UI_INPUT_FLAG_DEFAULT_PWD , +which means that a default password of some sort will be used +(completely depending on the application and the UI method). +.Pp +.Fn UI_dup_input_string , +.Fn UI_dup_verify_string , +.Fn UI_dup_input_boolean , +.Fn UI_dup_info_string , +and +.Fn UI_dup_error_string +are basically the same as their +.Fn UI_add_* +counterparts, except that they make their own copies of all strings. +.Pp +.Fn UI_construct_prompt +is a helper function that can be used to create a prompt from two pieces +of information: an description and a name. +The default constructor (if there is none provided by the method used) +creates a string "Enter +.Em description +for +.Em name Ns :". +With the description "pass phrase" and the file name "foo.key", that +becomes "Enter pass phrase for foo.key:". Other methods may create +whatever string and may include encodings that will be processed by the +other method functions. +.Pp +.Fn UI_add_user_data +adds a piece of memory for the method to use at any time. +The builtin UI method doesn't care about this info. +Note that several calls to this function doesn't add data, it replaces +the previous blob with the one given as argument. +.Pp +.Fn UI_get0_user_data +retrieves the data that has last been given to the +.Fa ui +with +.Fn UI_add_user_data . +.Pp +.Fn UI_get0_result +returns a pointer to the result buffer associated with the information +indexed by +.Fa i . +.Pp +.Fn UI_process +goes through the information given so far, does all the printing and +prompting and returns. +.Pp +.Fn UI_ctrl +adds extra control for the application author. +For now, it understands two commands: +.Dv UI_CTRL_PRINT_ERRORS , +which makes +.Fn UI_process +print the OpenSSL error stack as part of processing the +.Fa ui , +and +.Dv UI_CTRL_IS_REDOABLE , +which returns a flag saying if the used +.Fa ui +can be used again or not. +.Pp +.Fn UI_set_default_method +changes the default UI method to the one given. +.Pp +.Fn UI_get_default_method +returns a pointer to the current default UI method. +.Pp +.Fn UI_get_method +returns the UI method associated with a given +.Fa ui . +.Pp +.Fn UI_set_method +changes the UI method associated with a given +.Fa ui . +.Sh SEE ALSO +.Xr des_read_pw 3 +.Sh HISTORY +The UI section was first introduced in OpenSSL 0.9.7. +.Sh AUTHORS +.An Richard Levitte Aq Mt richard@levitte.org +for the OpenSSL project. diff --git a/lib/libssl/src/doc/crypto/bn_internal.pod b/lib/libssl/src/doc/crypto/bn_internal.pod deleted file mode 100644 index 9c59ed623b4..00000000000 --- a/lib/libssl/src/doc/crypto/bn_internal.pod +++ /dev/null @@ -1,238 +0,0 @@ -=pod - -=head1 NAME - -bn_mul_words, bn_mul_add_words, bn_sqr_words, bn_div_words, -bn_add_words, bn_sub_words, bn_mul_comba4, bn_mul_comba8, -bn_sqr_comba4, bn_sqr_comba8, bn_cmp_words, bn_mul_normal, -bn_mul_low_normal, bn_mul_recursive, bn_mul_part_recursive, -bn_mul_low_recursive, bn_mul_high, bn_sqr_normal, bn_sqr_recursive, -bn_expand, bn_wexpand, bn_expand2, bn_fix_top, bn_check_top, -bn_print, bn_dump, bn_set_max, bn_set_high, bn_set_low, sqr -- BIGNUM library internal functions - -=head1 SYNOPSIS - - #include <openssl/bn.h> - - BN_ULONG bn_mul_words(BN_ULONG *rp, BN_ULONG *ap, int num, BN_ULONG w); - BN_ULONG bn_mul_add_words(BN_ULONG *rp, BN_ULONG *ap, int num, - BN_ULONG w); - void bn_sqr_words(BN_ULONG *rp, BN_ULONG *ap, int num); - BN_ULONG bn_div_words(BN_ULONG h, BN_ULONG l, BN_ULONG d); - BN_ULONG bn_add_words(BN_ULONG *rp, BN_ULONG *ap, BN_ULONG *bp, - int num); - BN_ULONG bn_sub_words(BN_ULONG *rp, BN_ULONG *ap, BN_ULONG *bp, - int num); - - void bn_mul_comba4(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b); - void bn_mul_comba8(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b); - void bn_sqr_comba4(BN_ULONG *r, BN_ULONG *a); - void bn_sqr_comba8(BN_ULONG *r, BN_ULONG *a); - - int bn_cmp_words(BN_ULONG *a, BN_ULONG *b, int n); - - void bn_mul_normal(BN_ULONG *r, BN_ULONG *a, int na, BN_ULONG *b, - int nb); - void bn_mul_low_normal(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, int n); - void bn_mul_recursive(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, int n2, - int dna,int dnb,BN_ULONG *tmp); - void bn_mul_part_recursive(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, - int n, int tna,int tnb, BN_ULONG *tmp); - void bn_mul_low_recursive(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, - int n2, BN_ULONG *tmp); - void bn_mul_high(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, BN_ULONG *l, - int n2, BN_ULONG *tmp); - - void bn_sqr_normal(BN_ULONG *r, BN_ULONG *a, int n, BN_ULONG *tmp); - void bn_sqr_recursive(BN_ULONG *r, BN_ULONG *a, int n2, BN_ULONG *tmp); - - void mul(BN_ULONG r, BN_ULONG a, BN_ULONG w, BN_ULONG c); - void mul_add(BN_ULONG r, BN_ULONG a, BN_ULONG w, BN_ULONG c); - void sqr(BN_ULONG r0, BN_ULONG r1, BN_ULONG a); - - BIGNUM *bn_expand(BIGNUM *a, int bits); - BIGNUM *bn_wexpand(BIGNUM *a, int n); - BIGNUM *bn_expand2(BIGNUM *a, int n); - void bn_fix_top(BIGNUM *a); - - void bn_check_top(BIGNUM *a); - void bn_print(BIGNUM *a); - void bn_dump(BN_ULONG *d, int n); - void bn_set_max(BIGNUM *a); - void bn_set_high(BIGNUM *r, BIGNUM *a, int n); - void bn_set_low(BIGNUM *r, BIGNUM *a, int n); - -=head1 DESCRIPTION - -This page documents the internal functions used by the OpenSSL -B<BIGNUM> implementation. They are described here to facilitate -debugging and extending the library. They are I<not> to be used by -applications. - -=head2 The BIGNUM structure - - typedef struct bignum_st BIGNUM; - - struct bignum_st - { - BN_ULONG *d; /* Pointer to an array of 'BN_BITS2' bit chunks. */ - int top; /* Index of last used d +1. */ - /* The next are internal book keeping for bn_expand. */ - int dmax; /* Size of the d array. */ - int neg; /* one if the number is negative */ - int flags; - }; - - -The integer value is stored in B<d>, a malloc()ed array of words (B<BN_ULONG>), -least significant word first. A B<BN_ULONG> can be either 16, 32 or 64 bits -in size, depending on the 'number of bits' (B<BITS2>) specified in -C<openssl/bn.h>. - -B<dmax> is the size of the B<d> array that has been allocated. B<top> -is the number of words being used, so for a value of 4, bn.d[0]=4 and -bn.top=1. B<neg> is 1 if the number is negative. When a B<BIGNUM> is -B<0>, the B<d> field can be B<NULL> and B<top> == B<0>. - -B<flags> is a bit field of flags which are defined in C<openssl/bn.h>. The -flags begin with B<BN_FLG_>. The macros BN_set_flags(b,n) and -BN_get_flags(b,n) exist to enable or fetch flag(s) B<n> from B<BIGNUM> -structure B<b>. - -Various routines in this library require the use of temporary -B<BIGNUM> variables during their execution. Since dynamic memory -allocation to create B<BIGNUM>s is rather expensive when used in -conjunction with repeated subroutine calls, the B<BN_CTX> structure is -used. This structure contains B<BN_CTX_NUM> B<BIGNUM>s, see -L<BN_CTX_start(3)|BN_CTX_start(3)>. - -=head2 Low-level arithmetic operations - -These functions are implemented in C and for several platforms in -assembly language: - -bn_mul_words(B<rp>, B<ap>, B<num>, B<w>) operates on the B<num> word -arrays B<rp> and B<ap>. It computes B<ap> * B<w>, places the result -in B<rp>, and returns the high word (carry). - -bn_mul_add_words(B<rp>, B<ap>, B<num>, B<w>) operates on the B<num> -word arrays B<rp> and B<ap>. It computes B<ap> * B<w> + B<rp>, places -the result in B<rp>, and returns the high word (carry). - -bn_sqr_words(B<rp>, B<ap>, B<n>) operates on the B<num> word array -B<ap> and the 2*B<num> word array B<ap>. It computes B<ap> * B<ap> -word-wise, and places the low and high bytes of the result in B<rp>. - -bn_div_words(B<h>, B<l>, B<d>) divides the two word number (B<h>,B<l>) -by B<d> and returns the result. - -bn_add_words(B<rp>, B<ap>, B<bp>, B<num>) operates on the B<num> word -arrays B<ap>, B<bp> and B<rp>. It computes B<ap> + B<bp>, places the -result in B<rp>, and returns the high word (carry). - -bn_sub_words(B<rp>, B<ap>, B<bp>, B<num>) operates on the B<num> word -arrays B<ap>, B<bp> and B<rp>. It computes B<ap> - B<bp>, places the -result in B<rp>, and returns the carry (1 if B<bp> E<gt> B<ap>, 0 -otherwise). - -bn_mul_comba4(B<r>, B<a>, B<b>) operates on the 4 word arrays B<a> and -B<b> and the 8 word array B<r>. It computes B<a>*B<b> and places the -result in B<r>. - -bn_mul_comba8(B<r>, B<a>, B<b>) operates on the 8 word arrays B<a> and -B<b> and the 16 word array B<r>. It computes B<a>*B<b> and places the -result in B<r>. - -bn_sqr_comba4(B<r>, B<a>, B<b>) operates on the 4 word arrays B<a> and -B<b> and the 8 word array B<r>. - -bn_sqr_comba8(B<r>, B<a>, B<b>) operates on the 8 word arrays B<a> and -B<b> and the 16 word array B<r>. - -The following functions are implemented in C: - -bn_cmp_words(B<a>, B<b>, B<n>) operates on the B<n> word arrays B<a> -and B<b>. It returns 1, 0 and -1 if B<a> is greater than, equal and -less than B<b>. - -bn_mul_normal(B<r>, B<a>, B<na>, B<b>, B<nb>) operates on the B<na> -word array B<a>, the B<nb> word array B<b> and the B<na>+B<nb> word -array B<r>. It computes B<a>*B<b> and places the result in B<r>. - -bn_mul_low_normal(B<r>, B<a>, B<b>, B<n>) operates on the B<n> word -arrays B<r>, B<a> and B<b>. It computes the B<n> low words of -B<a>*B<b> and places the result in B<r>. - -bn_mul_recursive(B<r>, B<a>, B<b>, B<n2>, B<dna>, B<dnb>, B<t>) operates -on the word arrays B<a> and B<b> of length B<n2>+B<dna> and B<n2>+B<dnb> -(B<dna> and B<dnb> are currently allowed to be 0 or negative) and the 2*B<n2> -word arrays B<r> and B<t>. B<n2> must be a power of 2. It computes -B<a>*B<b> and places the result in B<r>. - -bn_mul_part_recursive(B<r>, B<a>, B<b>, B<n>, B<tna>, B<tnb>, B<tmp>) -operates on the word arrays B<a> and B<b> of length B<n>+B<tna> and -B<n>+B<tnb> and the 4*B<n> word arrays B<r> and B<tmp>. - -bn_mul_low_recursive(B<r>, B<a>, B<b>, B<n2>, B<tmp>) operates on the -B<n2> word arrays B<r> and B<tmp> and the B<n2>/2 word arrays B<a> -and B<b>. - -bn_mul_high(B<r>, B<a>, B<b>, B<l>, B<n2>, B<tmp>) operates on the -B<n2> word arrays B<r>, B<a>, B<b> and B<l> (?) and the 3*B<n2> word -array B<tmp>. - -BN_mul() calls bn_mul_normal(), or an optimized implementation if the -factors have the same size: bn_mul_comba8() is used if they are 8 -words long, bn_mul_recursive() if they are larger than -B<BN_MULL_SIZE_NORMAL> and the size is an exact multiple of the word -size, and bn_mul_part_recursive() for others that are larger than -B<BN_MULL_SIZE_NORMAL>. - -bn_sqr_normal(B<r>, B<a>, B<n>, B<tmp>) operates on the B<n> word array -B<a> and the 2*B<n> word arrays B<tmp> and B<r>. - -The implementations use the following macros which, depending on the -architecture, may use "long long" C operations or inline assembler. -They are defined in C<bn_lcl.h>. - -mul(B<r>, B<a>, B<w>, B<c>) computes B<w>*B<a>+B<c> and places the -low word of the result in B<r> and the high word in B<c>. - -mul_add(B<r>, B<a>, B<w>, B<c>) computes B<w>*B<a>+B<r>+B<c> and -places the low word of the result in B<r> and the high word in B<c>. - -sqr(B<r0>, B<r1>, B<a>) computes B<a>*B<a> and places the low word -of the result in B<r0> and the high word in B<r1>. - -=head2 Size changes - -bn_expand() ensures that B<b> has enough space for a B<bits> bit -number. bn_wexpand() ensures that B<b> has enough space for an -B<n> word number. If the number has to be expanded, both macros -call bn_expand2(), which allocates a new B<d> array and copies the -data. They return B<NULL> on error, B<b> otherwise. - -The bn_fix_top() macro reduces B<a-E<gt>top> to point to the most -significant non-zero word plus one when B<a> has shrunk. - -=head2 Debugging - -bn_check_top() verifies that C<((a)-E<gt>top E<gt>= 0 && (a)-E<gt>top -E<lt>= (a)-E<gt>dmax)>. A violation will cause the program to abort. - -bn_print() prints B<a> to stderr. bn_dump() prints B<n> words at B<d> -(in reverse order, i.e. most significant word first) to stderr. - -bn_set_max() makes B<a> a static number with a B<dmax> of its current size. -This is used by bn_set_low() and bn_set_high() to make B<r> a read-only -B<BIGNUM> that contains the B<n> low or high words of B<a>. - -If B<BN_DEBUG> is not defined, bn_check_top(), bn_print(), bn_dump() -and bn_set_max() are defined as empty macros. - -=head1 SEE ALSO - -L<bn(3)|bn(3)> - -=cut diff --git a/lib/libssl/src/doc/crypto/d2i_PKCS8PrivateKey.pod b/lib/libssl/src/doc/crypto/d2i_PKCS8PrivateKey.pod deleted file mode 100644 index fc7335c7a12..00000000000 --- a/lib/libssl/src/doc/crypto/d2i_PKCS8PrivateKey.pod +++ /dev/null @@ -1,58 +0,0 @@ -=pod - -=head1 NAME - -d2i_PKCS8PrivateKey_bio, d2i_PKCS8PrivateKey_fp, i2d_PKCS8PrivateKey_bio, -i2d_PKCS8PrivateKey_fp, i2d_PKCS8PrivateKey_nid_bio, i2d_PKCS8PrivateKey_nid_fp -- PKCS#8 format private key functions - -=head1 SYNOPSIS - - #include <openssl/evp.h> - - EVP_PKEY *d2i_PKCS8PrivateKey_bio(BIO *bp, EVP_PKEY **x, pem_password_cb *cb, void *u); - EVP_PKEY *d2i_PKCS8PrivateKey_fp(FILE *fp, EVP_PKEY **x, pem_password_cb *cb, void *u); - - int i2d_PKCS8PrivateKey_bio(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc, - char *kstr, int klen, - pem_password_cb *cb, void *u); - - int i2d_PKCS8PrivateKey_fp(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc, - char *kstr, int klen, - pem_password_cb *cb, void *u); - - int i2d_PKCS8PrivateKey_nid_bio(BIO *bp, EVP_PKEY *x, int nid, - char *kstr, int klen, - pem_password_cb *cb, void *u); - - int i2d_PKCS8PrivateKey_nid_fp(FILE *fp, EVP_PKEY *x, int nid, - char *kstr, int klen, - pem_password_cb *cb, void *u); - -=head1 DESCRIPTION - -The PKCS#8 functions encode and decode private keys in PKCS#8 format using both -PKCS#5 v1.5 and PKCS#5 v2.0 password based encryption algorithms. - -Other than the use of DER as opposed to PEM these functions are identical to the -corresponding B<PEM> function as described in the L<pem(3)|pem(3)> manual page. - -=head1 NOTES - -Before using these functions -L<OpenSSL_add_all_algorithms(3)|OpenSSL_add_all_algorithms(3)> should be called -to initialize the internal algorithm lookup tables otherwise errors about -unknown algorithms will occur if an attempt is made to decrypt a private key. - -These functions are currently the only way to store encrypted private keys -using DER format. - -Currently all the functions use BIOs or FILE pointers, there are no functions -which work directly on memory: this can be readily worked around by converting -the buffers to memory BIOs, see L<BIO_s_mem(3)|BIO_s_mem(3)> for details. - -=head1 SEE ALSO - -L<pem(3)|pem(3)> - -=cut diff --git a/lib/libssl/src/doc/crypto/ecdsa.pod b/lib/libssl/src/doc/crypto/ecdsa.pod deleted file mode 100644 index 9e9608155a7..00000000000 --- a/lib/libssl/src/doc/crypto/ecdsa.pod +++ /dev/null @@ -1,205 +0,0 @@ -=pod - -=head1 NAME - -ECDSA_SIG_new, ECDSA_SIG_free, i2d_ECDSA_SIG, d2i_ECDSA_SIG, -ECDSA_size, ECDSA_sign_setup, ECDSA_sign, ECDSA_sign_ex, -ECDSA_verify, ECDSA_do_sign, ECDSA_do_sign_ex, ECDSA_do_verify, -ECDSA_OpenSSL, ECDSA_get_default_method, ECDSA_get_ex_data, -ECDSA_get_ex_new_index, ECDSA_set_default_method, ECDSA_set_ex_data, -ECDSA_set_method - Elliptic Curve Digital Signature Algorithm - -=head1 SYNOPSIS - - #include <openssl/ecdsa.h> - - ECDSA_SIG* ECDSA_SIG_new(void); - void ECDSA_SIG_free(ECDSA_SIG *sig); - int i2d_ECDSA_SIG(const ECDSA_SIG *sig, unsigned char **pp); - ECDSA_SIG* d2i_ECDSA_SIG(ECDSA_SIG **sig, const unsigned char **pp, - long len); - - ECDSA_SIG* ECDSA_do_sign(const unsigned char *dgst, int dgst_len, - EC_KEY *eckey); - ECDSA_SIG* ECDSA_do_sign_ex(const unsigned char *dgst, int dgstlen, - const BIGNUM *kinv, const BIGNUM *rp, - EC_KEY *eckey); - int ECDSA_do_verify(const unsigned char *dgst, int dgst_len, - const ECDSA_SIG *sig, EC_KEY* eckey); - int ECDSA_sign_setup(EC_KEY *eckey, BN_CTX *ctx, - BIGNUM **kinv, BIGNUM **rp); - int ECDSA_sign(int type, const unsigned char *dgst, - int dgstlen, unsigned char *sig, - unsigned int *siglen, EC_KEY *eckey); - int ECDSA_sign_ex(int type, const unsigned char *dgst, - int dgstlen, unsigned char *sig, - unsigned int *siglen, const BIGNUM *kinv, - const BIGNUM *rp, EC_KEY *eckey); - int ECDSA_verify(int type, const unsigned char *dgst, - int dgstlen, const unsigned char *sig, - int siglen, EC_KEY *eckey); - int ECDSA_size(const EC_KEY *eckey); - - const ECDSA_METHOD* ECDSA_OpenSSL(void); - void ECDSA_set_default_method(const ECDSA_METHOD *meth); - const ECDSA_METHOD* ECDSA_get_default_method(void); - int ECDSA_set_method(EC_KEY *eckey,const ECDSA_METHOD *meth); - - int ECDSA_get_ex_new_index(long argl, void *argp, - CRYPTO_EX_new *new_func, - CRYPTO_EX_dup *dup_func, - CRYPTO_EX_free *free_func); - int ECDSA_set_ex_data(EC_KEY *d, int idx, void *arg); - void* ECDSA_get_ex_data(EC_KEY *d, int idx); - -=head1 DESCRIPTION - -The B<ECDSA_SIG> structure consists of two BIGNUMs for the -r and s value of a ECDSA signature (see X9.62 or FIPS 186-2). - - struct - { - BIGNUM *r; - BIGNUM *s; - } ECDSA_SIG; - -ECDSA_SIG_new() allocates a new B<ECDSA_SIG> structure (note: this -function also allocates the BIGNUMs) and initialize it. - -ECDSA_SIG_free() frees the B<ECDSA_SIG> structure B<sig>. - -i2d_ECDSA_SIG() creates the DER encoding of the ECDSA signature -B<sig> and writes the encoded signature to B<*pp> (note: if B<pp> -is NULL B<i2d_ECDSA_SIG> returns the expected length in bytes of -the DER encoded signature). B<i2d_ECDSA_SIG> returns the length -of the DER encoded signature (or 0 on error). - -d2i_ECDSA_SIG() decodes a DER encoded ECDSA signature and returns -the decoded signature in a newly allocated B<ECDSA_SIG> structure. -B<*sig> points to the buffer containing the DER encoded signature -of size B<len>. - -ECDSA_size() returns the maximum length of a DER encoded -ECDSA signature created with the private EC key B<eckey>. - -ECDSA_sign_setup() may be used to precompute parts of the -signing operation. B<eckey> is the private EC key and B<ctx> -is a pointer to B<BN_CTX> structure (or NULL). The precomputed -values or returned in B<kinv> and B<rp> and can be used in a -later call to B<ECDSA_sign_ex> or B<ECDSA_do_sign_ex>. - -ECDSA_sign() is wrapper function for ECDSA_sign_ex with B<kinv> -and B<rp> set to NULL. - -ECDSA_sign_ex() computes a digital signature of the B<dgstlen> bytes -hash value B<dgst> using the private EC key B<eckey> and the optional -pre-computed values B<kinv> and B<rp>. The DER encoded signatures is -stored in B<sig> and it's length is returned in B<sig_len>. Note: B<sig> -must point to B<ECDSA_size> bytes of memory. The parameter B<type> -is ignored. - -ECDSA_verify() verifies that the signature in B<sig> of size -B<siglen> is a valid ECDSA signature of the hash value -B<dgst> of size B<dgstlen> using the public key B<eckey>. -The parameter B<type> is ignored. - -ECDSA_do_sign() is wrapper function for ECDSA_do_sign_ex with B<kinv> -and B<rp> set to NULL. - -ECDSA_do_sign_ex() computes a digital signature of the B<dgst_len> -bytes hash value B<dgst> using the private key B<eckey> and the -optional pre-computed values B<kinv> and B<rp>. The signature is -returned in a newly allocated B<ECDSA_SIG> structure (or NULL on error). - -ECDSA_do_verify() verifies that the signature B<sig> is a valid -ECDSA signature of the hash value B<dgst> of size B<dgst_len> -using the public key B<eckey>. - -=head1 RETURN VALUES - -ECDSA_size() returns the maximum length signature or 0 on error. - -ECDSA_sign_setup() and ECDSA_sign() return 1 if successful or 0 -on error. - -ECDSA_verify() and ECDSA_do_verify() return 1 for a valid -signature, 0 for an invalid signature and -1 on error. -The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. - -=head1 EXAMPLES - -Creating a ECDSA signature of given SHA-1 hash value using the -named curve secp192k1. - -First step: create a EC_KEY object (note: this part is B<not> ECDSA -specific) - - int ret; - ECDSA_SIG *sig; - EC_KEY *eckey; - - eckey = EC_KEY_new_by_curve_name(NID_secp192k1); - if (eckey == NULL) { - /* error */ - } - if (!EC_KEY_generate_key(eckey)) { - /* error */ - } - -Second step: compute the ECDSA signature of a SHA-1 hash value -using B<ECDSA_do_sign> - - sig = ECDSA_do_sign(digest, 20, eckey); - if (sig == NULL) { - /* error */ - } - -or using B<ECDSA_sign> - - unsigned char *buffer, *pp; - int buf_len; - - buf_len = ECDSA_size(eckey); - buffer = malloc(buf_len); - pp = buffer; - if (!ECDSA_sign(0, dgst, dgstlen, pp, &buf_len, eckey) { - /* error */ - } - -Third step: verify the created ECDSA signature using B<ECDSA_do_verify> - - ret = ECDSA_do_verify(digest, 20, sig, eckey); - -or using B<ECDSA_verify> - - ret = ECDSA_verify(0, digest, 20, buffer, buf_len, eckey); - -and finally evaluate the return value: - - if (ret == -1) { - /* error */ - } else if (ret == 0) { - /* incorrect signature */ - } else { - /* ret == 1 */ - /* signature ok */ - } - -=head1 CONFORMING TO - -ANSI X9.62, US Federal Information Processing Standard FIPS 186-2 -(Digital Signature Standard, DSS) - -=head1 SEE ALSO - -L<dsa(3)|dsa(3)>, L<rsa(3)|rsa(3)> - -=head1 HISTORY - -The ecdsa implementation was first introduced in OpenSSL 0.9.8 - -=head1 AUTHOR - -Nils Larsch for the OpenSSL project (http://www.openssl.org). - -=cut diff --git a/lib/libssl/src/doc/crypto/lhash.pod b/lib/libssl/src/doc/crypto/lhash.pod deleted file mode 100644 index a9c44dd9ef3..00000000000 --- a/lib/libssl/src/doc/crypto/lhash.pod +++ /dev/null @@ -1,303 +0,0 @@ -=pod - -=head1 NAME - -lh_new, lh_free, lh_insert, lh_delete, lh_retrieve, lh_doall, lh_doall_arg, -lh_error - dynamic hash table - -=head1 SYNOPSIS - - #include <openssl/lhash.h> - - DECLARE_LHASH_OF(<type>); - - LHASH *lh_<type>_new(); - void lh_<type>_free(LHASH_OF(<type> *table); - - <type> *lh_<type>_insert(LHASH_OF(<type> *table, <type> *data); - <type> *lh_<type>_delete(LHASH_OF(<type> *table, <type> *data); - <type> *lh_retrieve(LHASH_OF<type> *table, <type> *data); - - void lh_<type>_doall(LHASH_OF(<type> *table, LHASH_DOALL_FN_TYPE func); - void lh_<type>_doall_arg(LHASH_OF(<type> *table, LHASH_DOALL_ARG_FN_TYPE func, - <type2>, <type2> *arg); - - int lh_<type>_error(LHASH_OF(<type> *table); - - typedef int (*LHASH_COMP_FN_TYPE)(const void *, const void *); - typedef unsigned long (*LHASH_HASH_FN_TYPE)(const void *); - typedef void (*LHASH_DOALL_FN_TYPE)(const void *); - typedef void (*LHASH_DOALL_ARG_FN_TYPE)(const void *, const void *); - -=head1 DESCRIPTION - -This library implements type-checked dynamic hash tables. The hash -table entries can be arbitrary structures. Usually they consist of key -and value fields. - -lh_<type>_new() creates a new B<LHASH_OF(<type>> structure to store -arbitrary data entries, and provides the 'hash' and 'compare' -callbacks to be used in organising the table's entries. The B<hash> -callback takes a pointer to a table entry as its argument and returns -an unsigned long hash value for its key field. The hash value is -normally truncated to a power of 2, so make sure that your hash -function returns well mixed low order bits. The B<compare> callback -takes two arguments (pointers to two hash table entries), and returns -0 if their keys are equal, non-zero otherwise. If your hash table -will contain items of some particular type and the B<hash> and -B<compare> callbacks hash/compare these types, then the -B<DECLARE_LHASH_HASH_FN> and B<IMPLEMENT_LHASH_COMP_FN> macros can be -used to create callback wrappers of the prototypes required by -lh_<type>_new(). These provide per-variable casts before calling the -type-specific callbacks written by the application author. These -macros, as well as those used for the "doall" callbacks, are defined -as; - - #define DECLARE_LHASH_HASH_FN(name, o_type) \ - unsigned long name##_LHASH_HASH(const void *); - #define IMPLEMENT_LHASH_HASH_FN(name, o_type) \ - unsigned long name##_LHASH_HASH(const void *arg) { \ - const o_type *a = arg; \ - return name##_hash(a); } - #define LHASH_HASH_FN(name) name##_LHASH_HASH - - #define DECLARE_LHASH_COMP_FN(name, o_type) \ - int name##_LHASH_COMP(const void *, const void *); - #define IMPLEMENT_LHASH_COMP_FN(name, o_type) \ - int name##_LHASH_COMP(const void *arg1, const void *arg2) { \ - const o_type *a = arg1; \ - const o_type *b = arg2; \ - return name##_cmp(a,b); } - #define LHASH_COMP_FN(name) name##_LHASH_COMP - - #define DECLARE_LHASH_DOALL_FN(name, o_type) \ - void name##_LHASH_DOALL(void *); - #define IMPLEMENT_LHASH_DOALL_FN(name, o_type) \ - void name##_LHASH_DOALL(void *arg) { \ - o_type *a = arg; \ - name##_doall(a); } - #define LHASH_DOALL_FN(name) name##_LHASH_DOALL - - #define DECLARE_LHASH_DOALL_ARG_FN(name, o_type, a_type) \ - void name##_LHASH_DOALL_ARG(void *, void *); - #define IMPLEMENT_LHASH_DOALL_ARG_FN(name, o_type, a_type) \ - void name##_LHASH_DOALL_ARG(void *arg1, void *arg2) { \ - o_type *a = arg1; \ - a_type *b = arg2; \ - name##_doall_arg(a, b); } - #define LHASH_DOALL_ARG_FN(name) name##_LHASH_DOALL_ARG - - An example of a hash table storing (pointers to) structures of type 'STUFF' - could be defined as follows; - - /* Calculates the hash value of 'tohash' (implemented elsewhere) */ - unsigned long STUFF_hash(const STUFF *tohash); - /* Orders 'arg1' and 'arg2' (implemented elsewhere) */ - int stuff_cmp(const STUFF *arg1, const STUFF *arg2); - /* Create the type-safe wrapper functions for use in the LHASH internals */ - static IMPLEMENT_LHASH_HASH_FN(stuff, STUFF); - static IMPLEMENT_LHASH_COMP_FN(stuff, STUFF); - /* ... */ - int main(int argc, char *argv[]) { - /* Create the new hash table using the hash/compare wrappers */ - LHASH_OF(STUFF) *hashtable = lh_STUFF_new(LHASH_HASH_FN(STUFF_hash), - LHASH_COMP_FN(STUFF_cmp)); - /* ... */ - } - -lh_<type>_free() frees the B<LHASH_OF(<type>> structure -B<table>. Allocated hash table entries will not be freed; consider -using lh_<type>_doall() to deallocate any remaining entries in the -hash table (see below). - -lh_<type>_insert() inserts the structure pointed to by B<data> into -B<table>. If there already is an entry with the same key, the old -value is replaced. Note that lh_<type>_insert() stores pointers, the -data are not copied. - -lh_<type>_delete() deletes an entry from B<table>. - -lh_<type>_retrieve() looks up an entry in B<table>. Normally, B<data> -is a structure with the key field(s) set; the function will return a -pointer to a fully populated structure. - -lh_<type>_doall() will, for every entry in the hash table, call -B<func> with the data item as its parameter. For lh_<type>_doall() -and lh_<type>_doall_arg(), function pointer casting should be avoided -in the callbacks (see B<NOTE>) - instead use the declare/implement -macros to create type-checked wrappers that cast variables prior to -calling your type-specific callbacks. An example of this is -illustrated here where the callback is used to cleanup resources for -items in the hash table prior to the hashtable itself being -deallocated: - - /* Cleans up resources belonging to 'a' (this is implemented elsewhere) */ - void STUFF_cleanup_doall(STUFF *a); - /* Implement a prototype-compatible wrapper for "STUFF_cleanup" */ - IMPLEMENT_LHASH_DOALL_FN(STUFF_cleanup, STUFF) - /* ... then later in the code ... */ - /* So to run "STUFF_cleanup" against all items in a hash table ... */ - lh_STUFF_doall(hashtable, LHASH_DOALL_FN(STUFF_cleanup)); - /* Then the hash table itself can be deallocated */ - lh_STUFF_free(hashtable); - -When doing this, be careful if you delete entries from the hash table -in your callbacks: the table may decrease in size, moving the item -that you are currently on down lower in the hash table - this could -cause some entries to be skipped during the iteration. The second -best solution to this problem is to set hash-E<gt>down_load=0 before -you start (which will stop the hash table ever decreasing in size). -The best solution is probably to avoid deleting items from the hash -table inside a "doall" callback! - -lh_<type>_doall_arg() is the same as lh_<type>_doall() except that -B<func> will be called with B<arg> as the second argument and B<func> -should be of type B<LHASH_DOALL_ARG_FN_TYPE> (a callback prototype -that is passed both the table entry and an extra argument). As with -lh_doall(), you can instead choose to declare your callback with a -prototype matching the types you are dealing with and use the -declare/implement macros to create compatible wrappers that cast -variables before calling your type-specific callbacks. An example of -this is demonstrated here (printing all hash table entries to a BIO -that is provided by the caller): - - /* Prints item 'a' to 'output_bio' (this is implemented elsewhere) */ - void STUFF_print_doall_arg(const STUFF *a, BIO *output_bio); - /* Implement a prototype-compatible wrapper for "STUFF_print" */ - static IMPLEMENT_LHASH_DOALL_ARG_FN(STUFF, const STUFF, BIO) - /* ... then later in the code ... */ - /* Print out the entire hashtable to a particular BIO */ - lh_STUFF_doall_arg(hashtable, LHASH_DOALL_ARG_FN(STUFF_print), BIO, - logging_bio); - -lh_<type>_error() can be used to determine if an error occurred in the last -operation. lh_<type>_error() is a macro. - -=head1 RETURN VALUES - -lh_<type>_new() returns B<NULL> on error, otherwise a pointer to the new -B<LHASH> structure. - -When a hash table entry is replaced, lh_<type>_insert() returns the value -being replaced. B<NULL> is returned on normal operation and on error. - -lh_<type>_delete() returns the entry being deleted. B<NULL> is returned if -there is no such value in the hash table. - -lh_<type>_retrieve() returns the hash table entry if it has been found, -B<NULL> otherwise. - -lh_<type>_error() returns 1 if an error occurred in the last operation, 0 -otherwise. - -lh_<type>_free(), lh_<type>_doall() and lh_<type>_doall_arg() return no values. - -=head1 NOTE - -The various LHASH macros and callback types exist to make it possible -to write type-checked code without resorting to function-prototype -casting - an evil that makes application code much harder to -audit/verify and also opens the window of opportunity for stack -corruption and other hard-to-find bugs. It also, apparently, violates -ANSI-C. - -The LHASH code regards table entries as constant data. As such, it -internally represents lh_insert()'d items with a "const void *" -pointer type. This is why callbacks such as those used by lh_doall() -and lh_doall_arg() declare their prototypes with "const", even for the -parameters that pass back the table items' data pointers - for -consistency, user-provided data is "const" at all times as far as the -LHASH code is concerned. However, as callers are themselves providing -these pointers, they can choose whether they too should be treating -all such parameters as constant. - -As an example, a hash table may be maintained by code that, for -reasons of encapsulation, has only "const" access to the data being -indexed in the hash table (ie. it is returned as "const" from -elsewhere in their code) - in this case the LHASH prototypes are -appropriate as-is. Conversely, if the caller is responsible for the -life-time of the data in question, then they may well wish to make -modifications to table item passed back in the lh_doall() or -lh_doall_arg() callbacks (see the "STUFF_cleanup" example above). If -so, the caller can either cast the "const" away (if they're providing -the raw callbacks themselves) or use the macros to declare/implement -the wrapper functions without "const" types. - -Callers that only have "const" access to data they're indexing in a -table, yet declare callbacks without constant types (or cast the -"const" away themselves), are therefore creating their own risks/bugs -without being encouraged to do so by the API. On a related note, -those auditing code should pay special attention to any instances of -DECLARE/IMPLEMENT_LHASH_DOALL_[ARG_]_FN macros that provide types -without any "const" qualifiers. - -=head1 BUGS - -lh_<type>_insert() returns B<NULL> both for success and error. - -=head1 INTERNALS - -The following description is based on the SSLeay documentation: - -The B<lhash> library implements a hash table described in the -I<Communications of the ACM> in 1991. What makes this hash table -different is that as the table fills, the hash table is increased (or -decreased) in size via OPENSSL_realloc(). When a 'resize' is done, instead of -all hashes being redistributed over twice as many 'buckets', one -bucket is split. So when an 'expand' is done, there is only a minimal -cost to redistribute some values. Subsequent inserts will cause more -single 'bucket' redistributions but there will never be a sudden large -cost due to redistributing all the 'buckets'. - -The state for a particular hash table is kept in the B<LHASH> structure. -The decision to increase or decrease the hash table size is made -depending on the 'load' of the hash table. The load is the number of -items in the hash table divided by the size of the hash table. The -default values are as follows. If (hash->up_load E<lt> load) =E<gt> -expand. if (hash-E<gt>down_load E<gt> load) =E<gt> contract. The -B<up_load> has a default value of 1 and B<down_load> has a default value -of 2. These numbers can be modified by the application by just -playing with the B<up_load> and B<down_load> variables. The 'load' is -kept in a form which is multiplied by 256. So -hash-E<gt>up_load=8*256; will cause a load of 8 to be set. - -If you are interested in performance the field to watch is -num_comp_calls. The hash library keeps track of the 'hash' value for -each item so when a lookup is done, the 'hashes' are compared, if -there is a match, then a full compare is done, and -hash-E<gt>num_comp_calls is incremented. If num_comp_calls is not equal -to num_delete plus num_retrieve it means that your hash function is -generating hashes that are the same for different values. It is -probably worth changing your hash function if this is the case because -even if your hash table has 10 items in a 'bucket', it can be searched -with 10 B<unsigned long> compares and 10 linked list traverses. This -will be much less expensive that 10 calls to your compare function. - -lh_strhash() is a demo string hashing function: - - unsigned long lh_strhash(const char *c); - -Since the B<LHASH> routines would normally be passed structures, this -routine would not normally be passed to lh_<type>_new(), rather it would be -used in the function passed to lh_<type>_new(). - -=head1 SEE ALSO - -L<lh_stats(3)|lh_stats(3)> - -=head1 HISTORY - -The B<lhash> library is available in all versions of SSLeay and OpenSSL. -lh_error() was added in SSLeay 0.9.1b. - -This manpage is derived from the SSLeay documentation. - -In OpenSSL 0.9.7, all lhash functions that were passed function pointers -were changed for better type safety, and the function types LHASH_COMP_FN_TYPE, -LHASH_HASH_FN_TYPE, LHASH_DOALL_FN_TYPE and LHASH_DOALL_ARG_FN_TYPE -became available. - -In OpenSSL 1.0.0, the lhash interface was revamped for even better -type checking. - -=cut diff --git a/lib/libssl/src/doc/crypto/ui.pod b/lib/libssl/src/doc/crypto/ui.pod deleted file mode 100644 index 6df68d604a8..00000000000 --- a/lib/libssl/src/doc/crypto/ui.pod +++ /dev/null @@ -1,194 +0,0 @@ -=pod - -=head1 NAME - -UI_new, UI_new_method, UI_free, UI_add_input_string, UI_dup_input_string, -UI_add_verify_string, UI_dup_verify_string, UI_add_input_boolean, -UI_dup_input_boolean, UI_add_info_string, UI_dup_info_string, -UI_add_error_string, UI_dup_error_string, UI_construct_prompt, -UI_add_user_data, UI_get0_user_data, UI_get0_result, UI_process, -UI_ctrl, UI_set_default_method, UI_get_default_method, UI_get_method, -UI_set_method, UI_OpenSSL, ERR_load_UI_strings - New User Interface - -=head1 SYNOPSIS - - #include <openssl/ui.h> - - typedef struct ui_st UI; - typedef struct ui_method_st UI_METHOD; - - UI *UI_new(void); - UI *UI_new_method(const UI_METHOD *method); - void UI_free(UI *ui); - - int UI_add_input_string(UI *ui, const char *prompt, int flags, - char *result_buf, int minsize, int maxsize); - int UI_dup_input_string(UI *ui, const char *prompt, int flags, - char *result_buf, int minsize, int maxsize); - int UI_add_verify_string(UI *ui, const char *prompt, int flags, - char *result_buf, int minsize, int maxsize, const char *test_buf); - int UI_dup_verify_string(UI *ui, const char *prompt, int flags, - char *result_buf, int minsize, int maxsize, const char *test_buf); - int UI_add_input_boolean(UI *ui, const char *prompt, const char *action_desc, - const char *ok_chars, const char *cancel_chars, - int flags, char *result_buf); - int UI_dup_input_boolean(UI *ui, const char *prompt, const char *action_desc, - const char *ok_chars, const char *cancel_chars, - int flags, char *result_buf); - int UI_add_info_string(UI *ui, const char *text); - int UI_dup_info_string(UI *ui, const char *text); - int UI_add_error_string(UI *ui, const char *text); - int UI_dup_error_string(UI *ui, const char *text); - - /* These are the possible flags. They can be or'ed together. */ - #define UI_INPUT_FLAG_ECHO 0x01 - #define UI_INPUT_FLAG_DEFAULT_PWD 0x02 - - char *UI_construct_prompt(UI *ui_method, - const char *object_desc, const char *object_name); - - void *UI_add_user_data(UI *ui, void *user_data); - void *UI_get0_user_data(UI *ui); - - const char *UI_get0_result(UI *ui, int i); - - int UI_process(UI *ui); - - int UI_ctrl(UI *ui, int cmd, long i, void *p, void (*f)()); - #define UI_CTRL_PRINT_ERRORS 1 - #define UI_CTRL_IS_REDOABLE 2 - - void UI_set_default_method(const UI_METHOD *meth); - const UI_METHOD *UI_get_default_method(void); - const UI_METHOD *UI_get_method(UI *ui); - const UI_METHOD *UI_set_method(UI *ui, const UI_METHOD *meth); - - UI_METHOD *UI_OpenSSL(void); - -=head1 DESCRIPTION - -UI stands for User Interface, and is general purpose set of routines to -prompt the user for text-based information. Through user-written methods -(see L<ui_create(3)|ui_create(3)>), prompting can be done in any way -imaginable, be it plain text prompting, through dialog boxes or from a -cell phone. - -All the functions work through a context of the type UI. This context -contains all the information needed to prompt correctly as well as a -reference to a UI_METHOD, which is an ordered vector of functions that -carry out the actual prompting. - -The first thing to do is to create a UI with UI_new() or UI_new_method(), -then add information to it with the UI_add or UI_dup functions. Also, -user-defined random data can be passed down to the underlying method -through calls to UI_add_user_data. The default UI method doesn't care -about these data, but other methods might. Finally, use UI_process() -to actually perform the prompting and UI_get0_result() to find the result -to the prompt. - -A UI can contain more than one prompt, which are performed in the given -sequence. Each prompt gets an index number which is returned by the -UI_add and UI_dup functions, and has to be used to get the corresponding -result with UI_get0_result(). - -The functions are as follows: - -UI_new() creates a new UI using the default UI method. When done with -this UI, it should be freed using UI_free(). - -UI_new_method() creates a new UI using the given UI method. When done with -this UI, it should be freed using UI_free(). - -UI_OpenSSL() returns the built-in UI method (note: not the default one, -since the default can be changed. See further on). This method is the -most machine/OS dependent part of OpenSSL and normally generates the -most problems when porting. - -UI_free() removes a UI from memory, along with all other pieces of memory -that's connected to it, like duplicated input strings, results and others. - -UI_add_input_string() and UI_add_verify_string() add a prompt to the UI, -as well as flags and a result buffer and the desired minimum and maximum -sizes of the result. The given information is used to prompt for -information, for example a password, and to verify a password (i.e. having -the user enter it twice and check that the same string was entered twice). -UI_add_verify_string() takes and extra argument that should be a pointer -to the result buffer of the input string that it's supposed to verify, or -verification will fail. - -UI_add_input_boolean() adds a prompt to the UI that's supposed to be answered -in a boolean way, with a single character for yes and a different character -for no. A set of characters that can be used to cancel the prompt is given -as well. The prompt itself is really divided in two, one part being the -descriptive text (given through the I<prompt> argument) and one describing -the possible answers (given through the I<action_desc> argument). - -UI_add_info_string() and UI_add_error_string() add strings that are shown at -the same time as the prompt for extra information or to show an error string. -The difference between the two is only conceptual. With the builtin method, -there's no technical difference between them. Other methods may make a -difference between them, however. - -The flags currently supported are UI_INPUT_FLAG_ECHO, which is relevant for -UI_add_input_string() and will have the users response be echoed (when -prompting for a password, this flag should obviously not be used, and -UI_INPUT_FLAG_DEFAULT_PWD, which means that a default password of some -sort will be used (completely depending on the application and the UI -method). - -UI_dup_input_string(), UI_dup_verify_string(), UI_dup_input_boolean(), -UI_dup_info_string() and UI_dup_error_string() are basically the same -as their UI_add counterparts, except that they make their own copies -of all strings. - -UI_construct_prompt() is a helper function that can be used to create -a prompt from two pieces of information: an description and a name. -The default constructor (if there is none provided by the method used) -creates a string "Enter I<description> for I<name>:". With the -description "pass phrase" and the file name "foo.key", that becomes -"Enter pass phrase for foo.key:". Other methods may create whatever -string and may include encodings that will be processed by the other -method functions. - -UI_add_user_data() adds a piece of memory for the method to use at any -time. The builtin UI method doesn't care about this info. Note that several -calls to this function doesn't add data, it replaces the previous blob -with the one given as argument. - -UI_get0_user_data() retrieves the data that has last been given to the -UI with UI_add_user_data(). - -UI_get0_result() returns a pointer to the result buffer associated with -the information indexed by I<i>. - -UI_process() goes through the information given so far, does all the printing -and prompting and returns. - -UI_ctrl() adds extra control for the application author. For now, it -understands two commands: UI_CTRL_PRINT_ERRORS, which makes UI_process() -print the OpenSSL error stack as part of processing the UI, and -UI_CTRL_IS_REDOABLE, which returns a flag saying if the used UI can -be used again or not. - -UI_set_default_method() changes the default UI method to the one given. - -UI_get_default_method() returns a pointer to the current default UI method. - -UI_get_method() returns the UI method associated with a given UI. - -UI_set_method() changes the UI method associated with a given UI. - -=head1 SEE ALSO - -L<ui_create(3)|ui_create(3)>, L<ui_compat(3)|ui_compat(3)> - -=head1 HISTORY - -The UI section was first introduced in OpenSSL 0.9.7. - -=head1 AUTHOR - -Richard Levitte (richard@levitte.org) for the OpenSSL project -(http://www.openssl.org). - -=cut diff --git a/lib/libssl/src/doc/crypto/ui_compat.pod b/lib/libssl/src/doc/crypto/ui_compat.pod deleted file mode 100644 index 4ef5465539e..00000000000 --- a/lib/libssl/src/doc/crypto/ui_compat.pod +++ /dev/null @@ -1,57 +0,0 @@ -=pod - -=head1 NAME - -des_read_password, des_read_2passwords, des_read_pw_string, des_read_pw - -Compatibility user interface functions - -=head1 SYNOPSIS - - #include <openssl/des_old.h> - - int des_read_password(DES_cblock *key,const char *prompt,int verify); - int des_read_2passwords(DES_cblock *key1,DES_cblock *key2, - const char *prompt,int verify); - - int des_read_pw_string(char *buf,int length,const char *prompt,int verify); - int des_read_pw(char *buf,char *buff,int size,const char *prompt,int verify); - -=head1 DESCRIPTION - -The DES library contained a few routines to prompt for passwords. These -aren't necessarily dependent on DES, and have therefore become part of the -UI compatibility library. - -des_read_pw() writes the string specified by I<prompt> to standard output -turns echo off and reads an input string from the terminal. The string is -returned in I<buf>, which must have space for at least I<size> bytes. -If I<verify> is set, the user is asked for the password twice and unless -the two copies match, an error is returned. The second password is stored -in I<buff>, which must therefore also be at least I<size> bytes. A return -code of -1 indicates a system error, 1 failure due to use interaction, and -0 is success. All other functions described here use des_read_pw() to do -the work. - -des_read_pw_string() is a variant of des_read_pw() that provides a buffer -for you if I<verify> is set. - -des_read_password() calls des_read_pw() and converts the password to a -DES key by calling DES_string_to_key(); des_read_2password() operates in -the same way as des_read_password() except that it generates two keys -by using the DES_string_to_2key() function. - -=head1 NOTES - -des_read_pw_string() is available in the MIT Kerberos library as well, and -is also available under the name EVP_read_pw_string(). - -=head1 SEE ALSO - -L<ui(3)|ui(3)>, L<ui_create(3)|ui_create(3)> - -=head1 AUTHOR - -Richard Levitte (richard@levitte.org) for the OpenSSL project -(http://www.openssl.org). - -=cut |