From 71b431bd059aaefaa67b54a34adfaadc4014902c Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Sat, 5 Nov 2016 13:36:33 +0000 Subject: convert the remaining manual pages from pod to mdoc --- src/lib/libcrypto/man/Makefile | 41 +- src/lib/libcrypto/man/RC4.3 | 79 ++ src/lib/libcrypto/man/RIPEMD160.3 | 96 +++ src/lib/libcrypto/man/SHA1.3 | 102 +++ src/lib/libcrypto/man/bn.3 | 576 ++++++++++++++ src/lib/libcrypto/man/d2i_DHparams.3 | 30 + src/lib/libcrypto/man/d2i_DSAPublicKey.3 | 159 ++++ src/lib/libcrypto/man/d2i_ECPKParameters.3 | 188 +++++ src/lib/libcrypto/man/dh.3 | 148 ++++ src/lib/libcrypto/man/dsa.3 | 244 ++++++ src/lib/libcrypto/man/ec.3 | 710 +++++++++++++++++ src/lib/libcrypto/man/engine.3 | 1187 ++++++++++++++++++++++++++++ src/lib/libcrypto/man/lh_stats.3 | 83 ++ 13 files changed, 3615 insertions(+), 28 deletions(-) create mode 100644 src/lib/libcrypto/man/RC4.3 create mode 100644 src/lib/libcrypto/man/RIPEMD160.3 create mode 100644 src/lib/libcrypto/man/SHA1.3 create mode 100644 src/lib/libcrypto/man/bn.3 create mode 100644 src/lib/libcrypto/man/d2i_DHparams.3 create mode 100644 src/lib/libcrypto/man/d2i_DSAPublicKey.3 create mode 100644 src/lib/libcrypto/man/d2i_ECPKParameters.3 create mode 100644 src/lib/libcrypto/man/dh.3 create mode 100644 src/lib/libcrypto/man/dsa.3 create mode 100644 src/lib/libcrypto/man/ec.3 create mode 100644 src/lib/libcrypto/man/engine.3 create mode 100644 src/lib/libcrypto/man/lh_stats.3 (limited to 'src/lib/libcrypto/man') diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile index 7819029ff6..81840a0b29 100644 --- a/src/lib/libcrypto/man/Makefile +++ b/src/lib/libcrypto/man/Makefile @@ -1,9 +1,7 @@ -# $OpenBSD: Makefile,v 1.47 2016/11/04 18:07:23 beck Exp $ +# $OpenBSD: Makefile,v 1.48 2016/11/05 13:36:33 schwarze Exp $ .include # for NOMAN -POD2MAN=pod2man --official --release="OpenBSD ${OSREV}" --center=OpenSSL - .ifndef NOMAN MAN= \ ASN1_OBJECT_new.3 \ @@ -138,6 +136,8 @@ MAN= \ RAND_cleanup.3 \ RAND_load_file.3 \ RAND_set_rand_method.3 \ + RC4.3 \ + RIPEMD160.3 \ RSA_blinding_on.3 \ RSA_check_key.3 \ RSA_generate_key.3 \ @@ -151,6 +151,7 @@ MAN= \ RSA_sign.3 \ RSA_sign_ASN1_OCTET_STRING.3 \ RSA_size.3 \ + SHA1.3 \ SMIME_read_PKCS7.3 \ SMIME_write_PKCS7.3 \ UI_new.3 \ @@ -166,9 +167,13 @@ MAN= \ X509_VERIFY_PARAM_set_flags.3 \ X509_new.3 \ X509_verify_cert.3 \ + bn.3 \ bn_dump.3 \ crypto.3 \ d2i_ASN1_OBJECT.3 \ + d2i_DHparams.3 \ + d2i_DSAPublicKey.3 \ + d2i_ECPKParameters.3 \ d2i_PKCS8PrivateKey_bio.3 \ d2i_RSAPublicKey.3 \ d2i_X509.3 \ @@ -178,27 +183,16 @@ MAN= \ d2i_X509_REQ.3 \ d2i_X509_SIG.3 \ des_read_pw.3 \ - evp.3 \ - i2d_PKCS7_bio_stream.3 \ - lh_new.3 \ - rsa.3 \ - x509.3 - -GENMAN= \ - RC4.3 \ - RIPEMD160.3 \ - SHA1.3 \ - bn.3 \ - d2i_DHparams.3 \ - d2i_DSAPublicKey.3 \ - d2i_ECPKParameters.3 \ dh.3 \ dsa.3 \ ec.3 \ engine.3 \ + evp.3 \ + i2d_PKCS7_bio_stream.3 \ + lh_new.3 \ lh_stats.3 \ - -MAN+= ${GENMAN} + rsa.3 \ + x509.3 .include .else @@ -206,16 +200,7 @@ maninstall: .endif -.PATH: ${.CURDIR}/../doc -.SUFFIXES: .pod .1 .3 .7 -.for sect in 1 3 7 -.pod.${sect}: - @echo '${POD2MAN} --section=${sect} --name=${*:U} $< > $@' - @${POD2MAN} --section=${sect} --name=${*:U} $< > $@.tmp && mv $@.tmp $@ -.endfor - .include .include clean cleandir: - rm -f ${GENMAN} diff --git a/src/lib/libcrypto/man/RC4.3 b/src/lib/libcrypto/man/RC4.3 new file mode 100644 index 0000000000..2c631c36be --- /dev/null +++ b/src/lib/libcrypto/man/RC4.3 @@ -0,0 +1,79 @@ +.Dd $Mdocdate: November 5 2016 $ +.Dt RC4 3 +.Os +.Sh NAME +.Nm RC4_set_key , +.Nm RC4 +.Nd RC4 encryption +.Sh SYNOPSIS +.In openssl/rc4.h +.Ft void +.Fo RC4_set_key +.Fa "RC4_KEY *key" +.Fa "int len" +.Fa "const unsigned char *data" +.Fc +.Ft void +.Fo RC4 +.Fa "RC4_KEY *key" +.Fa "unsigned long len" +.Fa "const unsigned char *indata" +.Fa "unsigned char *outdata" +.Fc +.Sh DESCRIPTION +This library implements the alleged RC4 cipher, which is described for +example in +.%B Applied Cryptography . +It is believed to be compatible with RC4[TM], a proprietary cipher of +RSA Security Inc. +.Pp +RC4 is a stream cipher with variable key length. +Typically, 128 bit (16 byte) keys are used for strong encryption, but +shorter insecure key sizes have been widely used due to export +restrictions. +.Pp +RC4 consists of a key setup phase and the actual encryption or +decryption phase. +.Pp +.Fn RC4_set_key +sets up the +.Vt RC4_KEY +.Fa key +using the +.Fa len +bytes long key at +.Fa data . +.Pp +.Fn RC4 +encrypts or decrypts the +.Fa len +bytes of data at +.Fa indata +using +.Fa key +and places the result at +.Fa outdata . +Repeated +.Fn RC4 +calls with the same +.Fa key +yield a continuous key stream. +.Pp +Since RC4 is a stream cipher (the input is XOR'ed with a pseudo-random +key stream to produce the output), decryption uses the same function +calls as encryption. +.Sh RETURN VALUES +.Fn RC4_set_key +and +.Fn RC4 +do not return values. +.Sh SEE ALSO +.Xr blowfish 3 , +.Xr EVP_EncryptInit 3 +.Sh HISTORY +.Fn RC4_set_key +and +.Fn RC4 +are available in all versions of SSLeay and OpenSSL. +.Sh BUGS +This cipher is broken and should no longer be used. diff --git a/src/lib/libcrypto/man/RIPEMD160.3 b/src/lib/libcrypto/man/RIPEMD160.3 new file mode 100644 index 0000000000..57cff8a9e4 --- /dev/null +++ b/src/lib/libcrypto/man/RIPEMD160.3 @@ -0,0 +1,96 @@ +.Dd $Mdocdate: November 5 2016 $ +.Dt RIPEMD160 3 +.Os +.Sh NAME +.Nm RIPEMD160 , +.Nm RIPEMD160_Init , +.Nm RIPEMD160_Update , +.Nm RIPEMD160_Final +.Nd RIPEMD-160 hash function +.Sh SYNOPSIS +.In openssl/ripemd.h +.Ft unsigned char * +.Fo RIPEMD160 +.Fa "const unsigned char *d" +.Fa "unsigned long n" +.Fa "unsigned char *md" +.Fc +.Ft int +.Fo RIPEMD160_Init +.Fa "RIPEMD160_CTX *c" +.Fc +.Ft int +.Fo RIPEMD160_Update +.Fa "RIPEMD_CTX *c" +.Fa "const void *data" +.Fa "unsigned long len" +.Fc +.Ft int +.Fo RIPEMD160_Final +.Fa "unsigned char *md" +.Fa "RIPEMD160_CTX *c" +.Fc +.Sh DESCRIPTION +RIPEMD-160 is a cryptographic hash function with a 160 bit output. +.Pp +.Fn RIPEMD160 +computes the RIPEMD-160 message digest of the +.Fa n +bytes at +.Fa d +and places it in +.Fa md , +which must have space for +.Dv RIPEMD160_DIGEST_LENGTH +== 20 bytes of output. +If +.Fa md +is +.Dv NULL , +the digest is placed in a static array. +.Pp +The following functions may be used if the message is not completely +stored in memory: +.Pp +.Fn RIPEMD160_Init +initializes a +.Vt RIPEMD160_CTX +structure. +.Pp +.Fn RIPEMD160_Update +can be called repeatedly with chunks of the message to be hashed +.Pq Fa len No bytes at Fa data . +.Pp +.Fn RIPEMD160_Final +places the message digest in +.Fa md , +which must have space for +.Dv RIPEMD160_DIGEST_LENGTH +== 20 bytes of output, +and erases the +.Vt RIPEMD160_CTX . +.Pp +Applications should use the higher level functions +.Xr EVP_DigestInit 3 +etc. instead of calling the hash functions directly. +.Sh RETURN VALUES +.Fn RIPEMD160 +returns a pointer to the hash value. +.Pp +.Fn RIPEMD160_Init , +.Fn RIPEMD160_Update , +and +.Fn RIPEMD160_Final +return 1 for success or 0 otherwise. +.Sh SEE ALSO +.Xr EVP_DigestInit 3 , +.Xr HMAC 3 +.Sh STANDARDS +ISO/IEC 10118-3 (draft) (??) +.Sh HISTORY +.Fn RIPEMD160 , +.Fn RIPEMD160_Init , +.Fn RIPEMD160_Update , +and +.Fn RIPEMD160_Final +are available since SSLeay 0.9.0. diff --git a/src/lib/libcrypto/man/SHA1.3 b/src/lib/libcrypto/man/SHA1.3 new file mode 100644 index 0000000000..c873a8cbb7 --- /dev/null +++ b/src/lib/libcrypto/man/SHA1.3 @@ -0,0 +1,102 @@ +.Dd $Mdocdate: November 5 2016 $ +.Dt SHA1 3 +.Os +.Sh NAME +.Nm SHA1 , +.Nm SHA1_Init , +.Nm SHA1_Update , +.Nm SHA1_Final +.Nd Secure Hash Algorithm +.Sh SYNOPSIS +.In openssl/sha.h +.Ft unsigned char * +.Fo SHA1 +.Fa "const unsigned char *d" +.Fa "unsigned long n" +.Fa "unsigned char *md" +.Fc +.Ft int +.Fo SHA1_Init +.Fa "SHA_CTX *c" +.Fc +.Ft int +.Fo SHA1_Update +.Fa "SHA_CTX *c" +.Fa "const void *data" +.Fa "unsigned long len" +.Fc +.Ft int +.Fo SHA1_Final +.Fa "unsigned char *md" +.Fa "SHA_CTX *c" +.Fc +.Sh DESCRIPTION +SHA-1 (Secure Hash Algorithm) is a cryptographic hash function with a +160 bit output. +.Pp +.Fn SHA1 +computes the SHA-1 message digest of the +.Fa n +bytes at +.Fa d +and places it in +.Fa md , +which must have space for +.Dv SHA_DIGEST_LENGTH +== 20 bytes of output. +If +.Fa md +is +.Dv NULL , +the digest is placed in a static array. +.Pp +The following functions may be used if the message is not completely +stored in memory: +.Pp +.Fn SHA1_Init +initializes a +.Vt SHA_CTX +structure. +.Pp +.Fn SHA1_Update +can be called repeatedly with chunks of the message to be hashed +.Pq Fa len No bytes at Fa data . +.Pp +.Fn SHA1_Final +places the message digest in +.Fa md , +which must have space for +.Dv SHA_DIGEST_LENGTH +== 20 bytes of output, and erases the +.Vt SHA_CTX . +.Pp +Applications should use the higher level functions +.Xr EVP_DigestInit 3 +etc. instead of calling the hash functions directly. +.Pp +The predecessor of SHA-1, SHA, is also implemented, but it should be +used only when backward compatibility is required. +.Sh RETURN VALUES +.Fn SHA1 +returns a pointer to the hash value. +.Pp +.Fn SHA1_Init , +.Fn SHA1_Update , +and +.Fn SHA1_Final +return 1 for success or 0 otherwise. +.Sh SEE ALSO +.Xr EVP_DigestInit 3 , +.Xr HMAC 3 , +.Xr RIPEMD160 3 +.Sh STANDARDS +SHA: US Federal Information Processing Standard FIPS PUB 180 (Secure +Hash Standard), SHA-1: US Federal Information Processing Standard FIPS +PUB 180-1 (Secure Hash Standard), ANSI X9.30 +.Sh HISTORY +.Fn SHA1 , +.Fn SHA1_Init , +.Fn SHA1_Update , +and +.Fn SHA1_Final +are available in all versions of SSLeay and OpenSSL. diff --git a/src/lib/libcrypto/man/bn.3 b/src/lib/libcrypto/man/bn.3 new file mode 100644 index 0000000000..6406be1663 --- /dev/null +++ b/src/lib/libcrypto/man/bn.3 @@ -0,0 +1,576 @@ +.Dd $Mdocdate: November 5 2016 $ +.Dt BN 3 +.Os +.Sh NAME +.Nm bn +.Nd multiprecision integer arithmetics +.Sh SYNOPSIS +.In openssl/bn.h +.Ft BIGNUM * +.Fn BN_new void +.Ft void +.Fo BN_free +.Fa "BIGNUM *a" +.Fc +.Ft void +.Fo BN_init +.Fa "BIGNUM *" +.Fc +.Ft void +.Fo BN_clear +.Fa "BIGNUM *a" +.Fc +.Ft void +.Fo BN_clear_free +.Fa "BIGNUM *a" +.Fc +.Ft BN_CTX * +.Fn BN_CTX_new void +.Ft void +.Fo BN_CTX_init +.Fa "BN_CTX *c" +.Fc +.Ft void +.Fo BN_CTX_free +.Fa "BN_CTX *c" +.Fc +.Ft BIGNUM * +.Fo BN_copy +.Fa "BIGNUM *a" +.Fa "const BIGNUM *b" +.Fc +.Ft BIGNUM * +.Fo BN_dup +.Fa "const BIGNUM *a" +.Fc +.Ft BIGNUM * +.Fo BN_swap +.Fa "BIGNUM *a" +.Fa "BIGNUM *b" +.Fc +.Ft int +.Fo BN_num_bytes +.Fa "const BIGNUM *a" +.Fc +.Ft int +.Fo BN_num_bits +.Fa "const BIGNUM *a" +.Fc +.Ft int +.Fo BN_num_bits_word +.Fa "BN_ULONG w" +.Fc +.Ft void +.Fo BN_set_negative +.Fa "BIGNUM *a" +.Fa "int n" +.Fc +.Ft int +.Fo BN_is_negative +.Fa "const BIGNUM *a" +.Fc +.Ft int +.Fo BN_add +.Fa "BIGNUM *r" +.Fa "const BIGNUM *a" +.Fa "const BIGNUM *b" +.Fc +.Ft int +.Fo BN_sub +.Fa "BIGNUM *r" +.Fa "const BIGNUM *a" +.Fa "const BIGNUM *b" +.Fc +.Ft int +.Fo BN_mul +.Fa "BIGNUM *r" +.Fa "BIGNUM *a" +.Fa "BIGNUM *b" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo BN_sqr +.Fa "BIGNUM *r" +.Fa "BIGNUM *a" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo BN_div +.Fa "BIGNUM *dv" +.Fa "BIGNUM *rem" +.Fa "const BIGNUM *a" +.Fa "const BIGNUM *d" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo BN_mod +.Fa "BIGNUM *rem" +.Fa "const BIGNUM *a" +.Fa "const BIGNUM *m" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo BN_nnmod +.Fa "BIGNUM *rem" +.Fa "const BIGNUM *a" +.Fa "const BIGNUM *m" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo BN_mod_add +.Fa "BIGNUM *ret" +.Fa "BIGNUM *a" +.Fa "BIGNUM *b" +.Fa "const BIGNUM *m" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo BN_mod_sub +.Fa "BIGNUM *ret" +.Fa "BIGNUM *a" +.Fa "BIGNUM *b" +.Fa "const BIGNUM *m" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo BN_mod_mul +.Fa "BIGNUM *ret" +.Fa "BIGNUM *a" +.Fa "BIGNUM *b" +.Fa "const BIGNUM *m" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo BN_mod_sqr +.Fa "BIGNUM *ret" +.Fa "BIGNUM *a" +.Fa "const BIGNUM *m" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo BN_exp +.Fa "BIGNUM *r" +.Fa "BIGNUM *a" +.Fa "BIGNUM *p" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo BN_mod_exp +.Fa "BIGNUM *r" +.Fa "BIGNUM *a" +.Fa "const BIGNUM *p" +.Fa "const BIGNUM *m" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo BN_gcd +.Fa "BIGNUM *r" +.Fa "BIGNUM *a" +.Fa "BIGNUM *b" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo BN_add_word +.Fa "BIGNUM *a" +.Fa "BN_ULONG w" +.Fc +.Ft int +.Fo BN_sub_word +.Fa "BIGNUM *a" +.Fa "BN_ULONG w" +.Fc +.Ft int +.Fo BN_mul_word +.Fa "BIGNUM *a" +.Fa "BN_ULONG w" +.Fc +.Ft BN_ULONG +.Fo BN_div_word +.Fa "BIGNUM *a" +.Fa "BN_ULONG w" +.Fc +.Ft BN_ULONG +.Fo BN_mod_word +.Fa "const BIGNUM *a" +.Fa "BN_ULONG w" +.Fc +.Ft int +.Fo BN_cmp +.Fa "BIGNUM *a" +.Fa "BIGNUM *b" +.Fc +.Ft int +.Fo BN_ucmp +.Fa "BIGNUM *a" +.Fa "BIGNUM *b" +.Fc +.Ft int +.Fo BN_is_zero +.Fa "BIGNUM *a" +.Fc +.Ft int +.Fo BN_is_one +.Fa "BIGNUM *a" +.Fc +.Ft int +.Fo BN_is_word +.Fa "BIGNUM *a" +.Fa "BN_ULONG w" +.Fc +.Ft int +.Fo BN_is_odd +.Fa "BIGNUM *a" +.Fc +.Ft int +.Fo BN_zero +.Fa "BIGNUM *a" +.Fc +.Ft int +.Fo BN_one +.Fa "BIGNUM *a" +.Fc +.Ft const BIGNUM * +.Fn BN_value_one void +.Ft int +.Fo BN_set_word +.Fa "BIGNUM *a" +.Fa "unsigned long w" +.Fc +.Ft unsigned long +.Fo BN_get_word +.Fa "BIGNUM *a" +.Fc +.Ft int +.Fo BN_rand +.Fa "BIGNUM *rnd" +.Fa "int bits" +.Fa "int top" +.Fa "int bottom" +.Fc +.Ft int +.Fo BN_pseudo_rand +.Fa "BIGNUM *rnd" +.Fa "int bits" +.Fa "int top" +.Fa "int bottom" +.Fc +.Ft int +.Fo BN_rand_range +.Fa "BIGNUM *rnd" +.Fa "BIGNUM *range" +.Fc +.Ft int +.Fo BN_pseudo_rand_range +.Fa "BIGNUM *rnd" +.Fa "BIGNUM *range" +.Fc +.Ft BIGNUM * +.Fo BN_generate_prime +.Fa "BIGNUM *ret" +.Fa "int bits" +.Fa "int safe" +.Fa "BIGNUM *add" +.Fa "BIGNUM *rem" +.Fa "void (*callback)(int, int, void *)" +.Fa "void *cb_arg" +.Fc +.Ft int +.Fo BN_is_prime +.Fa "const BIGNUM *p" +.Fa "int nchecks" +.Fa "void (*callback)(int, int, void *)" +.Fa "BN_CTX *ctx" +.Fa "void *cb_arg" +.Fc +.Ft int +.Fo BN_set_bit +.Fa "BIGNUM *a" +.Fa "int n" +.Fc +.Ft int +.Fo BN_clear_bit +.Fa "BIGNUM *a" +.Fa "int n" +.Fc +.Ft int +.Fo BN_is_bit_set +.Fa "const BIGNUM *a" +.Fa "int n" +.Fc +.Ft int +.Fo BN_mask_bits +.Fa "BIGNUM *a" +.Fa "int n" +.Fc +.Ft int +.Fo BN_lshift +.Fa "BIGNUM *r" +.Fa "const BIGNUM *a" +.Fa "int n" +.Fc +.Ft int +.Fo BN_lshift1 +.Fa "BIGNUM *r" +.Fa "BIGNUM *a" +.Fc +.Ft int +.Fo BN_rshift +.Fa "BIGNUM *r" +.Fa "BIGNUM *a" +.Fa "int n" +.Fc +.Ft int +.Fo BN_rshift1 +.Fa "BIGNUM *r" +.Fa "BIGNUM *a" +.Fc +.Ft int +.Fo BN_bn2bin +.Fa "const BIGNUM *a" +.Fa "unsigned char *to" +.Fc +.Ft BIGNUM * +.Fo BN_bin2bn +.Fa "const unsigned char *s" +.Fa "int len" +.Fa "BIGNUM *ret" +.Fc +.Ft char * +.Fo BN_bn2hex +.Fa "const BIGNUM *a" +.Fc +.Ft char * +.Fo BN_bn2dec +.Fa "const BIGNUM *a" +.Fc +.Ft int +.Fo BN_hex2bn +.Fa "BIGNUM **a" +.Fa "const char *str" +.Fc +.Ft int +.Fo BN_dec2bn +.Fa "BIGNUM **a" +.Fa "const char *str" +.Fc +.Ft int +.Fo BN_print +.Fa "BIO *fp" +.Fa "const BIGNUM *a" +.Fc +.Ft int +.Fo BN_print_fp +.Fa "FILE *fp" +.Fa "const BIGNUM *a" +.Fc +.Ft int +.Fo BN_bn2mpi +.Fa "const BIGNUM *a" +.Fa "unsigned char *to" +.Fc +.Ft BIGNUM * +.Fo BN_mpi2bn +.Fa "unsigned char *s" +.Fa "int len" +.Fa "BIGNUM *ret" +.Fc +.Ft BIGNUM * +.Fo BN_mod_inverse +.Fa "BIGNUM *r" +.Fa "BIGNUM *a" +.Fa "const BIGNUM *n" +.Fa "BN_CTX *ctx" +.Fc +.Ft BN_RECP_CTX * +.Fn BN_RECP_CTX_new void +.Ft void +.Fo BN_RECP_CTX_init +.Fa "BN_RECP_CTX *recp" +.Fc +.Ft void +.Fo BN_RECP_CTX_free +.Fa "BN_RECP_CTX *recp" +.Fc +.Ft int +.Fo BN_RECP_CTX_set +.Fa "BN_RECP_CTX *recp" +.Fa "const BIGNUM *m" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo BN_mod_mul_reciprocal +.Fa "BIGNUM *r" +.Fa "BIGNUM *a" +.Fa "BIGNUM *b" +.Fa "BN_RECP_CTX *recp" +.Fa "BN_CTX *ctx" +.Fc +.Ft BN_MONT_CTX * +.Fn BN_MONT_CTX_new void +.Ft void +.Fo BN_MONT_CTX_init +.Fa "BN_MONT_CTX *ctx" +.Fc +.Ft void +.Fo BN_MONT_CTX_free +.Fa "BN_MONT_CTX *mont" +.Fc +.Ft int +.Fo BN_MONT_CTX_set +.Fa "BN_MONT_CTX *mont" +.Fa "const BIGNUM *m" +.Fa "BN_CTX *ctx" +.Fc +.Ft BN_MONT_CTX * +.Fo BN_MONT_CTX_copy +.Fa "BN_MONT_CTX *to" +.Fa "BN_MONT_CTX *from" +.Fc +.Ft int +.Fo BN_mod_mul_montgomery +.Fa "BIGNUM *r" +.Fa "BIGNUM *a" +.Fa "BIGNUM *b" +.Fa "BN_MONT_CTX *mont" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo BN_from_montgomery +.Fa "BIGNUM *r" +.Fa "BIGNUM *a" +.Fa "BN_MONT_CTX *mont" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo BN_to_montgomery +.Fa "BIGNUM *r" +.Fa "BIGNUM *a" +.Fa "BN_MONT_CTX *mont" +.Fa "BN_CTX *ctx" +.Fc +.Ft BN_BLINDING * +.Fo BN_BLINDING_new +.Fa "const BIGNUM *A" +.Fa "const BIGNUM *Ai" +.Fa "BIGNUM *mod" +.Fc +.Ft void +.Fo BN_BLINDING_free +.Fa "BN_BLINDING *b" +.Fc +.Ft int +.Fo BN_BLINDING_update +.Fa "BN_BLINDING *b" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo BN_BLINDING_convert +.Fa "BIGNUM *n" +.Fa "BN_BLINDING *b" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo BN_BLINDING_invert +.Fa "BIGNUM *n" +.Fa "BN_BLINDING *b" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo BN_BLINDING_convert_ex +.Fa "BIGNUM *n" +.Fa "BIGNUM *r" +.Fa "BN_BLINDING *b" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo BN_BLINDING_invert_ex +.Fa "BIGNUM *n" +.Fa "const BIGNUM *r" +.Fa "BN_BLINDING *b" +.Fa "BN_CTX *ctx" +.Fc +.Ft unsigned long +.Fo BN_BLINDING_get_thread_id +.Fa "const BN_BLINDING *" +.Fc +.Ft void +.Fo BN_BLINDING_set_thread_id +.Fa "BN_BLINDING *" +.Fa "unsigned long" +.Fc +.Ft unsigned long +.Fo BN_BLINDING_get_flags +.Fa "const BN_BLINDING *" +.Fc +.Ft void +.Fo BN_BLINDING_set_flags +.Fa "BN_BLINDING *" +.Fa "unsigned long" +.Fc +.Ft BN_BLINDING * +.Fo BN_BLINDING_create_param +.Fa "BN_BLINDING *b" +.Fa "const BIGNUM *e" +.Fa "BIGNUM *m" +.Fa "BN_CTX *ctx" +.Fa "int (*bn_mod_exp)(BIGNUM *r, const BIGNUM *a, const BIGNUM *p, const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx)" +.Fa "BN_MONT_CTX *m_ctx" +.Fc +.Sh DESCRIPTION +This library performs arithmetic operations on integers of arbitrary size. +It was written for use in public key cryptography, such as RSA and +Diffie-Hellman. +.Pp +It uses dynamic memory allocation for storing its data structures. +That means that there is no limit on the size of the numbers manipulated +by these functions, but return values must always be checked in case a +memory allocation error has occurred. +.Pp +The basic object in this library is a +.Vt BIGNUM . +It is used to hold a single large integer. +This type should be considered opaque and fields should not be modified +or accessed directly. +.Pp +The creation of +.Vt BIGNUM +objects is described in +.Xr BN_new 3 ; +.Xr BN_add 3 +describes most of the arithmetic operations. +Comparison is described in +.Xr BN_cmp 3 ; +.Xr BN_zero 3 +describes certain assignments, +.Xr BN_rand 3 +the generation of random numbers, +.Xr BN_generate_prime 3 +deals with prime numbers and +.Xr BN_set_bit 3 +with bit operations. +The conversion of +.Vt BIGNUM Ns s +to external formats is described in +.Xr BN_bn2bin 3 . +.Sh SEE ALSO +.Xr BN_add 3 , +.Xr BN_add_word 3 , +.Xr BN_BLINDING_new 3 , +.Xr BN_bn2bin 3 , +.Xr BN_cmp 3 , +.Xr BN_copy 3 , +.Xr BN_CTX_new 3 , +.Xr bn_dump 3 , +.Xr BN_generate_prime 3 , +.Xr BN_mod_inverse 3 , +.Xr BN_mod_mul_montgomery 3 , +.Xr BN_mod_mul_reciprocal 3 , +.Xr BN_new 3 , +.Xr BN_num_bytes 3 , +.Xr BN_rand 3 , +.Xr BN_set_bit 3 , +.Xr BN_swap 3 , +.Xr BN_zero 3 , +.Xr dh 3 , +.Xr ERR 3 , +.Xr rsa 3 diff --git a/src/lib/libcrypto/man/d2i_DHparams.3 b/src/lib/libcrypto/man/d2i_DHparams.3 new file mode 100644 index 0000000000..73aec0269b --- /dev/null +++ b/src/lib/libcrypto/man/d2i_DHparams.3 @@ -0,0 +1,30 @@ +.Dd $Mdocdate: November 5 2016 $ +.Dt D2I_DHPARAMS 3 +.Os +.Sh NAME +.Nm d2i_DHparams , +.Nm i2d_DHparams +.Nd PKCS#3 DH parameter functions +.Sh SYNOPSIS +.In openssl/dh.h +.Ft DH * +.Fo d2i_DHparams +.Fa "DH **a" +.Fa "unsigned char **pp" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_DHparams +.Fa "DH *a" +.Fa "unsigned char **pp" +.Fc +.Sh DESCRIPTION +These functions decode and encode PKCS#3 DH parameters using the +DHparameter structure described in PKCS#3. +.Pp +Otherwise these behave in a way similar to +.Xr d2i_X509 3 +and +.Xr i2d_X509 3 . +.Sh SEE ALSO +.Xr d2i_X509 3 diff --git a/src/lib/libcrypto/man/d2i_DSAPublicKey.3 b/src/lib/libcrypto/man/d2i_DSAPublicKey.3 new file mode 100644 index 0000000000..aff5d0f814 --- /dev/null +++ b/src/lib/libcrypto/man/d2i_DSAPublicKey.3 @@ -0,0 +1,159 @@ +.Dd $Mdocdate: November 5 2016 $ +.Dt D2I_DSAPUBLICKEY 3 +.Os +.Sh NAME +.Nm d2i_DSAPublicKey , +.Nm i2d_DSAPublicKey , +.Nm d2i_DSAPrivateKey , +.Nm i2d_DSAPrivateKey , +.Nm d2i_DSA_PUBKEY , +.Nm i2d_DSA_PUBKEY , +.Nm d2i_DSAparams , +.Nm i2d_DSAparams , +.Nm d2i_DSA_SIG , +.Nm i2d_DSA_SIG +.Nd DSA key encoding and parsing functions +.Sh SYNOPSIS +.In openssl/dsa.h +.In openssl/x509.h +.Ft DSA * +.Fo d2i_DSAPublicKey +.Fa "DSA **a" +.Fa "const unsigned char **pp" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_DSAPublicKey +.Fa "const DSA *a" +.Fa "unsigned char **pp" +.Fc +.Ft DSA * +.Fo d2i_DSA_PUBKEY +.Fa "DSA **a" +.Fa "const unsigned char **pp" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_DSA_PUBKEY +.Fa "const DSA *a" +.Fa "unsigned char **pp" +.Fc +.Ft DSA * +.Fo d2i_DSAPrivateKey +.Fa "DSA **a" +.Fa "const unsigned char **pp" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_DSAPrivateKey +.Fa "const DSA *a" +.Fa "unsigned char **pp" +.Fc +.Ft DSA * +.Fo d2i_DSAparams +.Fa "DSA **a" +.Fa "const unsigned char **pp" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_DSAparams +.Fa "const DSA *a" +.Fa "unsigned char **pp" +.Fc +.Ft DSA * +.Fo d2i_DSA_SIG +.Fa "DSA_SIG **a" +.Fa "const unsigned char **pp" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_DSA_SIG +.Fa "const DSA_SIG *a" +.Fa "unsigned char **pp" +.Fc +.Sh DESCRIPTION +.Fn d2i_DSAPublicKey +and +.Fn i2d_DSAPublicKey +decode and encode the DSA public key components structure. +.Pp +.Fn d2i_DSA_PUBKEY +and +.Fn i2d_DSA_PUBKEY +decode and encode a DSA public key using a SubjectPublicKeyInfo +(certificate public key) structure. +.Pp +.Fn d2i_DSAPrivateKey +and +.Fn i2d_DSAPrivateKey +decode and encode the DSA private key components. +.Pp +.Fn d2i_DSAparams +and +.Fn i2d_DSAparams +decode and encode the DSA parameters using a +.Sy Dss-Parms +structure as defined in RFC2459. +.Pp +.Fn d2i_DSA_SIG +and +.Fn i2d_DSA_SIG +decode and encode a DSA signature using a +.Sy Dss-Sig-Value +structure as defined in RFC2459. +.Pp +The usage of all of these functions is similar to +.Xr d2i_X509 3 +and +.Xr i2d_X509 3 . +.Pp +The +.Vt DSA +structure passed to the private key encoding functions should have all +the private key components present. +.Pp +The data encoded by the private key functions is unencrypted and +therefore offers no private key security. +.Pp +The +.Fn *_DSA_PUBKEY +functions should be used in preference to the +.Fn *_DSAPublicKey +functions when encoding public keys because they use a standard format. +.Pp +The +.Fn *_DSAPublicKey +functions use an non-standard format. +The actual data encoded depends on the value of +.Fa a->write_params . +If +.Fa a->write_params +is zero, then only the +.Fa a->pub_key +field is encoded as an +.Sy INTEGER . +If +.Fa a->write_params +is 1, then a +.Sy SEQUENCE +consisting of the +.Fa a->p , +.Fa a->q , +.Fa a->g , +and +.Fa a->pub_key +fields is encoded. +.Pp +The +.Fn *_DSAPrivateKey +functions also use a non-standard structure consisting consisting of a +SEQUENCE containing the +.Fa a->p , +.Fa a->q , +.Fa a->g , +.Fa a->pub_key , +and +.Fa a->priv_key +fields. +.Sh SEE ALSO +.Xr d2i_X509 3 diff --git a/src/lib/libcrypto/man/d2i_ECPKParameters.3 b/src/lib/libcrypto/man/d2i_ECPKParameters.3 new file mode 100644 index 0000000000..71d84b95c9 --- /dev/null +++ b/src/lib/libcrypto/man/d2i_ECPKParameters.3 @@ -0,0 +1,188 @@ +.Dd $Mdocdate: November 5 2016 $ +.Dt D2I_ECPKPARAMETERS 3 +.Os +.Sh NAME +.Nm d2i_ECPKParameters , +.Nm i2d_ECPKParameters , +.Nm d2i_ECPKParameters_bio , +.Nm i2d_ECPKParameters_bio , +.Nm d2i_ECPKParameters_fp , +.Nm i2d_ECPKParameters_fp , +.Nm ECPKParameters_print , +.Nm ECPKParameters_print_fp +.Nd decode and encode ASN.1 representations of elliptic curve entities +.Sh SYNOPSIS +.In openssl/ec.h +.Ft EC_GROUP * +.Fo d2i_ECPKParameters +.Fa "EC_GROUP **px" +.Fa "const unsigned char **in" +.Fa "long len" +.Fc +.Ft int +.Fo i2d_ECPKParameters +.Fa "const EC_GROUP *x" +.Fa "unsigned char **out" +.Fc +.Fd #define d2i_ECPKParameters_bio(bp,x)\ + ASN1_d2i_bio_of(EC_GROUP,NULL,d2i_ECPKParameters,bp,x) +.Fd #define i2d_ECPKParameters_bio(bp,x)\ + ASN1_i2d_bio_of_const(EC_GROUP,i2d_ECPKParameters,bp,x) +.Fd #define d2i_ECPKParameters_fp(fp,x) (EC_GROUP *)ASN1_d2i_fp(NULL,\ + (char *(*)())d2i_ECPKParameters,(fp),(unsigned char **)(x)) +.Fd #define i2d_ECPKParameters_fp(fp,x)\ + ASN1_i2d_fp(i2d_ECPKParameters,(fp), (unsigned char *)(x)) +.Ft int +.Fo ECPKParameters_print +.Fa "BIO *bp" +.Fa "const EC_GROUP *x" +.Fa "int off" +.Fc +.Ft int +.Fo ECPKParameters_print_fp +.Fa "FILE *fp" +.Fa "const EC_GROUP *x" +.Fa "int off" +.Fc +.Sh DESCRIPTION +The ECPKParameters encode and decode routines encode and parse the +public parameters for an +.Vt EC_GROUP +structure, which represents a curve. +.Pp +.Fn d2i_ECPKParameters +attempts to decode +.Fa len +bytes at +.Pf * Fa in . +If successful, a pointer to the +.Vt EC_GROUP +structure is returned. +If an error occurred, then +.Dv NULL +is returned. +If +.Fa px +is not +.Dv NULL , +then the returned structure is written to +.Pf * Fa px . +If +.Pf * Fa px +is not +.Dv NULL , +then it is assumed that +.Pf * Fa px +contains a valid +.Vt EC_GROUP +structure and an attempt is made to reuse it. +If the call is successful, +.Pf * Fa in +is incremented to the byte following the parsed data. +.Pp +.Fn i2d_ECPKParameters +encodes the structure pointed to by +.Fa x +into DER format. +If +.Fa out +is not +.Dv NULL , +is writes the DER encoded data to the buffer at +.Pf * Fa out +and increments it to point after the data just written. +If the return value is negative, an error occurred, otherwise it returns +the length of the encoded data. +.Pp +If +.Pf * Fa out +is +.Dv NULL , +memory will be allocated for a buffer and the encoded data written to it. +In this case +.Pf * Fa out +is not incremented, and it points to the start of the data just written. +.Pp +.Fn d2i_ECPKParameters_bio +is similar to +.Fn d2i_ECPKParameters +except it attempts to parse data from +.Vt BIO +.Fa bp . +.Pp +.Fn d2i_ECPKParameters_fp +is similar to +.Fn d2i_ECPKParameters +except it attempts to parse data from the +.Vt FILE +pointer +.Fa fp . +.Pp +.Fn i2d_ECPKParameters_bio +is similar to +.Fn i2d_ECPKParameters +except it writes the encoding of the structure +.Fa x +to +.Vt BIO +.Fa bp +and it returns 1 for success or 0 for failure. +.Pp +.Fn i2d_ECPKParameters_fp +is similar to +.Fn i2d_ECPKParameters +except it writes the encoding of the structure +.Fa x +to +.Vt BIO +.Sy bp +and it returns 1 for success or 0 for failure. +.Pp +These functions are very similar to the X.509 functions described in +.Xr d2i_X509 3 , +where further notes and examples are available. +.Pp +The +.Fn ECPKParameters_print +and +.Fn ECPKParameters_print_fp +functions print human-readable output of the public parameters of the +.Vt EC_GROUP +to +.Fa bp +or +.Fa fp . +The output lines are indented by +.Fa off +spaces. +.Sh RETURN VALUES +.Fn d2i_ECPKParameters , +.Fn d2i_ECPKParameters_bio , +and +.Fn d2i_ECPKParameters_fp +return a valid +.Vt EC_GROUP +structure or +.Dv NULL +if an error occurs. +.Pp +.Fn i2d_ECPKParameters +returns the number of bytes successfully encoded or a negative value if +an error occurs. +.Pp +.Fn i2d_ECPKParameters_bio , +.Fn i2d_ECPKParameters_fp , +.Fn ECPKParameters_print , +and +.Fn ECPKParameters_print_fp +return 1 for success or 0 if an error occurs. +.Sh SEE ALSO +.Xr crypto 3 , +.Xr d2i_X509 3 , +.Xr ec 3 , +.Xr EC_GFp_simple_method 3 , +.Xr EC_GROUP_copy 3 , +.Xr EC_GROUP_new 3 , +.Xr EC_KEY_new 3 , +.Xr EC_POINT_add 3 , +.Xr EC_POINT_new 3 diff --git a/src/lib/libcrypto/man/dh.3 b/src/lib/libcrypto/man/dh.3 new file mode 100644 index 0000000000..2a8f172e2b --- /dev/null +++ b/src/lib/libcrypto/man/dh.3 @@ -0,0 +1,148 @@ +.Dd $Mdocdate: November 5 2016 $ +.Dt DH 3 +.Os +.Sh NAME +.Nm dh +.Nd Diffie-Hellman key agreement +.Sh SYNOPSIS +.In openssl/dh.h +.In openssl/engine.h +.Ft DH * +.Fn DH_new void +.Ft void +.Fo DH_free +.Fa "DH *dh" +.Fc +.Ft int +.Fo DH_size +.Fa "const DH *dh" +.Fc +.Ft DH * +.Fo DH_generate_parameters +.Fa "int prime_len" +.Fa "int generator" +.Fa "void (*callback)(int, int, void *)" +.Fa "void *cb_arg" +.Fc +.Ft int +.Fo DH_check +.Fa "const DH *dh" +.Fa "int *codes" +.Fc +.Ft int +.Fo DH_generate_key +.Fa "DH *dh" +.Fc +.Ft int +.Fo DH_compute_key +.Fa "unsigned char *key" +.Fa "BIGNUM *pub_key" +.Fa "DH *dh" +.Fc +.Ft void +.Fo DH_set_default_method +.Fa "const DH_METHOD *meth" +.Fc +.Ft const DH_METHOD * +.Fn DH_get_default_method void +.Ft int +.Fo DH_set_method +.Fa "DH *dh" +.Fa "const DH_METHOD *meth" +.Fc +.Ft DH * +.Fo DH_new_method +.Fa "ENGINE *engine" +.Fc +.Ft const DH_METHOD * +.Fn DH_OpenSSL void +.Ft int +.Fo DH_get_ex_new_index +.Fa "long argl" +.Fa "char *argp" +.Fa "int (*new_func)()" +.Fa "int (*dup_func)()" +.Fa "void (*free_func)()" +.Fc +.Ft int +.Fo DH_set_ex_data +.Fa "DH *d" +.Fa "int idx" +.Fa "char *arg" +.Fc +.Ft char * +.Fo DH_get_ex_data +.Fa "DH *d" +.Fa "int idx" +.Fc +.Ft DH * +.Fo d2i_DHparams +.Fa "DH **a" +.Fa "unsigned char **pp" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_DHparams +.Fa "const DH *a" +.Fa "unsigned char **pp" +.Fc +.Ft int +.Fo DHparams_print_fp +.Fa "FILE *fp" +.Fa "const DH *x" +.Fc +.Ft int +.Fo DHparams_print +.Fa "BIO *bp" +.Fa "const DH *x" +.Fc +.Sh DESCRIPTION +These functions implement the Diffie-Hellman key agreement protocol. +The generation of shared DH parameters is described in +.Xr DH_generate_parameters 3 ; +.Xr DH_generate_key 3 +describes how to perform a key agreement. +.Pp +The +.Vt DH +structure consists of several +.Vt BIGNUM +components. +.Bd -literal +typedef struct { + BIGNUM *p; // prime number (shared) + BIGNUM *g; // generator of Z_p (shared) + BIGNUM *priv_key; // private DH value x + BIGNUM *pub_key; // public DH value g^x + // ... +} DH; +.Ed +.Pp +Note that DH keys may use non-standard +.Vt DH_METHOD +implementations, either directly or by the use of +.Vt ENGINE +modules. +In some cases (eg. an +.Vt ENGINE +providing support for hardware-embedded keys), these +.Vt BIGNUM +values will not be used by the implementation or may be used for +alternative data storage. +For this reason, applications should generally avoid using +.Vt DH +structure elements directly and instead use API functions to query +or modify keys. +.Sh SEE ALSO +.Xr bn 3 , +.Xr d2i_DHparams 3 , +.Xr DH_compute_key 3 , +.Xr DH_generate_parameters 3 , +.Xr DH_get_ex_new_index 3 , +.Xr DH_new 3 , +.Xr DH_set_method 3 , +.Xr dsa 3 , +.Xr engine 3 , +.Xr ERR 3 , +.Xr rsa 3 , +.Xr RSA_print 3 diff --git a/src/lib/libcrypto/man/dsa.3 b/src/lib/libcrypto/man/dsa.3 new file mode 100644 index 0000000000..b374f18d27 --- /dev/null +++ b/src/lib/libcrypto/man/dsa.3 @@ -0,0 +1,244 @@ +.Dd $Mdocdate: November 5 2016 $ +.Dt DSA 3 +.Os +.Sh NAME +.Nm dsa +.Nd Digital Signature Algorithm +.Sh SYNOPSIS +.In openssl/dsa.h +.In openssl/engine.h +.Ft DSA * +.Fn DSA_new void +.Ft void +.Fo DSA_free +.Fa "DSA *dsa" +.Fc +.Ft int +.Fo DSA_size +.Fa "const DSA *dsa" +.Fc +.Ft DSA * +.Fo DSA_generate_parameters +.Fa "int bits" +.Fa "unsigned char *seed" +.Fa "int seed_len" +.Fa "int *counter_ret" +.Fa "unsigned long *h_ret" +.Fa "void (*callback)(int, int, void *)" +.Fa "void *cb_arg" +.Fc +.Ft DH * +.Fo DSA_dup_DH +.Fa "const DSA *r" +.Fc +.Ft int +.Fo DSA_generate_key +.Fa "DSA *dsa" +.Fc +.Ft int +.Fo DSA_sign +.Fa "int dummy" +.Fa "const unsigned char *dgst" +.Fa "int len" +.Fa "unsigned char *sigret" +.Fa "unsigned int *siglen" +.Fa "DSA *dsa" +.Fc +.Ft int +.Fo DSA_sign_setup +.Fa "DSA *dsa" +.Fa "BN_CTX *ctx" +.Fa "BIGNUM **kinvp" +.Fa "BIGNUM **rp" +.Fc +.Ft int +.Fo DSA_verify +.Fa "int dummy" +.Fa "const unsigned char *dgst" +.Fa "int len" +.Fa "const unsigned char *sigbuf" +.Fa "int siglen" +.Fa "DSA *dsa" +.Fc +.Ft void +.Fo DSA_set_default_method +.Fa "const DSA_METHOD *meth" +.Fc +.Ft const DSA_METHOD * +.Fn DSA_get_default_method void +.Ft int +.Fo DSA_set_method +.Fa "DSA *dsa" +.Fa "const DSA_METHOD *meth" +.Fc +.Ft DSA * +.Fo DSA_new_method +.Fa "ENGINE *engine" +.Fc +.Ft const DSA_METHOD * +.Fn DSA_OpenSSL void +.Ft int +.Fo DSA_get_ex_new_index +.Fa "long argl" +.Fa "char *argp" +.Fa "int (*new_func)()" +.Fa "int (*dup_func)()" +.Fa "void (*free_func)()" +.Fc +.Ft int +.Fo DSA_set_ex_data +.Fa "DSA *d" +.Fa "int idx" +.Fa "char *arg" +.Fc +.Ft char * +.Fo DSA_get_ex_data +.Fa "DSA *d" +.Fa "int idx" +.Fc +.Ft DSA_SIG * +.Fn DSA_SIG_new void +.Ft void +.Fo DSA_SIG_free +.Fa "DSA_SIG *a" +.Fc +.Ft int +.Fo i2d_DSA_SIG +.Fa "const DSA_SIG *a" +.Fa "unsigned char **pp" +.Fc +.Ft DSA_SIG * +.Fo d2i_DSA_SIG +.Fa "DSA_SIG **v" +.Fa "unsigned char **pp" +.Fa "long length" +.Fc +.Ft DSA_SIG * +.Fo DSA_do_sign +.Fa "const unsigned char *dgst" +.Fa "int dlen" +.Fa "DSA *dsa" +.Fc +.Ft int +.Fo DSA_do_verify +.Fa "const unsigned char *dgst" +.Fa "int dgst_len" +.Fa "DSA_SIG *sig" +.Fa "DSA *dsa" +.Fc +.Ft DSA * +.Fo d2i_DSAPublicKey +.Fa "DSA **a" +.Fa "unsigned char **pp" +.Fa "long length" +.Fc +.Ft DSA * +.Fo d2i_DSAPrivateKey +.Fa "DSA **a" +.Fa "unsigned char **pp" +.Fa "long length" +.Fc +.Ft DSA * +.Fo d2i_DSAparams +.Fa "DSA **a" +.Fa "unsigned char **pp" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_DSAPublicKey +.Fa "const DSA *a" +.Fa "unsigned char **pp" +.Fc +.Ft int +.Fo i2d_DSAPrivateKey +.Fa "const DSA *a" +.Fa "unsigned char **pp" +.Fc +.Ft int +.Fo i2d_DSAparams +.Fa "const DSA *a" +.Fa "unsigned char **pp" +.Fc +.Ft int +.Fo DSAparams_print +.Fa "BIO *bp" +.Fa "const DSA *x" +.Fc +.Ft int +.Fo DSAparams_print_fp +.Fa "FILE *fp" +.Fa "const DSA *x" +.Fc +.Ft int +.Fo DSA_print +.Fa "BIO *bp" +.Fa "const DSA *x" +.Fa "int off" +.Fc +.Ft int +.Fo DSA_print_fp +.Fa "FILE *bp" +.Fa "const DSA *x" +.Fa "int off" +.Fc +.Sh DESCRIPTION +These functions implement the Digital Signature Algorithm (DSA). +The generation of shared DSA parameters is described in +.Xr DSA_generate_parameters 3 ; +.Xr DSA_generate_key 3 +describes how to generate a signature key. +Signature generation and verification are described in +.Xr DSA_sign 3 . +.Pp +The +.Vt DSA +structure consists of several BIGNUM components. +.Bd -literal +typedef struct { + BIGNUM *p; // prime number (public) + BIGNUM *q; // 160-bit subprime, q | p-1 (public) + BIGNUM *g; // generator of subgroup (public) + BIGNUM *priv_key; // private key x + BIGNUM *pub_key; // public key y = g^x + // ... +} DSA; +.Ed +.Pp +In public keys, +.Fa priv_key +is +.Dv NULL . +.Pp +Note that DSA keys may use non-standard +.Vt DSA_METHOD +implementations, either directly or by the use of +.Vt ENGINE +modules. +In some cases (eg. an +.Vt ENGINE +providing support for hardware-embedded keys), these +.Vt BIGNUM +values will not be used by the implementation or may be used for +alternative data storage. +For this reason, applications should generally avoid using +.Vt DSA +structure elements directly and instead use API functions to query +or modify keys. +.Sh SEE ALSO +.Xr bn 3 , +.Xr dh 3 , +.Xr DSA_dup_DH 3 , +.Xr DSA_generate_key 3 , +.Xr DSA_generate_parameters 3 , +.Xr DSA_get_ex_new_index 3 , +.Xr DSA_new 3 , +.Xr DSA_set_method 3 , +.Xr DSA_sign 3 , +.Xr DSA_size 3 , +.Xr engine 3 , +.Xr err 3 , +.Xr rsa 3 , +.Xr RSA_print 3 +.Sh STANDARDS +US Federal Information Processing Standard FIPS 186 (Digital Signature +Standard, DSS), ANSI X9.30 diff --git a/src/lib/libcrypto/man/ec.3 b/src/lib/libcrypto/man/ec.3 new file mode 100644 index 0000000000..3ecdd5dd8d --- /dev/null +++ b/src/lib/libcrypto/man/ec.3 @@ -0,0 +1,710 @@ +.Dd $Mdocdate: November 5 2016 $ +.Dt EC 3 +.Os +.Sh NAME +.Nm ec +.Nd Elliptic Curve functions +.Sh SYNOPSIS +.In openssl/ec.h +.In openssl/bn.h +.Ft const EC_METHOD * +.Fn EC_GFp_simple_method void +.Ft const EC_METHOD * +.Fn EC_GFp_mont_method void +.Ft const EC_METHOD * +.Fn EC_GFp_nist_method void +.Ft const EC_METHOD * +.Fn EC_GFp_nistp224_method void +.Ft const EC_METHOD * +.Fn EC_GFp_nistp256_method void +.Ft const EC_METHOD * +.Fn EC_GFp_nistp521_method void +.Ft const EC_METHOD * +.Fn EC_GF2m_simple_method void +.Ft EC_GROUP * +.Fo EC_GROUP_new +.Fa "const EC_METHOD *meth" +.Fc +.Ft void +.Fo EC_GROUP_free +.Fa "EC_GROUP *group" +.Fc +.Ft void +.Fo EC_GROUP_clear_free +.Fa "EC_GROUP *group" +.Fc +.Ft int +.Fo EC_GROUP_copy +.Fa "EC_GROUP *dst" +.Fa "const EC_GROUP *src" +.Fc +.Ft EC_GROUP * +.Fo EC_GROUP_dup +.Fa "const EC_GROUP *src" +.Fc +.Ft const EC_METHOD * +.Fo EC_GROUP_method_of +.Fa "const EC_GROUP *group" +.Fc +.Ft int +.Fo EC_METHOD_get_field_type +.Fa "const EC_METHOD *meth" +.Fc +.Ft int +.Fo EC_GROUP_set_generator +.Fa "EC_GROUP *group" +.Fa "const EC_POINT *generator" +.Fa "const BIGNUM *order" +.Fa "const BIGNUM *cofactor" +.Fc +.Ft const EC_POINT * +.Fo EC_GROUP_get0_generator +.Fa "const EC_GROUP *group" +.Fc +.Ft int +.Fo EC_GROUP_get_order +.Fa "const EC_GROUP *group" +.Fa "BIGNUM *order" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_GROUP_get_cofactor +.Fa "const EC_GROUP *group" +.Fa "BIGNUM *cofactor" +.Fa "BN_CTX *ctx" +.Fc +.Ft void +.Fo EC_GROUP_set_curve_name +.Fa "EC_GROUP *group" +.Fa "int nid" +.Fc +.Ft int +.Fo EC_GROUP_get_curve_name +.Fa "const EC_GROUP *group" +.Fc +.Ft void +.Fo EC_GROUP_set_asn1_flag +.Fa "EC_GROUP *group" +.Fa "int flag" +.Fc +.Ft int +.Fo EC_GROUP_get_asn1_flag +.Fa "const EC_GROUP *group" +.Fc +.Ft void +.Fo EC_GROUP_set_point_conversion_form +.Fa "EC_GROUP *group" +.Fa "point_conversion_form_t form" +.Fc +.Ft point_conversion_form_t +.Fo EC_GROUP_get_point_conversion_form +.Fa "const EC_GROUP *" +.Fc +.Ft unsigned char * +.Fo EC_GROUP_get0_seed +.Fa "const EC_GROUP *x" +.Fc +.Ft size_t +.Fo EC_GROUP_get_seed_len +.Fa "const EC_GROUP *" +.Fc +.Ft size_t +.Fo EC_GROUP_set_seed +.Fa "EC_GROUP *" +.Fa "const unsigned char *" +.Fa "size_t len" +.Fc +.Ft int +.Fo EC_GROUP_set_curve_GFp +.Fa "EC_GROUP *group" +.Fa "const BIGNUM *p" +.Fa "const BIGNUM *a" +.Fa "const BIGNUM *b" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_GROUP_get_curve_GFp +.Fa "const EC_GROUP *group" +.Fa "BIGNUM *p" +.Fa "BIGNUM *a" +.Fa "BIGNUM *b" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_GROUP_set_curve_GF2m +.Fa "EC_GROUP *group" +.Fa "const BIGNUM *p" +.Fa "const BIGNUM *a" +.Fa "const BIGNUM *b" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_GROUP_get_curve_GF2m +.Fa "const EC_GROUP *group" +.Fa "BIGNUM *p" +.Fa "BIGNUM *a" +.Fa "BIGNUM *b" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_GROUP_get_degree +.Fa "const EC_GROUP *group" +.Fc +.Ft int +.Fo EC_GROUP_check +.Fa "const EC_GROUP *group" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_GROUP_check_discriminant +.Fa "const EC_GROUP *group" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_GROUP_cmp +.Fa "const EC_GROUP *a" +.Fa "const EC_GROUP *b" +.Fa "BN_CTX *ctx" +.Fc +.Ft EC_GROUP * +.Fo EC_GROUP_new_curve_GFp +.Fa "const BIGNUM *p" +.Fa "const BIGNUM *a" +.Fa "const BIGNUM *b" +.Fa "BN_CTX *ctx" +.Fc +.Ft EC_GROUP * +.Fo EC_GROUP_new_curve_GF2m +.Fa "const BIGNUM *p" +.Fa "const BIGNUM *a" +.Fa "const BIGNUM *b" +.Fa "BN_CTX *ctx" +.Fc +.Ft EC_GROUP * +.Fo EC_GROUP_new_by_curve_name +.Fa "int nid" +.Fc +.Ft size_t +.Fo EC_get_builtin_curves +.Fa "EC_builtin_curve *r" +.Fa "size_t nitems" +.Fc +.Ft EC_POINT * +.Fo EC_POINT_new +.Fa "const EC_GROUP *group" +.Fc +.Ft void +.Fo EC_POINT_free +.Fa "EC_POINT *point" +.Fc +.Ft void +.Fo EC_POINT_clear_free +.Fa "EC_POINT *point" +.Fc +.Ft int +.Fo EC_POINT_copy +.Fa "EC_POINT *dst" +.Fa "const EC_POINT *src" +.Fc +.Ft EC_POINT * +.Fo EC_POINT_dup +.Fa "const EC_POINT *src" +.Fa "const EC_GROUP *group" +.Fc +.Ft const EC_METHOD * +.Fo EC_POINT_method_of +.Fa "const EC_POINT *point" +.Fc +.Ft int +.Fo EC_POINT_set_to_infinity +.Fa "const EC_GROUP *group" +.Fa "EC_POINT *point" +.Fc +.Ft int +.Fo EC_POINT_set_Jprojective_coordinates_GFp +.Fa "const EC_GROUP *group" +.Fa "EC_POINT *p" +.Fa "const BIGNUM *x" +.Fa "const BIGNUM *y" +.Fa "const BIGNUM *z" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_POINT_get_Jprojective_coordinates_GFp +.Fa "const EC_GROUP *group" +.Fa "const EC_POINT *p" +.Fa "BIGNUM *x" +.Fa "BIGNUM *y" +.Fa "BIGNUM *z" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_POINT_set_affine_coordinates_GFp +.Fa "const EC_GROUP *group" +.Fa "EC_POINT *p" +.Fa "const BIGNUM *x" +.Fa "const BIGNUM *y" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_POINT_get_affine_coordinates_GFp +.Fa "const EC_GROUP *group" +.Fa "const EC_POINT *p" +.Fa "BIGNUM *x" +.Fa "BIGNUM *y" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_POINT_set_compressed_coordinates_GFp +.Fa "const EC_GROUP *group" +.Fa "EC_POINT *p" +.Fa "const BIGNUM *x" +.Fa "int y_bit" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_POINT_set_affine_coordinates_GF2m +.Fa "const EC_GROUP *group" +.Fa "EC_POINT *p" +.Fa "const BIGNUM *x" +.Fa "const BIGNUM *y" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_POINT_get_affine_coordinates_GF2m +.Fa "const EC_GROUP *group" +.Fa "const EC_POINT *p" +.Fa "BIGNUM *x" +.Fa "BIGNUM *y" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_POINT_set_compressed_coordinates_GF2m +.Fa "const EC_GROUP *group" +.Fa "EC_POINT *p" +.Fa "const BIGNUM *x" +.Fa "int y_bit" +.Fa "BN_CTX *ctx" +.Fc +.Ft size_t +.Fo EC_POINT_point2oct +.Fa "const EC_GROUP *group" +.Fa "const EC_POINT *p" +.Fa "point_conversion_form_t form" +.Fa "unsigned char *buf" +.Fa "size_t len" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_POINT_oct2point +.Fa "const EC_GROUP *group" +.Fa "EC_POINT *p" +.Fa "const unsigned char *buf" +.Fa "size_t len" +.Fa "BN_CTX *ctx" +.Fc +.Ft BIGNUM * +.Fo EC_POINT_point2bn +.Fa "const EC_GROUP *" +.Fa "const EC_POINT *" +.Fa "point_conversion_form_t form" +.Fa "BIGNUM *" +.Fa "BN_CTX *" +.Fc +.Ft EC_POINT * +.Fo EC_POINT_bn2point +.Fa "const EC_GROUP *" +.Fa "const BIGNUM *" +.Fa "EC_POINT *" +.Fa "BN_CTX *" +.Fc +.Ft char * +.Fo EC_POINT_point2hex +.Fa "const EC_GROUP *" +.Fa "const EC_POINT *" +.Fa "point_conversion_form_t form" +.Fa "BN_CTX *" +.Fc +.Ft EC_POINT * +.Fo EC_POINT_hex2point +.Fa "const EC_GROUP *" +.Fa "const char *" +.Fa "EC_POINT *" +.Fa "BN_CTX *" +.Fc +.Ft int +.Fo EC_POINT_add +.Fa "const EC_GROUP *group" +.Fa "EC_POINT *r" +.Fa "const EC_POINT *a" +.Fa "const EC_POINT *b" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_POINT_dbl +.Fa "const EC_GROUP *group" +.Fa "EC_POINT *r" +.Fa "const EC_POINT *a" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_POINT_invert +.Fa "const EC_GROUP *group" +.Fa "EC_POINT *a" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_POINT_is_at_infinity +.Fa "const EC_GROUP *group" +.Fa "const EC_POINT *p" +.Fc +.Ft int +.Fo EC_POINT_is_on_curve +.Fa "const EC_GROUP *group" +.Fa "const EC_POINT *point" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_POINT_cmp +.Fa "const EC_GROUP *group" +.Fa "const EC_POINT *a" +.Fa "const EC_POINT *b" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_POINT_make_affine +.Fa "const EC_GROUP *group" +.Fa "EC_POINT *point" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_POINTs_make_affine +.Fa "const EC_GROUP *group" +.Fa "size_t num" +.Fa "EC_POINT *points[]" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_POINTs_mul +.Fa "const EC_GROUP *group" +.Fa "EC_POINT *r" +.Fa "const BIGNUM *n" +.Fa "size_t num" +.Fa "const EC_POINT *p[]" +.Fa "const BIGNUM *m[]" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_POINT_mul +.Fa "const EC_GROUP *group" +.Fa "EC_POINT *r" +.Fa "const BIGNUM *n" +.Fa "const EC_POINT *q" +.Fa "const BIGNUM *m" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_GROUP_precompute_mult +.Fa "EC_GROUP *group" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_GROUP_have_precompute_mult +.Fa "const EC_GROUP *group" +.Fc +.Ft int +.Fo EC_GROUP_get_basis_type +.Fa "const EC_GROUP *" +.Fc +.Ft int +.Fo EC_GROUP_get_trinomial_basis +.Fa "const EC_GROUP *" +.Fa "unsigned int *k" +.Fc +.Ft int +.Fo EC_GROUP_get_pentanomial_basis +.Fa "const EC_GROUP *" +.Fa "unsigned int *k1" +.Fa "unsigned int *k2" +.Fa "unsigned int *k3" +.Fc +.Ft EC_GROUP * +.Fo d2i_ECPKParameters +.Fa "EC_GROUP **" +.Fa "const unsigned char **in" +.Fa "long len" +.Fc +.Ft int +.Fo i2d_ECPKParameters +.Fa "const EC_GROUP *" +.Fa "unsigned char **out" +.Fc +.Fd #define d2i_ECPKParameters_bio(bp,x)\ + ASN1_d2i_bio_of(EC_GROUP,NULL,d2i_ECPKParameters,bp,x) +.Fd #define i2d_ECPKParameters_bio(bp,x)\ + ASN1_i2d_bio_of_const(EC_GROUP,i2d_ECPKParameters,bp,x) +.Fd #define d2i_ECPKParameters_fp(fp,x) (EC_GROUP *)ASN1_d2i_fp(NULL,\ + (char *(*)())d2i_ECPKParameters,(fp),(unsigned char **)(x)) +.Fd #define i2d_ECPKParameters_fp(fp,x)\ + ASN1_i2d_fp(i2d_ECPKParameters,(fp), (unsigned char *)(x)) +.Ft int +.Fo ECPKParameters_print +.Fa "BIO *bp" +.Fa "const EC_GROUP *x" +.Fa "int off" +.Fc +.Ft int +.Fo ECPKParameters_print_fp +.Fa "FILE *fp" +.Fa "const EC_GROUP *x" +.Fa "int off" +.Fc +.Ft EC_KEY * +.Fn EC_KEY_new void +.Ft int +.Fo EC_KEY_get_flags +.Fa "const EC_KEY *key" +.Fc +.Ft void +.Fo EC_KEY_set_flags +.Fa "EC_KEY *key" +.Fa "int flags" +.Fc +.Ft void +.Fo EC_KEY_clear_flags +.Fa "EC_KEY *key" +.Fa "int flags" +.Fc +.Ft EC_KEY * +.Fo EC_KEY_new_by_curve_name +.Fa "int nid" +.Fc +.Ft void +.Fo EC_KEY_free +.Fa "EC_KEY *key" +.Fc +.Ft EC_KEY * +.Fo EC_KEY_copy +.Fa "EC_KEY *dst" +.Fa "const EC_KEY *src" +.Fc +.Ft EC_KEY * +.Fo EC_KEY_dup +.Fa "const EC_KEY *src" +.Fc +.Ft int +.Fo EC_KEY_up_ref +.Fa "EC_KEY *key" +.Fc +.Ft const EC_GROUP * +.Fo EC_KEY_get0_group +.Fa "const EC_KEY *key" +.Fc +.Ft int +.Fo EC_KEY_set_group +.Fa "EC_KEY *key" +.Fa "const EC_GROUP *group" +.Fc +.Ft const BIGNUM * +.Fo EC_KEY_get0_private_key +.Fa "const EC_KEY *key" +.Fc +.Ft int +.Fo EC_KEY_set_private_key +.Fa "EC_KEY *key" +.Fa "const BIGNUM *prv" +.Fc +.Ft const EC_POINT * +.Fo EC_KEY_get0_public_key +.Fa "const EC_KEY *key" +.Fc +.Ft int +.Fo EC_KEY_set_public_key +.Fa "EC_KEY *key" +.Fa "const EC_POINT *pub" +.Fc +.Ft unsigned +.Fo EC_KEY_get_enc_flags +.Fa "const EC_KEY *key" +.Fc +.Ft void +.Fo EC_KEY_set_enc_flags +.Fa "EC_KEY *eckey" +.Fa "unsigned int flags" +.Fc +.Ft point_conversion_form_t +.Fo EC_KEY_get_conv_form +.Fa "const EC_KEY *key" +.Fc +.Ft void +.Fo EC_KEY_set_conv_form +.Fa "EC_KEY *eckey" +.Fa "point_conversion_form_t cform" +.Fc +.Ft void * +.Fo EC_KEY_get_key_method_data +.Fa "EC_KEY *key" +.Fa "void *(*dup_func)(void *)" +.Fa "void (*free_func)(void *)" +.Fa "void (*clear_free_func)(void *)" +.Fc +.Ft void +.Fo EC_KEY_insert_key_method_data +.Fa "EC_KEY *key" +.Fa "void *data" +.Fa "void *(*dup_func)(void *)" +.Fa "void (*free_func)(void *)" +.Fa "void (*clear_free_func)(void *)" +.Fc +.Ft void +.Fo EC_KEY_set_asn1_flag +.Fa "EC_KEY *eckey" +.Fa "int asn1_flag" +.Fc +.Ft int +.Fo EC_KEY_precompute_mult +.Fa "EC_KEY *key" +.Fa "BN_CTX *ctx" +.Fc +.Ft int +.Fo EC_KEY_generate_key +.Fa "EC_KEY *key" +.Fc +.Ft int +.Fo EC_KEY_check_key +.Fa "const EC_KEY *key" +.Fc +.Ft int +.Fo EC_KEY_set_public_key_affine_coordinates +.Fa "EC_KEY *key" +.Fa "BIGNUM *x" +.Fa "BIGNUM *y" +.Fc +.Ft EC_KEY * +.Fo d2i_ECPrivateKey +.Fa "EC_KEY **key" +.Fa "const unsigned char **in" +.Fa "long len" +.Fc +.Ft int +.Fo i2d_ECPrivateKey +.Fa "EC_KEY *key" +.Fa "unsigned char **out" +.Fc +.Ft EC_KEY * +.Fo d2i_ECParameters +.Fa "EC_KEY **key" +.Fa "const unsigned char **in" +.Fa "long len" +.Fc +.Ft int +.Fo i2d_ECParameters +.Fa "EC_KEY *key" +.Fa "unsigned char **out" +.Fc +.Ft EC_KEY * +.Fo o2i_ECPublicKey +.Fa "EC_KEY **key" +.Fa "const unsigned char **in" +.Fa "long len" +.Fc +.Ft int +.Fo i2o_ECPublicKey +.Fa "EC_KEY *key" +.Fa "unsigned char **out" +.Fc +.Ft int +.Fo ECParameters_print +.Fa "BIO *bp" +.Fa "const EC_KEY *key" +.Fc +.Ft int +.Fo EC_KEY_print +.Fa "BIO *bp" +.Fa "const EC_KEY *key" +.Fa "int off" +.Fc +.Ft int +.Fo ECParameters_print_fp +.Fa "FILE *fp" +.Fa "const EC_KEY *key" +.Fc +.Ft int +.Fo EC_KEY_print_fp +.Fa "FILE *fp" +.Fa "const EC_KEY *key" +.Fa "int off" +.Fc +.Ft EC_KEY * +.Fo ECParameters_dup +.Fa "EC_KEY *key" +.Fc +.Fd #define EVP_PKEY_CTX_set_ec_paramgen_curve_nid(ctx, nid)\ + EVP_PKEY_CTX_ctrl(ctx, EVP_PKEY_EC, EVP_PKEY_OP_PARAMGEN,\ + EVP_PKEY_CTRL_EC_PARAMGEN_CURVE_NID, nid, NULL) +.Sh DESCRIPTION +This library provides an extensive set of functions for performing +operations on elliptic curves over finite fields. +In general an elliptic curve is one with an equation of the form: +.Pp +.Dl y^2 = x^3 + ax + b +.Pp +An +.Vt EC_GROUP +structure is used to represent the definition of an elliptic curve. +Points on a curve are stored using an +.Vt EC_POINT +structure. +An +.Vt EC_KEY +is used to hold a private/public key pair, where a private key is simply a +.Vt BIGNUM +and a public key is a point on a curve represented by an +.Vt EC_POINT . +.Pp +The library contains a number of alternative implementations of the +different functions. +Each implementation is optimised for different scenarios. +No matter which implementation is being used, the interface remains the +same. +The library handles calling the correct implementation when an interface +function is invoked. +An implementation is represented by an +.Vt EC_METHOD +structure. +.Pp +The creation and destruction of +.Vt EC_GROUP +objects is described in +.Xr EC_GROUP_new 3 . +Functions for manipulating +.Vt EC_GROUP +objects are described in +.Xr EC_GROUP_copy 3 . +.Pp +Functions for creating, destroying and manipulating +.Vt EC_POINT +objects are explained in +.Xr EC_POINT_new 3 , +whilst functions for performing mathematical operations and tests on +.Vt EC_POINT Ns s +are coverd in +.Xr EC_POINT_add 3 . +.Pp +For working with private and public keys refer to +.Xr EC_KEY_new 3 . +Implementations are covered in +.Xr EC_GFp_simple_method 3 . +.Pp +For information on encoding and decoding curve parameters to and +from ASN.1 see +.Xr d2i_ECPKParameters 3 . +.Sh SEE ALSO +.Xr crypto 3 , +.Xr d2i_ECPKParameters 3 , +.Xr EC_GFp_simple_method 3 , +.Xr EC_GROUP_copy 3 , +.Xr EC_GROUP_new 3 , +.Xr EC_KEY_new 3 , +.Xr EC_POINT_add 3 , +.Xr EC_POINT_new 3 diff --git a/src/lib/libcrypto/man/engine.3 b/src/lib/libcrypto/man/engine.3 new file mode 100644 index 0000000000..3624fa76e4 --- /dev/null +++ b/src/lib/libcrypto/man/engine.3 @@ -0,0 +1,1187 @@ +.Dd $Mdocdate: November 5 2016 $ +.Dt ENGINE 3 +.Os +.Sh NAME +.Nm ENGINE_add , +.Nm ENGINE_by_id , +.Nm ENGINE_finish , +.Nm ENGINE_get_first , +.Nm ENGINE_get_last , +.Nm ENGINE_get_next , +.Nm ENGINE_get_prev , +.Nm ENGINE_init , +.Nm ENGINE_load_builtin_engines , +.Nm ENGINE_remove +.Nd ENGINE cryptographic module support +.Sh SYNOPSIS +.In openssl/engine.h +.Ft ENGINE * +.Fn ENGINE_get_first void +.Ft ENGINE * +.Fn ENGINE_get_last void +.Ft ENGINE * +.Fo ENGINE_get_next +.Fa "ENGINE *e" +.Fc +.Ft ENGINE * +.Fo ENGINE_get_prev +.Fa "ENGINE *e" +.Fc +.Ft int +.Fo ENGINE_add +.Fa "ENGINE *e" +.Fc +.Ft int +.Fo ENGINE_remove +.Fa "ENGINE *e" +.Fc +.Ft ENGINE * +.Fo ENGINE_by_id +.Fa "const char *id" +.Fc +.Ft int +.Fo ENGINE_init +.Fa "ENGINE *e" +.Fc +.Ft int +.Fo ENGINE_finish +.Fa "ENGINE *e" +.Fc +.Ft void +.Fn ENGINE_load_openssl void +.Ft void +.Fn ENGINE_load_dynamic void +.Ft void +.Fn ENGINE_load_cryptodev void +.Ft void +.Fn ENGINE_load_builtin_engines void +.Ft void +.Fn ENGINE_cleanup void +.Ft ENGINE * +.Fn ENGINE_get_default_RSA void +.Ft ENGINE * +.Fn ENGINE_get_default_DSA void +.Ft ENGINE * +.Fn ENGINE_get_default_ECDH void +.Ft ENGINE * +.Fn ENGINE_get_default_ECDSA void +.Ft ENGINE * +.Fn ENGINE_get_default_DH void +.Ft ENGINE * +.Fn ENGINE_get_default_RAND void +.Ft ENGINE * +.Fo ENGINE_get_cipher_engine +.Fa "int nid" +.Fc +.Ft ENGINE * +.Fo ENGINE_get_digest_engine +.Fa "int nid" +.Fc +.Ft int +.Fo ENGINE_set_default_RSA +.Fa "ENGINE *e" +.Fc +.Ft int +.Fo ENGINE_set_default_DSA +.Fa "ENGINE *e" +.Fc +.Ft int +.Fo ENGINE_set_default_ECDH +.Fa "ENGINE *e" +.Fc +.Ft int +.Fo ENGINE_set_default_ECDSA +.Fa "ENGINE *e" +.Fc +.Ft int +.Fo ENGINE_set_default_DH +.Fa "ENGINE *e" +.Fc +.Ft int +.Fo ENGINE_set_default_RAND +.Fa "ENGINE *e" +.Fc +.Ft int +.Fo ENGINE_set_default_ciphers +.Fa "ENGINE *e" +.Fc +.Ft int +.Fo ENGINE_set_default_digests +.Fa "ENGINE *e" +.Fc +.Ft int +.Fo ENGINE_set_default_string +.Fa "ENGINE *e" +.Fa "const char *list" +.Fc +.Ft int +.Fo ENGINE_set_default +.Fa "ENGINE *e" +.Fa "unsigned int flags" +.Fc +.Ft unsigned int +.Fn ENGINE_get_table_flags void +.Ft void +.Fo ENGINE_set_table_flags +.Fa "unsigned int flags" +.Fc +.Ft int +.Fo ENGINE_register_RSA +.Fa "ENGINE *e" +.Fc +.Ft void +.Fo ENGINE_unregister_RSA +.Fa "ENGINE *e" +.Fc +.Ft void +.Fn ENGINE_register_all_RSA void +.Ft int +.Fo ENGINE_register_DSA +.Fa "ENGINE *e" +.Fc +.Ft void +.Fo ENGINE_unregister_DSA +.Fa "ENGINE *e" +.Fc +.Ft void +.Fn ENGINE_register_all_DSA void +.Ft int +.Fo ENGINE_register_ECDH +.Fa "ENGINE *e" +.Fc +.Ft void +.Fo ENGINE_unregister_ECDH +.Fa "ENGINE *e" +.Fc +.Ft void +.Fn ENGINE_register_all_ECDH void +.Ft int +.Fo ENGINE_register_ECDSA +.Fa "ENGINE *e" +.Fc +.Ft void +.Fo ENGINE_unregister_ECDSA +.Fa "ENGINE *e" +.Fc +.Ft void +.Fn ENGINE_register_all_ECDSA void +.Ft int +.Fo ENGINE_register_DH +.Fa "ENGINE *e" +.Fc +.Ft void +.Fo ENGINE_unregister_DH +.Fa "ENGINE *e" +.Fc +.Ft void +.Fn ENGINE_register_all_DH void +.Ft int +.Fo ENGINE_register_RAND +.Fa "ENGINE *e" +.Fc +.Ft void +.Fo ENGINE_unregister_RAND +.Fa "ENGINE *e" +.Fc +.Ft void +.Fn ENGINE_register_all_RAND void +.Ft int +.Fo ENGINE_register_STORE +.Fa "ENGINE *e" +.Fc +.Ft void +.Fo ENGINE_unregister_STORE +.Fa "ENGINE *e" +.Fc +.Ft void +.Fn ENGINE_register_all_STORE void +.Ft int +.Fo ENGINE_register_ciphers +.Fa "ENGINE *e" +.Fc +.Ft void +.Fo ENGINE_unregister_ciphers +.Fa "ENGINE *e" +.Fc +.Ft void +.Fn ENGINE_register_all_ciphers void +.Ft int +.Fo ENGINE_register_digests +.Fa "ENGINE *e" +.Fc +.Ft void +.Fo ENGINE_unregister_digests +.Fa "ENGINE *e" +.Fc +.Ft void +.Fn ENGINE_register_all_digests void +.Ft int +.Fo ENGINE_register_complete +.Fa "ENGINE *e" +.Fc +.Ft int +.Fn ENGINE_register_all_complete void +.Ft int +.Fo ENGINE_ctrl +.Fa "ENGINE *e" +.Fa "int cmd" +.Fa "long i" +.Fa "void *p" +.Fa "void (*f)(void)" +.Fc +.Ft int +.Fo ENGINE_cmd_is_executable +.Fa "ENGINE *e" +.Fa "int cmd" +.Fc +.Ft int +.Fo ENGINE_ctrl_cmd +.Fa "ENGINE *e" +.Fa "const char *cmd_name" +.Fa "long i" +.Fa "void *p" +.Fa "void (*f)(void)" +.Fa "int cmd_optional" +.Fc +.Ft int +.Fo ENGINE_ctrl_cmd_string +.Fa "ENGINE *e" +.Fa "const char *cmd_name" +.Fa "const char *arg" +.Fa "int cmd_optional" +.Fc +.Ft int +.Fo ENGINE_set_ex_data +.Fa "ENGINE *e" +.Fa "int idx" +.Fa "void *arg" +.Fc +.Ft void * +.Fo ENGINE_get_ex_data +.Fa "const ENGINE *e" +.Fa "int idx" +.Fc +.Ft int +.Fo ENGINE_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 ENGINE * +.Fn ENGINE_new void +.Ft int +.Fo ENGINE_free +.Fa "ENGINE *e" +.Fc +.Ft int +.Fo ENGINE_up_ref +.Fa "ENGINE *e" +.Fc +.Ft int +.Fo ENGINE_set_id +.Fa "ENGINE *e" +.Fa "const char *id" +.Fc +.Ft int +.Fo ENGINE_set_name +.Fa "ENGINE *e" +.Fa "const char *name" +.Fc +.Ft int +.Fo ENGINE_set_RSA +.Fa "ENGINE *e" +.Fa "const RSA_METHOD *rsa_meth" +.Fc +.Ft int +.Fo ENGINE_set_DSA +.Fa "ENGINE *e" +.Fa "const DSA_METHOD *dsa_meth" +.Fc +.Ft int +.Fo ENGINE_set_ECDH +.Fa "ENGINE *e" +.Fa "const ECDH_METHOD *dh_meth" +.Fc +.Ft int +.Fo ENGINE_set_ECDSA +.Fa "ENGINE *e" +.Fa "const ECDSA_METHOD *dh_meth" +.Fc +.Ft int +.Fo ENGINE_set_DH +.Fa "ENGINE *e" +.Fa "const DH_METHOD *dh_meth" +.Fc +.Ft int +.Fo ENGINE_set_RAND +.Fa "ENGINE *e" +.Fa "const RAND_METHOD *rand_meth" +.Fc +.Ft int +.Fo ENGINE_set_STORE +.Fa "ENGINE *e" +.Fa "const STORE_METHOD *rand_meth" +.Fc +.Ft int +.Fo ENGINE_set_destroy_function +.Fa "ENGINE *e" +.Fa "ENGINE_GEN_INT_FUNC_PTR destroy_f" +.Fc +.Ft int +.Fo ENGINE_set_init_function +.Fa "ENGINE *e" +.Fa "ENGINE_GEN_INT_FUNC_PTR init_f" +.Fc +.Ft int +.Fo ENGINE_set_finish_function +.Fa "ENGINE *e" +.Fa "ENGINE_GEN_INT_FUNC_PTR finish_f" +.Fc +.Ft int +.Fo ENGINE_set_ctrl_function +.Fa "ENGINE *e" +.Fa "ENGINE_CTRL_FUNC_PTR ctrl_f" +.Fc +.Ft int +.Fo ENGINE_set_load_privkey_function +.Fa "ENGINE *e" +.Fa "ENGINE_LOAD_KEY_PTR loadpriv_f" +.Fc +.Ft int +.Fo ENGINE_set_load_pubkey_function +.Fa "ENGINE *e" +.Fa "ENGINE_LOAD_KEY_PTR loadpub_f" +.Fc +.Ft int +.Fo ENGINE_set_ciphers +.Fa "ENGINE *e" +.Fa "ENGINE_CIPHERS_PTR f" +.Fc +.Ft int +.Fo ENGINE_set_digests +.Fa "ENGINE *e" +.Fa "ENGINE_DIGESTS_PTR f" +.Fc +.Ft int +.Fo ENGINE_set_flags +.Fa "ENGINE *e" +.Fa "int flags" +.Fc +.Ft int +.Fo ENGINE_set_cmd_defns +.Fa "ENGINE *e" +.Fa "const ENGINE_CMD_DEFN *defns" +.Fc +.Ft const char * +.Fo ENGINE_get_id +.Fa "const ENGINE *e" +.Fc +.Ft const char * +.Fo ENGINE_get_name +.Fa "const ENGINE *e" +.Fc +.Ft const RSA_METHOD * +.Fo ENGINE_get_RSA +.Fa "const ENGINE *e" +.Fc +.Ft const DSA_METHOD * +.Fo ENGINE_get_DSA +.Fa "const ENGINE *e" +.Fc +.Ft const ECDH_METHOD * +.Fo ENGINE_get_ECDH +.Fa "const ENGINE *e" +.Fc +.Ft const ECDSA_METHOD * +.Fo ENGINE_get_ECDSA +.Fa "const ENGINE *e" +.Fc +.Ft const DH_METHOD * +.Fo ENGINE_get_DH +.Fa "const ENGINE *e" +.Fc +.Ft const RAND_METHOD * +.Fo ENGINE_get_RAND +.Fa "const ENGINE *e" +.Fc +.Ft const STORE_METHOD * +.Fo ENGINE_get_STORE +.Fa "const ENGINE *e" +.Fc +.Ft ENGINE_GEN_INT_FUNC_PTR +.Fo ENGINE_get_destroy_function +.Fa "const ENGINE *e" +.Fc +.Ft ENGINE_GEN_INT_FUNC_PTR +.Fo ENGINE_get_init_function +.Fa "const ENGINE *e" +.Fc +.Ft ENGINE_GEN_INT_FUNC_PTR +.Fo ENGINE_get_finish_function +.Fa "const ENGINE *e" +.Fc +.Ft ENGINE_CTRL_FUNC_PTR +.Fo ENGINE_get_ctrl_function +.Fa "const ENGINE *e" +.Fc +.Ft ENGINE_LOAD_KEY_PTR +.Fo ENGINE_get_load_privkey_function +.Fa "const ENGINE *e" +.Fc +.Ft ENGINE_LOAD_KEY_PTR +.Fo ENGINE_get_load_pubkey_function +.Fa "const ENGINE *e" +.Fc +.Ft ENGINE_CIPHERS_PTR +.Fo ENGINE_get_ciphers +.Fa "const ENGINE *e" +.Fc +.Ft ENGINE_DIGESTS_PTR +.Fo ENGINE_get_digests +.Fa "const ENGINE *e" +.Fc +.Ft const EVP_CIPHER * +.Fo ENGINE_get_cipher +.Fa "ENGINE *e" +.Fa "int nid" +.Fc +.Ft const EVP_MD * +.Fo ENGINE_get_digest +.Fa "ENGINE *e" +.Fa "int nid" +.Fc +.Ft int +.Fo ENGINE_get_flags +.Fa "const ENGINE *e" +.Fc +.Ft const ENGINE_CMD_DEFN * +.Fo ENGINE_get_cmd_defns +.Fa "const ENGINE *e" +.Fc +.Ft EVP_PKEY * +.Fo ENGINE_load_private_key +.Fa "ENGINE *e" +.Fa "const char *key_id" +.Fa "UI_METHOD *ui_method" +.Fa "void *callback_data" +.Fc +.Ft EVP_PKEY * +.Fo ENGINE_load_public_key +.Fa "ENGINE *e" +.Fa "const char *key_id" +.Fa "UI_METHOD *ui_method" +.Fa "void *callback_data" +.Fc +.Ft void +.Fn ENGINE_add_conf_module void +.Sh DESCRIPTION +These functions create, manipulate, and use cryptographic modules +in the form of +.Vt ENGINE +objects. +These objects act as containers for implementations of cryptographic +algorithms, and support a reference-counted mechanism to allow them to +be dynamically loaded in and out of the running application. +.Pp +The cryptographic functionality that can be provided by an +.Vt ENGINE +implementation includes the following abstractions: +.Pp +.Bl -bullet -compact +.It +.Vt RSA_METHOD : +for providing alternative RSA implementations +.It +.Vt DSA_METHOD , DH_METHOD , RAND_METHOD , ECDH_METHOD , +.Vt ECDSA_METHOD , STORE_METHOD : +similarly for other OpenSSL APIs +.It +.Vt EVP_CIPHER : +potentially multiple cipher algorithms (indexed by 'nid') +.It +.Vt EVP_DIGEST : +potentially multiple hash algorithms (indexed by 'nid') +.It +key-loading: loading public and/or private EVP_PKEY keys +.El +.Ss Reference counting and handles +Due to the modular nature of the +.Nm engine +API, pointers to +.Vt ENGINE Ns s +need to be treated as handles - ie. not only as pointers, but also +as references to the underlying +.Vt ENGINE +object. +One should obtain a new reference when making copies of an +.Vt ENGINE +pointer if the copies will be used (and released) independently. +.Pp +.Vt ENGINE +objects have two levels of reference-counting to match the way in +which the objects are used. +At the most basic level, each +.Vt ENGINE +pointer is inherently a +.Sy structural +reference - a structural reference is required to use the pointer value +at all, as this kind of reference is a guarantee that the structure can +not be deallocated until the reference is released. +.Pp +However, a structural reference provides no guarantee that the +.Vt ENGINE +is initialised and able to use any of its cryptographic implementations. +Indeed it's quite possible that most +.Vt ENGINE Ns s +will not initialise at all in typical environments, as +.Vt ENGINE Ns s +are typically used to support specialised hardware. +To use an +.Vt ENGINE Ap s +functionality, you need a +.Sy functional +reference. +This kind of reference can be considered a specialised form of +structural reference, because each functional reference implicitly +contains a structural reference as well - however to avoid +difficult-to-find programming bugs, it is recommended to treat the two +kinds of reference independently. +If you have a functional reference to an +.Vt ENGINE , +you have a guarantee that the +.Vt ENGINE +has been initialised ready to perform cryptographic operations and +will remain uninitialised until after you have released your +reference. +.Pp +.Em Structural references +.Pp +This basic type of reference is used for instantiating new +.Vt ENGINE Ns s, +iterating across OpenSSL's internal linked-list of loaded +.Vt ENGINE Ns s, +reading information about an +.Vt ENGINE , +etc. +Essentially a structural reference is sufficient if you only need to +query or manipulate the data of an +.Vt ENGINE +implementation rather than use its functionality. +.Pp +The +.Fn ENGINE_new +function returns a structural reference to a new (empty) +.Vt ENGINE +object. +There are other +.Nm engine +API functions that return structural references such as +.Fn ENGINE_by_id , +.Fn ENGINE_get_first , +.Fn ENGINE_get_last , +.Fn ENGINE_get_next , +and +.Fn ENGINE_get_prev . +All structural references should be released by a corresponding call +to the +.Fn ENGINE_free +function. +The +.Vt ENGINE +object itself will only actually be cleaned up and deallocated when +the last structural reference is released. +.Pp +It should also be noted that many +.Nm engine +API function calls that accept a structural reference will internally +obtain another reference. +Typically this happens whenever the supplied +.Vt ENGINE +will be needed by OpenSSL after the function has returned. +For example, the function to add a new +.Vt ENGINE +to OpenSSL's internal list is +.Fn ENGINE_add . +If this function returns success, OpenSSL will have stored a new +structural reference internally so the caller is still responsible for +freeing their own reference with +.Fn ENGINE_free +when they are finished with it. +In a similar way, some functions will automatically release the +structural reference passed to it if part of the function's job is +to do so. +For example, the +.Fn ENGINE_get_next +and +.Fn ENGINE_get_prev +functions are used for iterating across the internal +.Vt ENGINE +list. +They +will return a new structural reference to the next (or previous) +.Vt ENGINE +in the list or +.Dv NULL +if at the end (or beginning) of the list, but in either case the +structural reference passed to the function is released on behalf +of the caller. +.Pp +To clarify a particular function's handling of references, one should +always consult that function's manual page, or failing that the +.In openssl/engine.h +header file includes some hints. +.Pp +.Em Functional references +.Pp +As mentioned, functional references exist when the cryptographic +functionality of an +.Vt ENGINE +is required to be available. +A functional reference can be obtained in one of two ways; from an +existing structural reference to the required +.Vt ENGINE , +or by asking OpenSSL for the default operational +.Vt ENGINE +for a given cryptographic purpose. +.Pp +To obtain a functional reference from an existing structural reference, +call the +.Fn ENGINE_init +function. +This returns zero if the +.Vt ENGINE +was not already operational and couldn't be successfully initialised +(eg. lack of system drivers, no special hardware attached, etc.), +otherwise it will return non-zero to indicate that the +.Vt ENGINE +is now operational and will have allocated a new +.Sy functional +reference to the +.Vt ENGINE . +All functional references are released by calling +.Fn ENGINE_finish , +which removes the implicit structural reference as well. +.Pp +The second way to get a functional reference is by asking OpenSSL for a +default implementation for a given task, eg. +by +.Fn ENGINE_get_default_RSA , +.Fn ENGINE_get_default_cipher_engine , +etc. +These are discussed in the next section, though they are not usually +required by application programmers as they are used automatically when +creating and using the relevant algorithm-specific types in OpenSSL, +such as RSA, DSA, EVP_CIPHER_CTX, etc. +.Ss Default implementations +For each supported abstraction, the +.Nm engine +code maintains an internal table of state to control which +implementations are available for a given abstraction and which +should be used by default. +These implementations are registered in the tables and indexed by an +.Fa nid +value, because abstractions like +.Vt EVP_CIPHER +and +.Vt EVP_DIGEST +support many distinct algorithms and modes, and +.Vt ENGINE Ns s +can support arbitrarily many of them. +In the case of other abstractions like RSA, DSA, etc., there is +only one "algorithm" so all implementations implicitly register +using the same +.Fa nid +index. +.Pp +When a default +.Vt ENGINE +is requested for a given abstraction/algorithm/mode, (eg. when +calling +.Fn RSA_new_method NULL ) , +a "get_default" call will be made to the +.Nm engine +subsystem to process the corresponding state table and return +a functional reference to an initialised +.Vt ENGINE +whose implementation should be used. +If no +.Vt ENGINE +should (or can) be used, it will return +.Dv NULL +and the caller will operate with a +.Dv NULL +.Vt ENGINE +handle. +This usually equates to using the conventional software implementation. +In the latter case, OpenSSL will from then on behave the way it used to +before the +.Nm engine +API existed. +.Pp +Each state table has a flag to note whether it has processed this +"get_default" query since the table was last modified, because to +process this question it must iterate across all the registered +.Vt ENGINE Ns s +in the table trying to initialise each of them in turn, in case one of +them is operational. +If it returns a functional reference to an +.Vt ENGINE , +it will also cache another reference to speed up processing future +queries (without needing to iterate across the table). +Likewise, it will cache a +.Dv NULL +response if no +.Vt ENGINE +was available so that future queries won't repeat the same iteration +unless the state table changes. +This behaviour can also be changed; if the +.Dv ENGINE_TABLE_FLAG_NOINIT +flag is set (using +.Fn ENGINE_set_table_flags ) , +no attempted initialisations will take place, instead the only way for +the state table to return a +.Pf non- Dv NULL +.Vt ENGINE +to the "get_default" query will be if one is expressly set in the table. +For example, +.Fn ENGINE_set_default_RSA +does the same job as +.Fn ENGINE_register_RSA +except that it also sets the state table's cached response for the +"get_default" query. +In the case of abstractions like +.Vt EVP_CIPHER , +where implementations are indexed by +.Fa nid , +these flags and cached-responses are distinct for each +.Fa nid +value. +.Ss Application requirements +This section will explain the basic things an application programmer +should support to make the most useful elements of the +.Nm engine +functionality available to the user. +The first thing to consider is whether the programmer wishes to make +alternative +.Vt ENGINE +modules available to the application and user. +OpenSSL maintains an internal linked list of "visible" +.Vt ENGINE Ns s +from which it has to operate. +At start-up, this list is empty, and in fact if an application does +not call any +.Nm engine +API calls and it uses static +linking against openssl, then the resulting application binary will +not contain any alternative +.Nm engine +code at all. +So the first consideration is whether any/all available +.Vt ENGINE +implementations should be made visible to OpenSSL. +This is controlled by calling the various "load" functions, eg. +.Fn ENGINE_load_builtin_engines +to make all +.Vt ENGINE +implementations bundled with OpenSSL available. +.Pp +Note that +.Fn ENGINE_load_dynamic +is a placeholder and does not enable dynamic engine loading support. +.Pp +Having called any of these functions, +.Vt ENGINE +objects would have been dynamically allocated and populated with +these implementations and linked into OpenSSL's internal linked +list. +.Pp +If no +.Nm engine +API functions are called at all in an application, then there are +no inherent memory leaks to worry about from the +.Nm engine +functionality, however if any +.Vt ENGINE Ns s +are loaded, even if they are never registered or used, it is necessary +to use the +.Fn ENGINE_cleanup +function to correspondingly cleanup before program exit, if the caller +wishes to avoid memory leaks. +This mechanism uses an internal callback registration table so that any +.Nm engine +API functionality that knows it requires cleanup can register its +cleanup details to be called during +.Fn ENGINE_cleanup . +This approach allows +.Fn ENGINE_cleanup +to clean up after any +.Nm engine +functionality at all that your program uses, yet doesn't automatically +create linker dependencies to all possible +.Nm engine +functionality - only the cleanup callbacks required by the functionality +you do use will be required by the linker. +.Pp +The fact that +.Vt ENGINE Ns s +are made visible to OpenSSL (and thus are linked into the program +and loaded into memory at run-time) does not mean they are "registered" +or called into use by OpenSSL automatically - that behaviour is +something for the application to control. +Some applications will want to allow the user to specify exactly which +.Vt ENGINE +they want used if any is to be used at all. +Others may prefer to load all support and have OpenSSL automatically use +at run-time any +.Vt ENGINE +that is able to successfully initialised - ie. to assume that this +corresponds to acceleration hardware attached to the machine or +some such thing. +There are probably numerous other ways in which applications may prefer +to handle things, so we will simply illustrate the consequences as they +apply to a couple of simple cases and leave developers to consider these +and the source code to openssl's builtin utilities as guides. +.Pp +.Em Using a specific ENGINE implementation +.Pp +Here we'll assume an application has been configured by its user or +admin to want to use the "ACME" +.Vt ENGINE +if it is available in the version of OpenSSL the application was +compiled with. +If it is available, it should be used by default for all RSA, DSA, and +symmetric cipher operation, otherwise OpenSSL should use its builtin +software as usual. +The following code illustrates how to approach this: +.Bd -literal +ENGINE *e; +const char *engine_id = "ACME"; +ENGINE_load_builtin_engines(); +e = ENGINE_by_id(engine_id); +if (!e) + /* the engine isn't available */ + return; +if (!ENGINE_init(e)) { + /* the engine couldn't initialise, release 'e' */ + ENGINE_free(e); + return; +} +if (!ENGINE_set_default_RSA(e)) + /* This should only happen when 'e' can't initialise, but the previous + * statement suggests it did. */ + abort(); +ENGINE_set_default_DSA(e); +ENGINE_set_default_ciphers(e); +/* Release the functional reference from ENGINE_init() */ +ENGINE_finish(e); +/* Release the structural reference from ENGINE_by_id() */ +ENGINE_free(e); +.Ed +.Pp +.Em Automatically using builtin ENGINE implementations +.Pp +Here we'll assume we want to load and register all +.Vt ENGINE +implementations bundled with OpenSSL, such that for any cryptographic +algorithm required by OpenSSL - if there is an +.Vt ENGINE +that implements it and can be initialise, it should be used. +The following code illustrates how this can work; +.Bd -literal +/* Load all bundled ENGINEs into memory and make them visible */ +ENGINE_load_builtin_engines(); +/* Register all of them for every algorithm they collectively implement */ +ENGINE_register_all_complete(); +.Ed +.Pp +That's all that's required. +For example, the next time OpenSSL tries to set up an RSA key, any bundled +.Vt ENGINE Ns s +that implement +.Vt RSA_METHOD +will be passed to +.Fn ENGINE_init +and if any of those succeed, that +.Vt ENGINE +will be set as the default for RSA use from then on. +.Ss Advanced configuration support +There is a mechanism supported by the +.Nm engine +framework that allows each +.Vt ENGINE +implementation to define an arbitrary set of configuration +"commands" and expose them to OpenSSL and any applications based on +OpenSSL. +This mechanism is entirely based on the use of name-value pairs +and assumes ASCII input (no unicode or UTF for now!), so it is ideal if +applications want to provide a transparent way for users to provide +arbitrary configuration "directives" directly to such +.Vt ENGINE Ns s. +It is also possible for the application to dynamically interrogate the +loaded +.Vt ENGINE +implementations for the names, descriptions, and input flags of +their available "control commands", providing a more flexible +configuration scheme. +However, if the user is expected to know which +.Vt ENGINE +device he/she is using (in the case of specialised hardware, this +goes without saying) then applications may not need to concern +themselves with discovering the supported control commands and +simply prefer to pass settings into +.Vt ENGINE s +exactly as they are provided by the user. +.Pp +Before illustrating how control commands work, it is worth mentioning +what they are typically used for. +Broadly speaking there are two uses for control commands; the first is +to provide the necessary details to the implementation (which may know +nothing at all specific to the host system) so that it can be +initialised for use. +This could include the path to any driver or config files it needs to +load, required network addresses, smart-card identifiers, passwords to +initialise protected devices, logging information, etc etc. +This class of commands typically needs to be passed to an +.Vt ENGINE +.Sy before +attempting to initialise it, ie. before calling +.Fn ENGINE_init . +The other class of commands consist of settings or operations that tweak +certain behaviour or cause certain operations to take place, and these +commands may work either before or after +.Fn ENGINE_init , +or in some cases both. +.Vt ENGINE +implementations should provide indications of this in the descriptions +attached to builtin control commands and/or in external product +documentation. +.Pp +.Em Issuing control commands to an ENGINE +.Pp +Let's illustrate by example; a function for which the caller supplies +the name of the +.Vt ENGINE +it wishes to use, a table of string-pairs for use before initialisation, +and another table for use after initialisation. +Note that the string-pairs used for control commands consist of a +command "name" followed by the command "parameter" - the parameter +could be +.Dv NULL +in some cases but the name can not. +This function should initialise the +.Vt ENGINE +(issuing the "pre" commands beforehand and the "post" commands +afterwards) and set it as the default for everything except RAND +and then return a boolean success or failure. +.Bd -literal +int +generic_load_engine_fn(const char *engine_id, + const char **pre_cmds, int pre_num, + const char **post_cmds, int post_num) +{ + ENGINE *e = ENGINE_by_id(engine_id); + + if (!e) + return 0; + while (pre_num--) { + if (!ENGINE_ctrl_cmd_string(e, + pre_cmds[0], pre_cmds[1], 0)) { + fprintf(stderr, + "Failed command (%s - %s:%s)\en", + engine_id, pre_cmds[0], + pre_cmds[1] ? pre_cmds[1] : "(NULL)"); + ENGINE_free(e); + return 0; + } + pre_cmds += 2; + } + if (!ENGINE_init(e)) { + fprintf(stderr, "Failed initialisation\en"); + ENGINE_free(e); + return 0; + } + /* + * ENGINE_init() returned a functional reference, + * so free the structural reference from + * ENGINE_by_id(). + */ + ENGINE_free(e); + while (post_num--) { + if (!ENGINE_ctrl_cmd_string(e, + post_cmds[0], post_cmds[1], 0)) { + fprintf(stderr, + "Failed command (%s - %s:%s)\en", + engine_id, post_cmds[0], + post_cmds[1] ? post_cmds[1] : "(NULL)"); + ENGINE_finish(e); + return 0; + } + post_cmds += 2; + } + ENGINE_set_default(e, ENGINE_METHOD_ALL & ~ENGINE_METHOD_RAND); + /* Success */ + return 1; +} +.Ed +.Pp +Note that +.Fn ENGINE_ctrl_cmd_string +accepts a boolean argument that can relax the semantics of the function. +If set to non-zero it will only return failure if the +.Vt ENGINE +supported the given command name but failed while executing it, if the +.Vt ENGINE +doesn't support the command name it will simply return success without +doing anything. +In this case we assume the user is only supplying commands specific to +the given +.Vt ENGINE +so we set this to FALSE. +.Pp +.Em Discovering supported control commands +.Pp +It is possible to discover at run-time the names, numerical-ids, +descriptions and input parameters of the control commands supported by an +.Vt ENGINE +using a structural reference. +Note that some control commands are defined by OpenSSL itself and it +will intercept and handle these control commands on behalf of the +.Vt ENGINE , +ie. the +.Vt ENGINE Ap s +ctrl() handler is not used for the control command. +.In openssl/engine.h +defines an index, +.Dv ENGINE_CMD_BASE , +that all control commands implemented by +.Vt ENGINE Ns s +should be numbered from. +Any command value lower than this symbol is considered a "generic" +command is handled directly by the OpenSSL core routines. +.Pp +It is using these "core" control commands that one can discover the +control commands implemented by a given +.Vt ENGINE , +specifically the commands: +.Bd -literal +#define ENGINE_HAS_CTRL_FUNCTION 10 +#define ENGINE_CTRL_GET_FIRST_CMD_TYPE 11 +#define ENGINE_CTRL_GET_NEXT_CMD_TYPE 12 +#define ENGINE_CTRL_GET_CMD_FROM_NAME 13 +#define ENGINE_CTRL_GET_NAME_LEN_FROM_CMD 14 +#define ENGINE_CTRL_GET_NAME_FROM_CMD 15 +#define ENGINE_CTRL_GET_DESC_LEN_FROM_CMD 16 +#define ENGINE_CTRL_GET_DESC_FROM_CMD 17 +#define ENGINE_CTRL_GET_CMD_FLAGS 18 +.Ed +.Pp +Whilst these commands are automatically processed by the OpenSSL +framework code, they use various properties exposed by each +.Vt ENGINE +to process these queries. +An +.Vt ENGINE +has 3 properties it exposes that can affect how this behaves; +it can supply a ctrl() handler, it can specify +.Dv ENGINE_FLAGS_MANUAL_CMD_CTRL +in the +.Vt ENGINE Ap s +flags, and it can expose an array of control command descriptions. +If an +.Vt ENGINE +specifies the +.Dv ENGINE_FLAGS_MANUAL_CMD_CTRL +flag, then it will simply pass all these "core" control commands +directly to the +.Vt ENGINE Ap s +ctrl() handler (and thus, it must have supplied one), so it is up +to the +.Vt ENGINE +to reply to these "discovery" commands itself. +If that flag is not set, then the OpenSSL framework code will work with +the following rules; +.Bl -tag -width Ds +.It If no ctrl() handler is supplied: +.Dv ENGINE_HAS_CTRL_FUNCTION +returns FALSE (zero), all other commands fail. +.It If a ctrl() handler was supplied but no array of control commands: +.Dv ENGINE_HAS_CTRL_FUNCTION +returns TRUE, all other commands fail. +.It If a ctrl() handler and array of control commands was supplied: +.Dv ENGINE_HAS_CTRL_FUNCTION +returns TRUE, all other commands proceed processing... +.El +.Pp +If the +.Vt ENGINE Ns s +array of control commands is empty, then all other commands will fail. +Otherwise +.Dv ENGINE_CTRL_GET_FIRST_CMD_TYPE +returns the identifier of the first command supported by the +.Vt ENGINE , +.Dv ENGINE_GET_NEXT_CMD_TYPE +takes the identifier of a command supported by the +.Vt ENGINE +and returns the next command identifier or fails if there are no more, +.Dv ENGINE_CMD_FROM_NAME +takes a string name for a command and returns the corresponding +identifier or fails if no such command name exists, and the remaining +commands take a command identifier and return properties of the +corresponding commands. +All except +.Dv ENGINE_CTRL_GET_FLAGS +return the string length of a command name or description, or +populate a supplied character buffer with a copy of the command +name or description. +.Dv ENGINE_CTRL_GET_FLAGS +returns a bitwise-OR'd mask of the following possible values: +.Bd -literal +#define ENGINE_CMD_FLAG_NUMERIC (unsigned int)0x0001 +#define ENGINE_CMD_FLAG_STRING (unsigned int)0x0002 +#define ENGINE_CMD_FLAG_NO_INPUT (unsigned int)0x0004 +#define ENGINE_CMD_FLAG_INTERNAL (unsigned int)0x0008 +.Ed +.Pp +If the +.Dv ENGINE_CMD_FLAG_INTERNAL +flag is set, then any other flags are purely informational to the caller. +This flag will prevent the command being usable for any higher-level +.Vt ENGINE +functions such as +.Fn ENGINE_ctrl_cmd_string . +"INTERNAL" commands are not intended to be exposed to text-based +configuration by applications, administrations, users, etc. +These can support arbitrary operations via +.Fn ENGINE_ctrl , +including passing to and/or from the control commands data of any +arbitrary type. +These commands are supported in the discovery mechanisms simply allow +applications to determine if an +.Vt ENGINE +supports certain specific commands it might want to use (eg. +application "foo" might query various +.Vt ENGINE Ns s +to see if they implement "FOO_GET_VENDOR_LOGO_GIF" - and +.Vt ENGINE +could therefore decide whether or not to support this "foo"-specific +extension). +.Ss Future developments +The +.Nm engine +API and internal architecture is currently being reviewed. +Slated for possible release in 0.9.8 is support for transparent loading +of "dynamic" +.Vt ENGINE Ns s (built as self-contained shared libraries). +This would allow +.Vt ENGINE +implementations to be provided independently of +OpenSSL libraries and/or OpenSSL-based applications, and would also +remove any requirement for applications to explicitly use the "dynamic" +.Vt ENGINE +to bind to shared-library implementations. +.Sh SEE ALSO +.Xr dh 3 , +.Xr dsa 3 , +.Xr rsa 3 diff --git a/src/lib/libcrypto/man/lh_stats.3 b/src/lib/libcrypto/man/lh_stats.3 new file mode 100644 index 0000000000..b56bb81979 --- /dev/null +++ b/src/lib/libcrypto/man/lh_stats.3 @@ -0,0 +1,83 @@ +.Dd $Mdocdate: November 5 2016 $ +.Dt LH_STATS 3 +.Os +.Sh NAME +.Nm lh_stats , +.Nm lh_node_stats , +.Nm lh_node_usage_stats , +.Nm lh_stats_bio , +.Nm lh_node_stats_bio , +.Nm lh_node_usage_stats_bio +.Nd LHASH statistics +.Sh SYNOPSIS +.In openssl/lhash.h +.Ft void +.Fo lh_stats +.Fa "LHASH *table" +.Fa "FILE *out" +.Fc +.Ft void +.Fo lh_node_stats +.Fa "LHASH *table" +.Fa "FILE *out" +.Fc +.Ft void +.Fo lh_node_usage_stats +.Fa "LHASH *table" +.Fa "FILE *out" +.Fc +.Ft void +.Fo lh_stats_bio +.Fa "LHASH *table" +.Fa "BIO *out" +.Fc +.Ft void +.Fo lh_node_stats_bio +.Fa "LHASH *table" +.Fa "BIO *out" +.Fc +.Ft void +.Fo lh_node_usage_stats_bio +.Fa "LHASH *table" +.Fa "BIO *out" +.Fc +.Sh DESCRIPTION +The +.Vt LHASH +structure records statistics about most aspects of accessing the hash +table. +.Pp +.Fn lh_stats +prints out statistics on the size of the hash table, how many entries +are in it, and the number and result of calls to the routines in this +library. +.Pp +.Fn lh_node_stats +prints the number of entries for each 'bucket' in the hash table. +.Pp +.Fn lh_node_usage_stats +prints out a short summary of the state of the hash table. +It prints the 'load' and the 'actual load'. +The load is the average number of data items per 'bucket' in the hash +table. +The 'actual load' is the average number of items per 'bucket', but only +for buckets which contain entries. +So the 'actual load' is the average number of searches that will need to +find an item in the hash table, while the 'load' is the average number +that will be done to record a miss. +.Pp +.Fn lh_stats_bio , +.Fn lh_node_stats_bio , +and +.Fn lh_node_usage_stats_bio +are the same as the above, except that the output goes to a +.Vt BIO . +.Sh RETURN VALUES +These functions do not return values. +.Sh SEE ALSO +.Xr bio 3 , +.Xr lh_new 3 +.Sh HISTORY +These functions are available in all versions of SSLeay and OpenSSL. +.Sh AUTHORS +.An Eric Young -- cgit v1.2.3-55-g6feb