From 53934822ac7acf69dde54a070eacd1c77cf079ff Mon Sep 17 00:00:00 2001 From: Rich Salz Date: Thu, 9 Jun 2016 16:39:19 -0400 Subject: [PATCH] Clean up "generic" intro pod files. Files like dh.pod, etc., mostly duplicated the API-specific pod files. Removed the duplicated content; that often mean the whole file could be removed. Some of the content about internals got moved into README files in the source tree. Some content (e.g., err.pod) got moved into other pod pages. Annotate generic pages, remove dup NAME Reviewed-by: Richard Levitte --- .../bn_internal.pod => crypto/bn/README.pod | 0 crypto/err/README | 44 ++++ doc/crypto/{blowfish.pod => BF_encrypt.pod} | 2 +- doc/crypto/BIO_new.pod | 11 +- doc/crypto/{buffer.pod => BUF_MEM_new.pod} | 0 ...threads.pod => CRYPTO_THREAD_run_once.pod} | 0 doc/crypto/{stack.pod => DEFINE_STACK_OF.pod} | 2 + doc/crypto/{des.pod => DES_random_key.pod} | 0 doc/crypto/DH_meth_new.pod | 3 +- doc/crypto/{ecdsa.pod => ECDSA_SIG_new.pod} | 1 - doc/crypto/{engine.pod => ENGINE_add.pod} | 2 +- doc/crypto/ERR_put_error.pod | 30 +++ doc/crypto/{hmac.pod => HMAC.pod} | 0 doc/crypto/{md5.pod => MD5.pod} | 0 doc/crypto/{mdc2.pod => MDC2_Init.pod} | 0 .../{lhash.pod => OPENSSL_LH_COMPFUNC.pod} | 2 + .../{lh_stats.pod => OPENSSL_LH_stats.pod} | 0 .../{pem.pod => PEM_read_bio_PrivateKey.pod} | 0 doc/crypto/{rc4.pod => RC4_set_key.pod} | 0 doc/crypto/{ripemd.pod => RIPEMD160_init.pod} | 0 doc/crypto/RSA_blinding_on.pod | 4 - doc/crypto/RSA_check_key.pod | 1 - doc/crypto/RSA_generate_key.pod | 4 +- doc/crypto/RSA_meth_new.pod | 2 +- doc/crypto/RSA_new.pod | 2 +- doc/crypto/RSA_print.pod | 2 +- .../{rsa.pod => RSA_private_decrypt.pod} | 54 +---- doc/crypto/RSA_private_encrypt.pod | 2 +- doc/crypto/RSA_public_encrypt.pod | 2 +- doc/crypto/RSA_set_method.pod | 2 +- doc/crypto/RSA_sign.pod | 2 +- doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod | 2 +- doc/crypto/RSA_size.pod | 2 +- doc/crypto/{sha.pod => SHA256_Init.pod} | 0 doc/crypto/{ui.pod => UI_new.pod} | 6 +- doc/crypto/bio.pod | 27 ++- doc/crypto/bn.pod | 197 ----------------- doc/crypto/dh.pod | 69 ------ doc/crypto/dsa.pod | 117 ---------- doc/crypto/ec.pod | 206 ------------------ doc/crypto/err.pod | 205 ----------------- doc/crypto/rand.pod | 90 -------- doc/crypto/x509.pod | 2 + 43 files changed, 133 insertions(+), 964 deletions(-) rename doc/crypto/bn_internal.pod => crypto/bn/README.pod (100%) create mode 100644 crypto/err/README rename doc/crypto/{blowfish.pod => BF_encrypt.pod} (98%) rename doc/crypto/{buffer.pod => BUF_MEM_new.pod} (100%) rename doc/crypto/{threads.pod => CRYPTO_THREAD_run_once.pod} (100%) rename doc/crypto/{stack.pod => DEFINE_STACK_OF.pod} (99%) rename doc/crypto/{des.pod => DES_random_key.pod} (100%) rename doc/crypto/{ecdsa.pod => ECDSA_SIG_new.pod} (99%) rename doc/crypto/{engine.pod => ENGINE_add.pod} (99%) rename doc/crypto/{hmac.pod => HMAC.pod} (100%) rename doc/crypto/{md5.pod => MD5.pod} (100%) rename doc/crypto/{mdc2.pod => MDC2_Init.pod} (100%) rename doc/crypto/{lhash.pod => OPENSSL_LH_COMPFUNC.pod} (99%) rename doc/crypto/{lh_stats.pod => OPENSSL_LH_stats.pod} (100%) rename doc/crypto/{pem.pod => PEM_read_bio_PrivateKey.pod} (100%) rename doc/crypto/{rc4.pod => RC4_set_key.pod} (100%) rename doc/crypto/{ripemd.pod => RIPEMD160_init.pod} (100%) rename doc/crypto/{rsa.pod => RSA_private_decrypt.pod} (59%) rename doc/crypto/{sha.pod => SHA256_Init.pod} (100%) rename doc/crypto/{ui.pod => UI_new.pod} (98%) delete mode 100644 doc/crypto/bn.pod delete mode 100644 doc/crypto/dh.pod delete mode 100644 doc/crypto/dsa.pod delete mode 100644 doc/crypto/ec.pod delete mode 100644 doc/crypto/err.pod delete mode 100644 doc/crypto/rand.pod diff --git a/doc/crypto/bn_internal.pod b/crypto/bn/README.pod similarity index 100% rename from doc/crypto/bn_internal.pod rename to crypto/bn/README.pod diff --git a/crypto/err/README b/crypto/err/README new file mode 100644 index 0000000000..6d2ce0cd0e --- /dev/null +++ b/crypto/err/README @@ -0,0 +1,44 @@ +Adding new libraries +-------------------- + +When adding a new sub-library to OpenSSL, assign it a library number +ERR_LIB_XXX, define a macro XXXerr() (both in err.h), add its +name to ERR_str_libraries[] (in crypto/err/err.c), and add +ERR_load_XXX_strings() to the ERR_load_crypto_strings() function +(in crypto/err/err_all.c). Finally, add an entry: + + L XXX xxx.h xxx_err.c + +to crypto/err/openssl.ec, and add xxx_err.c to the Makefile. +Running make errors will then generate a file xxx_err.c, and +add all error codes used in the library to xxx.h. + +Additionally the library include file must have a certain form. +Typically it will initially look like this: + + #ifndef HEADER_XXX_H + #define HEADER_XXX_H + + #ifdef __cplusplus + extern "C" { + #endif + + /* Include files */ + + #include + #include + + /* Macros, structures and function prototypes */ + + + /* BEGIN ERROR CODES */ + +The BEGIN ERROR CODES sequence is used by the error code +generation script as the point to place new error codes, any text +after this point will be overwritten when make errors is run. +The closing #endif etc will be automatically added by the script. + +The generated C error code file xxx_err.c will load the header +files stdio.h, openssl/err.h and openssl/xxx.h so the +header file must load any additional header files containing any +definitions it uses. diff --git a/doc/crypto/blowfish.pod b/doc/crypto/BF_encrypt.pod similarity index 98% rename from doc/crypto/blowfish.pod rename to doc/crypto/BF_encrypt.pod index 182cb87ecc..6d8cf1fdb4 100644 --- a/doc/crypto/blowfish.pod +++ b/doc/crypto/BF_encrypt.pod @@ -2,7 +2,7 @@ =head1 NAME -blowfish, BF_set_key, BF_encrypt, BF_decrypt, BF_ecb_encrypt, BF_cbc_encrypt, +BF_set_key, BF_encrypt, BF_decrypt, BF_ecb_encrypt, BF_cbc_encrypt, BF_cfb64_encrypt, BF_ofb64_encrypt, BF_options - Blowfish encryption =head1 SYNOPSIS diff --git a/doc/crypto/BIO_new.pod b/doc/crypto/BIO_new.pod index ca8bb7e946..8e42e650a2 100644 --- a/doc/crypto/BIO_new.pod +++ b/doc/crypto/BIO_new.pod @@ -45,21 +45,12 @@ BIO_free_all() and BIO_vfree() do not return values. =head1 NOTES -Some BIOs (such as memory BIOs) can be used immediately after calling -BIO_new(). Others (such as file BIOs) need some additional initialization, -and frequently a utility function exists to create and initialize such BIOs. - If BIO_free() is called on a BIO chain it will only free one BIO resulting in a memory leak. -Calling BIO_free_all() a single BIO has the same effect as calling BIO_free() +Calling BIO_free_all() on a single BIO has the same effect as calling BIO_free() on it other than the discarded return value. -Normally the B argument is supplied by a function which returns a -pointer to a BIO_METHOD. There is a naming convention for such functions: -a source/sink BIO is normally called BIO_s_*() and a filter BIO -BIO_f_*(); - =head1 EXAMPLE Create a memory BIO: diff --git a/doc/crypto/buffer.pod b/doc/crypto/BUF_MEM_new.pod similarity index 100% rename from doc/crypto/buffer.pod rename to doc/crypto/BUF_MEM_new.pod diff --git a/doc/crypto/threads.pod b/doc/crypto/CRYPTO_THREAD_run_once.pod similarity index 100% rename from doc/crypto/threads.pod rename to doc/crypto/CRYPTO_THREAD_run_once.pod diff --git a/doc/crypto/stack.pod b/doc/crypto/DEFINE_STACK_OF.pod similarity index 99% rename from doc/crypto/stack.pod rename to doc/crypto/DEFINE_STACK_OF.pod index 1defff0328..d32fb2177a 100644 --- a/doc/crypto/stack.pod +++ b/doc/crypto/DEFINE_STACK_OF.pod @@ -10,6 +10,8 @@ sk_TYPE_insert, sk_TYPE_set, sk_TYPE_find, sk_TYPE_find_ex, sk_TYPE_sort, sk_TYPE_is_sorted, sk_TYPE_dup, sk_TYPE_deep_copy, sk_TYPE_set_cmp_func - stack container +=for comment generic + =head1 SYNOPSIS #include diff --git a/doc/crypto/des.pod b/doc/crypto/DES_random_key.pod similarity index 100% rename from doc/crypto/des.pod rename to doc/crypto/DES_random_key.pod diff --git a/doc/crypto/DH_meth_new.pod b/doc/crypto/DH_meth_new.pod index 33e8db574f..bcf559215f 100644 --- a/doc/crypto/DH_meth_new.pod +++ b/doc/crypto/DH_meth_new.pod @@ -49,8 +49,7 @@ DH_meth_set_generate_params - Routines to build up DH methods The B type is a structure used for the provision of custom DH implementations. It provides a set of of functions used by OpenSSL for the -implementation of the various DH capabilities. See the L page for more -information. +implementation of the various DH capabilities. DH_meth_new() creates a new B structure. It should be given a unique B and a set of B. The B should be a NULL terminated diff --git a/doc/crypto/ecdsa.pod b/doc/crypto/ECDSA_SIG_new.pod similarity index 99% rename from doc/crypto/ecdsa.pod rename to doc/crypto/ECDSA_SIG_new.pod index c8392657be..691989074d 100644 --- a/doc/crypto/ecdsa.pod +++ b/doc/crypto/ECDSA_SIG_new.pod @@ -182,7 +182,6 @@ ANSI X9.62, US Federal Information Processing Standard FIPS 186-2 =head1 SEE ALSO L, -L, L, L diff --git a/doc/crypto/engine.pod b/doc/crypto/ENGINE_add.pod similarity index 99% rename from doc/crypto/engine.pod rename to doc/crypto/ENGINE_add.pod index df12d59983..a934d96ec4 100644 --- a/doc/crypto/engine.pod +++ b/doc/crypto/ENGINE_add.pod @@ -555,7 +555,7 @@ extension). =head1 SEE ALSO -L, L, L, L, L +L, L, L, L, L =head1 HISTORY diff --git a/doc/crypto/ERR_put_error.pod b/doc/crypto/ERR_put_error.pod index 9b02976774..9ddf534bbe 100644 --- a/doc/crypto/ERR_put_error.pod +++ b/doc/crypto/ERR_put_error.pod @@ -27,6 +27,36 @@ L can be used to register error strings so that the application can a generate human-readable error messages for the error code. +=head2 Reporting errors + +Each sub-library has a specific macro XXXerr() that is used to report +errors. Its first argument is a function code B, the second +argument is a reason code B. Function codes are derived +from the function names; reason codes consist of textual error +descriptions. For example, the function ssl3_read_bytes() reports a +"handshake failure" as follows: + + SSLerr(SSL_F_SSL3_READ_BYTES, SSL_R_SSL_HANDSHAKE_FAILURE); + +Function and reason codes should consist of upper case characters, +numbers and underscores only. The error file generation script translates +function codes into function names by looking in the header files +for an appropriate function name, if none is found it just uses +the capitalized form such as "SSL3_READ_BYTES" in the above example. + +The trailing section of a reason code (after the "_R_") is translated +into lower case and underscores changed to spaces. + +When you are using new function or reason codes, run B. +The necessary B<#define>s will then automatically be added to the +sub-library's header file. + +Although a library will normally report errors using its own specific +XXXerr macro, another library's macro can be used. This is normally +only done when a library wants to include ASN1 code which must use +the ASN1err() macro. + + =head1 RETURN VALUES ERR_put_error() and ERR_add_error_data() return diff --git a/doc/crypto/hmac.pod b/doc/crypto/HMAC.pod similarity index 100% rename from doc/crypto/hmac.pod rename to doc/crypto/HMAC.pod diff --git a/doc/crypto/md5.pod b/doc/crypto/MD5.pod similarity index 100% rename from doc/crypto/md5.pod rename to doc/crypto/MD5.pod diff --git a/doc/crypto/mdc2.pod b/doc/crypto/MDC2_Init.pod similarity index 100% rename from doc/crypto/mdc2.pod rename to doc/crypto/MDC2_Init.pod diff --git a/doc/crypto/lhash.pod b/doc/crypto/OPENSSL_LH_COMPFUNC.pod similarity index 99% rename from doc/crypto/lhash.pod rename to doc/crypto/OPENSSL_LH_COMPFUNC.pod index 959e2d6804..372f0d952c 100644 --- a/doc/crypto/lhash.pod +++ b/doc/crypto/OPENSSL_LH_COMPFUNC.pod @@ -9,6 +9,8 @@ lh_TYPE_new, lh_TYPE_free, lh_TYPE_insert, lh_TYPE_delete, lh_TYPE_retrieve, lh_TYPE_doall, lh_TYPE_doall_arg, lh_TYPE_error - dynamic hash table +=for comment generic + =head1 SYNOPSIS #include diff --git a/doc/crypto/lh_stats.pod b/doc/crypto/OPENSSL_LH_stats.pod similarity index 100% rename from doc/crypto/lh_stats.pod rename to doc/crypto/OPENSSL_LH_stats.pod diff --git a/doc/crypto/pem.pod b/doc/crypto/PEM_read_bio_PrivateKey.pod similarity index 100% rename from doc/crypto/pem.pod rename to doc/crypto/PEM_read_bio_PrivateKey.pod diff --git a/doc/crypto/rc4.pod b/doc/crypto/RC4_set_key.pod similarity index 100% rename from doc/crypto/rc4.pod rename to doc/crypto/RC4_set_key.pod diff --git a/doc/crypto/ripemd.pod b/doc/crypto/RIPEMD160_init.pod similarity index 100% rename from doc/crypto/ripemd.pod rename to doc/crypto/RIPEMD160_init.pod diff --git a/doc/crypto/RSA_blinding_on.pod b/doc/crypto/RSA_blinding_on.pod index 7258b08718..33d49d3720 100644 --- a/doc/crypto/RSA_blinding_on.pod +++ b/doc/crypto/RSA_blinding_on.pod @@ -32,10 +32,6 @@ RSA_blinding_on() returns 1 on success, and 0 if an error occurred. RSA_blinding_off() returns no value. -=head1 SEE ALSO - -L, L - =head1 COPYRIGHT Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. diff --git a/doc/crypto/RSA_check_key.pod b/doc/crypto/RSA_check_key.pod index 69df86473d..a8b1002fef 100644 --- a/doc/crypto/RSA_check_key.pod +++ b/doc/crypto/RSA_check_key.pod @@ -66,7 +66,6 @@ provide their own verifiers. =head1 SEE ALSO L, -L, L =head1 HISTORY diff --git a/doc/crypto/RSA_generate_key.pod b/doc/crypto/RSA_generate_key.pod index aec321affe..a8fab52cb9 100644 --- a/doc/crypto/RSA_generate_key.pod +++ b/doc/crypto/RSA_generate_key.pod @@ -72,8 +72,8 @@ RSA_generate_key() goes into an infinite loop for illegal input values. =head1 SEE ALSO -L, L, L, -L, L +L, L, +L, L =head1 COPYRIGHT diff --git a/doc/crypto/RSA_meth_new.pod b/doc/crypto/RSA_meth_new.pod index c5a78fcc65..19743d1240 100644 --- a/doc/crypto/RSA_meth_new.pod +++ b/doc/crypto/RSA_meth_new.pod @@ -215,7 +215,7 @@ success or 0 on failure. =head1 SEE ALSO -L, L, L, L, +L, L, L, L, L, L =head1 HISTORY diff --git a/doc/crypto/RSA_new.pod b/doc/crypto/RSA_new.pod index c3441caf6c..3317920741 100644 --- a/doc/crypto/RSA_new.pod +++ b/doc/crypto/RSA_new.pod @@ -31,7 +31,7 @@ RSA_free() returns no value. =head1 SEE ALSO -L, L, +L, L, L diff --git a/doc/crypto/RSA_print.pod b/doc/crypto/RSA_print.pod index fb5bcb70c2..1367478f93 100644 --- a/doc/crypto/RSA_print.pod +++ b/doc/crypto/RSA_print.pod @@ -38,7 +38,7 @@ These functions return 1 on success, 0 on error. =head1 SEE ALSO -L, L, L, L +L =head1 COPYRIGHT diff --git a/doc/crypto/rsa.pod b/doc/crypto/RSA_private_decrypt.pod similarity index 59% rename from doc/crypto/rsa.pod rename to doc/crypto/RSA_private_decrypt.pod index 4f7de72d2c..fa6c405364 100644 --- a/doc/crypto/rsa.pod +++ b/doc/crypto/RSA_private_decrypt.pod @@ -2,17 +2,19 @@ =head1 NAME -rsa - RSA public key cryptosystem +RSA_private_decrypt, +RSA_private_encrypt, +RSA_public_decrypt, +RSA_sign, +RSA_verify, +RSA_sign_ASN1_OCTET_STRING, +RSA_verify_ASN1_OCTET_STRING +- RSA public key cryptosystem =head1 SYNOPSIS #include - RSA * RSA_new(void); - void RSA_free(RSA *rsa); - - int RSA_public_encrypt(int flen, unsigned char *from, - unsigned char *to, RSA *rsa, int padding); int RSA_private_decrypt(int flen, unsigned char *from, unsigned char *to, RSA *rsa, int padding); int RSA_private_encrypt(int flen, unsigned char *from, @@ -25,26 +27,6 @@ rsa - RSA public key cryptosystem int RSA_verify(int type, unsigned char *m, unsigned int m_len, unsigned char *sigbuf, unsigned int siglen, RSA *rsa); - RSA *RSA_generate_key(int num, unsigned long e, - void (*callback)(int,int,void *), void *cb_arg); - - int RSA_check_key(RSA *rsa); - - int RSA_blinding_on(RSA *rsa, BN_CTX *ctx); - void RSA_blinding_off(RSA *rsa); - - void RSA_set_default_method(const RSA_METHOD *meth); - const RSA_METHOD *RSA_get_default_method(void); - int RSA_set_method(RSA *rsa, const RSA_METHOD *meth); - const RSA_METHOD *RSA_get_method(const RSA *rsa); - RSA_METHOD *RSA_PKCS1_OpenSSL(void); - RSA_METHOD *RSA_null_method(void); - int RSA_flags(const RSA *rsa); - RSA *RSA_new_method(ENGINE *engine); - - int RSA_print(BIO *bp, RSA *x, int offset); - int RSA_print_fp(FILE *fp, RSA *x, int offset); - int RSA_sign_ASN1_OCTET_STRING(int dummy, unsigned char *m, unsigned int m_len, unsigned char *sigret, unsigned int *siglen, RSA *rsa); @@ -57,16 +39,7 @@ rsa - RSA public key cryptosystem These functions implement RSA public key encryption and signatures as defined in PKCS #1 v2.0 [RFC 2437]. -The B structure consists of the BIGNUM components B, B, -B, B

, B, B, B and B, which represent public -as well as private RSA keys. - -In public keys, the private exponent B and the related secret -values B

, B, B, B and B are B. - -B

, B, B, B and B may be B in private -keys, but the RSA operations are much faster when these values are -available. +The B structure represents public and private RSA keys. Note that RSA keys may use non-standard B implementations, either directly or by the use of B modules. In some cases (eg. an @@ -80,22 +53,17 @@ modify keys. SSL, PKCS #1 v2.0 -=head1 PATENTS - -RSA was covered by a US patent which expired in September 2000. - =head1 SEE ALSO -L, L, L, L, +L, L, L, L, L, L, L L, -L, L, +L, L, L, L, L, L, L, -L, L, L diff --git a/doc/crypto/RSA_private_encrypt.pod b/doc/crypto/RSA_private_encrypt.pod index 4b307a0c61..7870371936 100644 --- a/doc/crypto/RSA_private_encrypt.pod +++ b/doc/crypto/RSA_private_encrypt.pod @@ -59,7 +59,7 @@ obtained by L. =head1 SEE ALSO -L, L, +L, L, L =head1 COPYRIGHT diff --git a/doc/crypto/RSA_public_encrypt.pod b/doc/crypto/RSA_public_encrypt.pod index c371dac42a..2f78c27484 100644 --- a/doc/crypto/RSA_public_encrypt.pod +++ b/doc/crypto/RSA_public_encrypt.pod @@ -73,7 +73,7 @@ SSL, PKCS #1 v2.0 =head1 SEE ALSO -L, L, L, +L, L, L =head1 COPYRIGHT diff --git a/doc/crypto/RSA_set_method.pod b/doc/crypto/RSA_set_method.pod index f8695ed852..7e7d27cf93 100644 --- a/doc/crypto/RSA_set_method.pod +++ b/doc/crypto/RSA_set_method.pod @@ -166,7 +166,7 @@ not currently exist). =head1 SEE ALSO -L, L +L =head1 COPYRIGHT diff --git a/doc/crypto/RSA_sign.pod b/doc/crypto/RSA_sign.pod index 4c6f14992f..64418a5653 100644 --- a/doc/crypto/RSA_sign.pod +++ b/doc/crypto/RSA_sign.pod @@ -50,7 +50,7 @@ SSL, PKCS #1 v2.0 =head1 SEE ALSO L, -L, L, +L, L =head1 COPYRIGHT diff --git a/doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod b/doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod index 499bf43260..16303c9f90 100644 --- a/doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod +++ b/doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod @@ -48,7 +48,7 @@ These functions serve no recognizable purpose. =head1 SEE ALSO L, -L, L, L, +L, L, L =head1 COPYRIGHT diff --git a/doc/crypto/RSA_size.pod b/doc/crypto/RSA_size.pod index 4ae29da737..eb6e481361 100644 --- a/doc/crypto/RSA_size.pod +++ b/doc/crypto/RSA_size.pod @@ -28,7 +28,7 @@ The size. =head1 SEE ALSO -L, L +L =head1 HISTORY diff --git a/doc/crypto/sha.pod b/doc/crypto/SHA256_Init.pod similarity index 100% rename from doc/crypto/sha.pod rename to doc/crypto/SHA256_Init.pod diff --git a/doc/crypto/ui.pod b/doc/crypto/UI_new.pod similarity index 98% rename from doc/crypto/ui.pod rename to doc/crypto/UI_new.pod index a9412659aa..78981c1478 100644 --- a/doc/crypto/ui.pod +++ b/doc/crypto/UI_new.pod @@ -8,7 +8,7 @@ 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 +UI_set_method, UI_OpenSSL, ERR_load_UI_strings - user interface =head1 SYNOPSIS @@ -179,10 +179,6 @@ 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, L - =head1 COPYRIGHT Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. diff --git a/doc/crypto/bio.pod b/doc/crypto/bio.pod index cf44a746ba..5a305c6a29 100644 --- a/doc/crypto/bio.pod +++ b/doc/crypto/bio.pod @@ -1,8 +1,10 @@ =pod +=for comment openssl_manual_section 7 + =head1 NAME -bio - I/O abstraction +bio - Basic I/O abstraction =head1 SYNOPSIS @@ -34,6 +36,28 @@ BIO and one or more filter BIOs. Data read from or written to the first BIO then traverses the chain to the end (normally a source/sink BIO). + +Some BIOs (such as memory BIOs) can be used immediately after calling +BIO_new(). Others (such as file BIOs) need some additional initialization, +and frequently a utility function exists to create and initialize such BIOs. + +If BIO_free() is called on a BIO chain it will only free one BIO resulting +in a memory leak. + +Calling BIO_free_all() a single BIO has the same effect as calling BIO_free() +on it other than the discarded return value. + +Normally the B argument is supplied by a function which returns a +pointer to a BIO_METHOD. There is a naming convention for such functions: +a source/sink BIO is normally called BIO_s_*() and a filter BIO +BIO_f_*(); + +=head1 EXAMPLE + +Create a memory BIO: + + BIO *mem = BIO_new(BIO_s_mem()); + =head1 SEE ALSO L, @@ -61,3 +85,4 @@ in the file LICENSE in the source distribution or at L. =cut + diff --git a/doc/crypto/bn.pod b/doc/crypto/bn.pod deleted file mode 100644 index 6d87d11e0f..0000000000 --- a/doc/crypto/bn.pod +++ /dev/null @@ -1,197 +0,0 @@ -=pod - -=head1 NAME - -bn - multiprecision integer arithmetics - -=head1 SYNOPSIS - - #include - - BIGNUM *BN_new(void); - void BN_free(BIGNUM *a); - void BN_clear(BIGNUM *a); - void BN_clear_free(BIGNUM *a); - - BN_CTX *BN_CTX_new(void); - BN_CTX *BN_CTX_secure_new(void); - void BN_CTX_free(BN_CTX *c); - - BIGNUM *BN_copy(BIGNUM *a, const BIGNUM *b); - BIGNUM *BN_dup(const BIGNUM *a); - - BIGNUM *BN_swap(BIGNUM *a, BIGNUM *b); - - int BN_num_bytes(const BIGNUM *a); - int BN_num_bits(const BIGNUM *a); - int BN_num_bits_word(BN_ULONG w); - - void BN_set_negative(BIGNUM *a, int n); - int BN_is_negative(const BIGNUM *a); - - int BN_add(BIGNUM *r, const BIGNUM *a, const BIGNUM *b); - int BN_sub(BIGNUM *r, const BIGNUM *a, const BIGNUM *b); - int BN_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); - int BN_sqr(BIGNUM *r, BIGNUM *a, BN_CTX *ctx); - int BN_div(BIGNUM *dv, BIGNUM *rem, const BIGNUM *a, const BIGNUM *d, - BN_CTX *ctx); - int BN_mod(BIGNUM *rem, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx); - int BN_nnmod(BIGNUM *rem, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx); - int BN_mod_add(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m, - BN_CTX *ctx); - int BN_mod_sub(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m, - BN_CTX *ctx); - int BN_mod_mul(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m, - BN_CTX *ctx); - int BN_mod_sqr(BIGNUM *ret, BIGNUM *a, const BIGNUM *m, BN_CTX *ctx); - int BN_exp(BIGNUM *r, BIGNUM *a, BIGNUM *p, BN_CTX *ctx); - int BN_mod_exp(BIGNUM *r, BIGNUM *a, const BIGNUM *p, - const BIGNUM *m, BN_CTX *ctx); - int BN_gcd(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); - - int BN_add_word(BIGNUM *a, BN_ULONG w); - int BN_sub_word(BIGNUM *a, BN_ULONG w); - int BN_mul_word(BIGNUM *a, BN_ULONG w); - BN_ULONG BN_div_word(BIGNUM *a, BN_ULONG w); - BN_ULONG BN_mod_word(const BIGNUM *a, BN_ULONG w); - - int BN_cmp(BIGNUM *a, BIGNUM *b); - int BN_ucmp(BIGNUM *a, BIGNUM *b); - int BN_is_zero(BIGNUM *a); - int BN_is_one(BIGNUM *a); - int BN_is_word(BIGNUM *a, BN_ULONG w); - int BN_is_odd(BIGNUM *a); - - int BN_zero(BIGNUM *a); - int BN_one(BIGNUM *a); - const BIGNUM *BN_value_one(void); - int BN_set_word(BIGNUM *a, unsigned long w); - unsigned long BN_get_word(BIGNUM *a); - - int BN_rand(BIGNUM *rnd, int bits, int top, int bottom); - int BN_pseudo_rand(BIGNUM *rnd, int bits, int top, int bottom); - int BN_rand_range(BIGNUM *rnd, BIGNUM *range); - int BN_pseudo_rand_range(BIGNUM *rnd, BIGNUM *range); - - int BN_generate_prime_ex(BIGNUM *ret,int bits,int safe, const BIGNUM *add, - const BIGNUM *rem, BN_GENCB *cb); - - int BN_is_prime_ex(const BIGNUM *p,int nchecks, BN_CTX *ctx, BN_GENCB *cb); - - int BN_is_prime_fasttest_ex(const BIGNUM *p,int nchecks, BN_CTX *ctx, - int do_trial_division, BN_GENCB *cb); - - int BN_GENCB_call(BN_GENCB *cb, int a, int b); - BN_GENCB *BN_GENCB_new(void); - void BN_GENCB_free(BN_GENCB *cb); - void BN_GENCB_set_old(BN_GENCB *gencb, void (*callback)(int, int, void *), void *cb_arg); - void BN_GENCB_set(BN_GENCB *gencb, int (*callback)(int, int, BN_GENCB *), void *cb_arg); - void *BN_GENCB_get_arg(BN_GENCB *cb); - - int BN_set_bit(BIGNUM *a, int n); - int BN_clear_bit(BIGNUM *a, int n); - int BN_is_bit_set(const BIGNUM *a, int n); - int BN_mask_bits(BIGNUM *a, int n); - int BN_lshift(BIGNUM *r, const BIGNUM *a, int n); - int BN_lshift1(BIGNUM *r, BIGNUM *a); - int BN_rshift(BIGNUM *r, BIGNUM *a, int n); - int BN_rshift1(BIGNUM *r, BIGNUM *a); - - int BN_bn2bin(const BIGNUM *a, unsigned char *to); - BIGNUM *BN_bin2bn(const unsigned char *s, int len, BIGNUM *ret); - char *BN_bn2hex(const BIGNUM *a); - char *BN_bn2dec(const BIGNUM *a); - int BN_hex2bn(BIGNUM **a, const char *str); - int BN_dec2bn(BIGNUM **a, const char *str); - int BN_print(BIO *fp, const BIGNUM *a); - int BN_print_fp(FILE *fp, const BIGNUM *a); - int BN_bn2mpi(const BIGNUM *a, unsigned char *to); - BIGNUM *BN_mpi2bn(unsigned char *s, int len, BIGNUM *ret); - - BIGNUM *BN_mod_inverse(BIGNUM *r, BIGNUM *a, const BIGNUM *n, - BN_CTX *ctx); - - BN_RECP_CTX *BN_RECP_CTX_new(void); - void BN_RECP_CTX_free(BN_RECP_CTX *recp); - int BN_RECP_CTX_set(BN_RECP_CTX *recp, const BIGNUM *m, BN_CTX *ctx); - int BN_mod_mul_reciprocal(BIGNUM *r, BIGNUM *a, BIGNUM *b, - BN_RECP_CTX *recp, BN_CTX *ctx); - - BN_MONT_CTX *BN_MONT_CTX_new(void); - void BN_MONT_CTX_free(BN_MONT_CTX *mont); - int BN_MONT_CTX_set(BN_MONT_CTX *mont, const BIGNUM *m, BN_CTX *ctx); - BN_MONT_CTX *BN_MONT_CTX_copy(BN_MONT_CTX *to, BN_MONT_CTX *from); - int BN_mod_mul_montgomery(BIGNUM *r, BIGNUM *a, BIGNUM *b, - BN_MONT_CTX *mont, BN_CTX *ctx); - int BN_from_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont, - BN_CTX *ctx); - int BN_to_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont, - BN_CTX *ctx); - - BN_BLINDING *BN_BLINDING_new(const BIGNUM *A, const BIGNUM *Ai, - BIGNUM *mod); - void BN_BLINDING_free(BN_BLINDING *b); - int BN_BLINDING_update(BN_BLINDING *b,BN_CTX *ctx); - int BN_BLINDING_convert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx); - int BN_BLINDING_invert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx); - int BN_BLINDING_convert_ex(BIGNUM *n, BIGNUM *r, BN_BLINDING *b, - BN_CTX *ctx); - int BN_BLINDING_invert_ex(BIGNUM *n,const BIGNUM *r,BN_BLINDING *b, - BN_CTX *ctx); - unsigned long BN_BLINDING_get_thread_id(const BN_BLINDING *); - void BN_BLINDING_set_thread_id(BN_BLINDING *, unsigned long); - unsigned long BN_BLINDING_get_flags(const BN_BLINDING *); - void BN_BLINDING_set_flags(BN_BLINDING *, unsigned long); - BN_BLINDING *BN_BLINDING_create_param(BN_BLINDING *b, - const BIGNUM *e, BIGNUM *m, BN_CTX *ctx, - int (*bn_mod_exp)(BIGNUM *r, const BIGNUM *a, const BIGNUM *p, - const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx), - BN_MONT_CTX *m_ctx); - -=head1 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. - -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. - -The basic object in this library is a B. It is used to hold a -single large integer. This type should be considered opaque and fields -should not be modified or accessed directly. - -The creation of B objects is described in L; -L describes most of the arithmetic operations. -Comparison is described in L; L -describes certain assignments, L the generation of -random numbers, L deals with prime -numbers and L with bit operations. The conversion -of Bs to external formats is described in L. - -=head1 SEE ALSO - -L, -L, L, L, L, -L, L, -L, L, L, -L, L, -L, L, L, -L, L, -L, L, -L, -L, -L - -=head1 COPYRIGHT - -Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the OpenSSL license (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L. - -=cut diff --git a/doc/crypto/dh.pod b/doc/crypto/dh.pod deleted file mode 100644 index 95b5fab81e..0000000000 --- a/doc/crypto/dh.pod +++ /dev/null @@ -1,69 +0,0 @@ -=pod - -=head1 NAME - -dh - Diffie-Hellman key agreement - -=head1 SYNOPSIS - - #include - - DH *DH_new(void); - void DH_free(DH *dh); - - DH *DH_generate_parameters(int prime_len, int generator, - void (*callback)(int, int, void *), void *cb_arg); - int DH_check(const DH *dh, int *codes); - - int DH_generate_key(DH *dh); - int DH_compute_key(unsigned char *key, BIGNUM *pub_key, DH *dh); - - void DH_set_default_method(const DH_METHOD *meth); - const DH_METHOD *DH_get_default_method(void); - int DH_set_method(DH *dh, const DH_METHOD *meth); - DH *DH_new_method(ENGINE *engine); - const DH_METHOD *DH_OpenSSL(void); - - DH *d2i_DHparams(DH **a, unsigned char **pp, long length); - int i2d_DHparams(const DH *a, unsigned char **pp); - - int DHparams_print_fp(FILE *fp, const DH *x); - int DHparams_print(BIO *bp, const DH *x); - -=head1 DESCRIPTION - -These functions implement the Diffie-Hellman key agreement protocol. -The generation of shared DH parameters is described in -L; L describes how -to perform a key agreement. - -The B structure consists of several BIGNUM components. The prime B

, the -generate B, the Private key B and the public key B. -Optionally there may also be an additional parameter B. - -Note that DH keys may use non-standard B implementations, -either directly or by the use of B modules. In some cases (eg. an -ENGINE providing support for hardware-embedded keys), these BIGNUM values -will not be used by the implementation or may be used for alternative data -storage. - -=head1 SEE ALSO - -L, L, L, L, -L, L, L, -L, L, -L, -L, -L, L, L, L, -L - -=head1 COPYRIGHT - -Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the OpenSSL license (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L. - -=cut diff --git a/doc/crypto/dsa.pod b/doc/crypto/dsa.pod deleted file mode 100644 index c803caf1c7..0000000000 --- a/doc/crypto/dsa.pod +++ /dev/null @@ -1,117 +0,0 @@ -=pod - -=head1 NAME - -dsa - Digital Signature Algorithm - -=head1 SYNOPSIS - - #include - - DSA * DSA_new(void); - void DSA_free(DSA *dsa); - - int DSA_size(const DSA *dsa); - - DSA * DSA_generate_parameters(int bits, unsigned char *seed, - int seed_len, int *counter_ret, unsigned long *h_ret, - void (*callback)(int, int, void *), void *cb_arg); - - DH * DSA_dup_DH(const DSA *r); - - int DSA_generate_key(DSA *dsa); - - int DSA_sign(int dummy, const unsigned char *dgst, int len, - unsigned char *sigret, unsigned int *siglen, DSA *dsa); - int DSA_sign_setup(DSA *dsa, BN_CTX *ctx, BIGNUM **kinvp, - BIGNUM **rp); - int DSA_verify(int dummy, const unsigned char *dgst, int len, - const unsigned char *sigbuf, int siglen, DSA *dsa); - - void DSA_set_default_method(const DSA_METHOD *meth); - const DSA_METHOD *DSA_get_default_method(void); - int DSA_set_method(DSA *dsa, const DSA_METHOD *meth); - DSA *DSA_new_method(ENGINE *engine); - const DSA_METHOD *DSA_OpenSSL(void); - - DSA_SIG *DSA_SIG_new(void); - void DSA_SIG_free(DSA_SIG *a); - int i2d_DSA_SIG(const DSA_SIG *a, unsigned char **pp); - DSA_SIG *d2i_DSA_SIG(DSA_SIG **v, unsigned char **pp, long length); - - DSA_SIG *DSA_do_sign(const unsigned char *dgst, int dlen, DSA *dsa); - int DSA_do_verify(const unsigned char *dgst, int dgst_len, - DSA_SIG *sig, DSA *dsa); - - DSA * d2i_DSAPublicKey(DSA **a, unsigned char **pp, long length); - DSA * d2i_DSAPrivateKey(DSA **a, unsigned char **pp, long length); - DSA * d2i_DSAparams(DSA **a, unsigned char **pp, long length); - int i2d_DSAPublicKey(const DSA *a, unsigned char **pp); - int i2d_DSAPrivateKey(const DSA *a, unsigned char **pp); - int i2d_DSAparams(const DSA *a,unsigned char **pp); - - int DSAparams_print(BIO *bp, const DSA *x); - int DSAparams_print_fp(FILE *fp, const DSA *x); - int DSA_print(BIO *bp, const DSA *x, int off); - int DSA_print_fp(FILE *bp, const DSA *x, int off); - -=head1 DESCRIPTION - -These functions implement the Digital Signature Algorithm (DSA). The -generation of shared DSA parameters is described in -L; -L describes how to -generate a signature key. Signature generation and verification are -described in L. - -The B structure consists of several BIGNUM components. - - 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; - -In public keys, B is NULL. - -Note that DSA keys may use non-standard B implementations, -either directly or by the use of B modules. In some cases (eg. an -ENGINE providing support for hardware-embedded keys), these 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 DSA -structure elements directly and instead use API functions to query or -modify keys. - -=head1 CONFORMING TO - -US Federal Information Processing Standard FIPS 186 (Digital Signature -Standard, DSS), ANSI X9.30 - -=head1 SEE ALSO - -L, L, L, L, -L, L, L, -L, -L, -L, -L, -L, -L, L, -L, -L - -=head1 COPYRIGHT - -Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the OpenSSL license (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L. - -=cut diff --git a/doc/crypto/ec.pod b/doc/crypto/ec.pod deleted file mode 100644 index cb073d7d84..0000000000 --- a/doc/crypto/ec.pod +++ /dev/null @@ -1,206 +0,0 @@ -=pod - -=head1 NAME - -ec - Elliptic Curve functions - -=head1 SYNOPSIS - - #include - - const EC_METHOD *EC_GFp_simple_method(void); - const EC_METHOD *EC_GFp_mont_method(void); - const EC_METHOD *EC_GFp_nist_method(void); - const EC_METHOD *EC_GFp_nistp224_method(void); - const EC_METHOD *EC_GFp_nistp256_method(void); - const EC_METHOD *EC_GFp_nistp521_method(void); - - const EC_METHOD *EC_GF2m_simple_method(void); - - EC_GROUP *EC_GROUP_new(const EC_METHOD *meth); - void EC_GROUP_free(EC_GROUP *group); - void EC_GROUP_clear_free(EC_GROUP *group); - int EC_GROUP_copy(EC_GROUP *dst, const EC_GROUP *src); - EC_GROUP *EC_GROUP_dup(const EC_GROUP *src); - const EC_METHOD *EC_GROUP_method_of(const EC_GROUP *group); - int EC_METHOD_get_field_type(const EC_METHOD *meth); - int EC_GROUP_set_generator(EC_GROUP *group, const EC_POINT *generator, const BIGNUM *order, const BIGNUM *cofactor); - const EC_POINT *EC_GROUP_get0_generator(const EC_GROUP *group); - int EC_GROUP_get_order(const EC_GROUP *group, BIGNUM *order, BN_CTX *ctx); - int EC_GROUP_get_cofactor(const EC_GROUP *group, BIGNUM *cofactor, BN_CTX *ctx); - void EC_GROUP_set_curve_name(EC_GROUP *group, int nid); - int EC_GROUP_get_curve_name(const EC_GROUP *group); - void EC_GROUP_set_asn1_flag(EC_GROUP *group, int flag); - int EC_GROUP_get_asn1_flag(const EC_GROUP *group); - void EC_GROUP_set_point_conversion_form(EC_GROUP *group, point_conversion_form_t form); - point_conversion_form_t EC_GROUP_get_point_conversion_form(const EC_GROUP *); - unsigned char *EC_GROUP_get0_seed(const EC_GROUP *x); - size_t EC_GROUP_get_seed_len(const EC_GROUP *); - size_t EC_GROUP_set_seed(EC_GROUP *, const unsigned char *, size_t len); - int EC_GROUP_set_curve_GFp(EC_GROUP *group, const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); - int EC_GROUP_get_curve_GFp(const EC_GROUP *group, BIGNUM *p, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); - int EC_GROUP_set_curve_GF2m(EC_GROUP *group, const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); - int EC_GROUP_get_curve_GF2m(const EC_GROUP *group, BIGNUM *p, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); - int EC_GROUP_get_degree(const EC_GROUP *group); - int EC_GROUP_check(const EC_GROUP *group, BN_CTX *ctx); - int EC_GROUP_check_discriminant(const EC_GROUP *group, BN_CTX *ctx); - int EC_GROUP_cmp(const EC_GROUP *a, const EC_GROUP *b, BN_CTX *ctx); - EC_GROUP *EC_GROUP_new_curve_GFp(const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); - EC_GROUP *EC_GROUP_new_curve_GF2m(const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); - EC_GROUP *EC_GROUP_new_by_curve_name(int nid); - - size_t EC_get_builtin_curves(EC_builtin_curve *r, size_t nitems); - - EC_POINT *EC_POINT_new(const EC_GROUP *group); - void EC_POINT_free(EC_POINT *point); - void EC_POINT_clear_free(EC_POINT *point); - int EC_POINT_copy(EC_POINT *dst, const EC_POINT *src); - EC_POINT *EC_POINT_dup(const EC_POINT *src, const EC_GROUP *group); - const EC_METHOD *EC_POINT_method_of(const EC_POINT *point); - int EC_POINT_set_to_infinity(const EC_GROUP *group, EC_POINT *point); - int EC_POINT_set_Jprojective_coordinates_GFp(const EC_GROUP *group, EC_POINT *p, - const BIGNUM *x, const BIGNUM *y, const BIGNUM *z, BN_CTX *ctx); - int EC_POINT_get_Jprojective_coordinates_GFp(const EC_GROUP *group, - const EC_POINT *p, BIGNUM *x, BIGNUM *y, BIGNUM *z, BN_CTX *ctx); - int EC_POINT_set_affine_coordinates_GFp(const EC_GROUP *group, EC_POINT *p, - const BIGNUM *x, const BIGNUM *y, BN_CTX *ctx); - int EC_POINT_get_affine_coordinates_GFp(const EC_GROUP *group, - const EC_POINT *p, BIGNUM *x, BIGNUM *y, BN_CTX *ctx); - int EC_POINT_set_compressed_coordinates_GFp(const EC_GROUP *group, EC_POINT *p, - const BIGNUM *x, int y_bit, BN_CTX *ctx); - int EC_POINT_set_affine_coordinates_GF2m(const EC_GROUP *group, EC_POINT *p, - const BIGNUM *x, const BIGNUM *y, BN_CTX *ctx); - int EC_POINT_get_affine_coordinates_GF2m(const EC_GROUP *group, - const EC_POINT *p, BIGNUM *x, BIGNUM *y, BN_CTX *ctx); - int EC_POINT_set_compressed_coordinates_GF2m(const EC_GROUP *group, EC_POINT *p, - const BIGNUM *x, int y_bit, BN_CTX *ctx); - size_t EC_POINT_point2oct(const EC_GROUP *group, const EC_POINT *p, - point_conversion_form_t form, - unsigned char *buf, size_t len, BN_CTX *ctx); - int EC_POINT_oct2point(const EC_GROUP *group, EC_POINT *p, - const unsigned char *buf, size_t len, BN_CTX *ctx); - BIGNUM *EC_POINT_point2bn(const EC_GROUP *, const EC_POINT *, - point_conversion_form_t form, BIGNUM *, BN_CTX *); - EC_POINT *EC_POINT_bn2point(const EC_GROUP *, const BIGNUM *, - EC_POINT *, BN_CTX *); - char *EC_POINT_point2hex(const EC_GROUP *, const EC_POINT *, - point_conversion_form_t form, BN_CTX *); - EC_POINT *EC_POINT_hex2point(const EC_GROUP *, const char *, - EC_POINT *, BN_CTX *); - - int EC_POINT_add(const EC_GROUP *group, EC_POINT *r, const EC_POINT *a, const EC_POINT *b, BN_CTX *ctx); - int EC_POINT_dbl(const EC_GROUP *group, EC_POINT *r, const EC_POINT *a, BN_CTX *ctx); - int EC_POINT_invert(const EC_GROUP *group, EC_POINT *a, BN_CTX *ctx); - int EC_POINT_is_at_infinity(const EC_GROUP *group, const EC_POINT *p); - int EC_POINT_is_on_curve(const EC_GROUP *group, const EC_POINT *point, BN_CTX *ctx); - int EC_POINT_cmp(const EC_GROUP *group, const EC_POINT *a, const EC_POINT *b, BN_CTX *ctx); - int EC_POINT_make_affine(const EC_GROUP *group, EC_POINT *point, BN_CTX *ctx); - int EC_POINTs_make_affine(const EC_GROUP *group, size_t num, EC_POINT *points[], BN_CTX *ctx); - int EC_POINTs_mul(const EC_GROUP *group, EC_POINT *r, const BIGNUM *n, size_t num, const EC_POINT *p[], const BIGNUM *m[], BN_CTX *ctx); - int EC_POINT_mul(const EC_GROUP *group, EC_POINT *r, const BIGNUM *n, const EC_POINT *q, const BIGNUM *m, BN_CTX *ctx); - int EC_GROUP_precompute_mult(EC_GROUP *group, BN_CTX *ctx); - int EC_GROUP_have_precompute_mult(const EC_GROUP *group); - - int EC_GROUP_get_basis_type(const EC_GROUP *); - int EC_GROUP_get_trinomial_basis(const EC_GROUP *, unsigned int *k); - int EC_GROUP_get_pentanomial_basis(const EC_GROUP *, unsigned int *k1, - unsigned int *k2, unsigned int *k3); - EC_GROUP *d2i_ECPKParameters(EC_GROUP **, const unsigned char **in, long len); - int i2d_ECPKParameters(const EC_GROUP *, unsigned char **out); - #define d2i_ECPKParameters_bio(bp,x) ASN1_d2i_bio_of(EC_GROUP,NULL,d2i_ECPKParameters,bp,x) - #define i2d_ECPKParameters_bio(bp,x) ASN1_i2d_bio_of_const(EC_GROUP,i2d_ECPKParameters,bp,x) - #define d2i_ECPKParameters_fp(fp,x) (EC_GROUP *)ASN1_d2i_fp(NULL, \ - (char *(*)())d2i_ECPKParameters,(fp),(unsigned char **)(x)) - #define i2d_ECPKParameters_fp(fp,x) ASN1_i2d_fp(i2d_ECPKParameters,(fp), \ - (unsigned char *)(x)) - int ECPKParameters_print(BIO *bp, const EC_GROUP *x, int off); - int ECPKParameters_print_fp(FILE *fp, const EC_GROUP *x, int off); - - EC_KEY *EC_KEY_new(void); - int EC_KEY_get_flags(const EC_KEY *key); - void EC_KEY_set_flags(EC_KEY *key, int flags); - void EC_KEY_clear_flags(EC_KEY *key, int flags); - EC_KEY *EC_KEY_new_by_curve_name(int nid); - void EC_KEY_free(EC_KEY *key); - EC_KEY *EC_KEY_copy(EC_KEY *dst, const EC_KEY *src); - EC_KEY *EC_KEY_dup(const EC_KEY *src); - int EC_KEY_up_ref(EC_KEY *key); - const EC_GROUP *EC_KEY_get0_group(const EC_KEY *key); - int EC_KEY_set_group(EC_KEY *key, const EC_GROUP *group); - const BIGNUM *EC_KEY_get0_private_key(const EC_KEY *key); - int EC_KEY_set_private_key(EC_KEY *key, const BIGNUM *prv); - const EC_POINT *EC_KEY_get0_public_key(const EC_KEY *key); - int EC_KEY_set_public_key(EC_KEY *key, const EC_POINT *pub); - unsigned EC_KEY_get_enc_flags(const EC_KEY *key); - void EC_KEY_set_enc_flags(EC_KEY *eckey, unsigned int flags); - point_conversion_form_t EC_KEY_get_conv_form(const EC_KEY *key); - void EC_KEY_set_conv_form(EC_KEY *eckey, point_conversion_form_t cform); - void EC_KEY_set_asn1_flag(EC_KEY *eckey, int asn1_flag); - int EC_KEY_precompute_mult(EC_KEY *key, BN_CTX *ctx); - int EC_KEY_generate_key(EC_KEY *key); - int EC_KEY_check_key(const EC_KEY *key); - int EC_KEY_set_public_key_affine_coordinates(EC_KEY *key, BIGNUM *x, BIGNUM *y); - - EC_KEY *d2i_ECPrivateKey(EC_KEY **key, const unsigned char **in, long len); - int i2d_ECPrivateKey(EC_KEY *key, unsigned char **out); - - EC_KEY *d2i_ECParameters(EC_KEY **key, const unsigned char **in, long len); - int i2d_ECParameters(EC_KEY *key, unsigned char **out); - - EC_KEY *o2i_ECPublicKey(EC_KEY **key, const unsigned char **in, long len); - int i2o_ECPublicKey(EC_KEY *key, unsigned char **out); - int ECParameters_print(BIO *bp, const EC_KEY *key); - int EC_KEY_print(BIO *bp, const EC_KEY *key, int off); - int ECParameters_print_fp(FILE *fp, const EC_KEY *key); - int EC_KEY_print_fp(FILE *fp, const EC_KEY *key, int off); - #define ECParameters_dup(x) ASN1_dup_of(EC_KEY,i2d_ECParameters,d2i_ECParameters,x) - #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) - const EC_KEY_METHOD *EC_KEY_get_method(const EC_KEY *key); - int EC_KEY_set_method(EC_KEY *key, const EC_KEY_METHOD *meth); - -=head1 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: - -y^2 = x^3 + ax + b - -An B structure is used to represent the definition of an elliptic curve. Points on a curve are stored using an -B structure. An B is used to hold a private/public key pair, where a private key is simply a BIGNUM and a -public key is a point on a curve (represented by an B). - -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 B structure. - -The creation and destruction of B objects is described in L. Functions for -manipulating B objects are described in L. - -Functions for creating, destroying and manipulating B objects are explained in L, -whilst functions for performing mathematical operations and tests on B are covered in L. - -For working with private and public keys refer to L. Implementations are covered in -L. - -For information on encoding and decoding curve parameters to and from ASN1 see L. - -=head1 SEE ALSO - -L, L, L, -L, L, L, -L, L - - -=head1 COPYRIGHT - -Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the OpenSSL license (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L. - -=cut diff --git a/doc/crypto/err.pod b/doc/crypto/err.pod deleted file mode 100644 index b57798e63b..0000000000 --- a/doc/crypto/err.pod +++ /dev/null @@ -1,205 +0,0 @@ -=pod - -=head1 NAME - -err - error codes - -=head1 SYNOPSIS - - #include - - unsigned long ERR_get_error(void); - unsigned long ERR_peek_error(void); - unsigned long ERR_get_error_line(const char **file, int *line); - unsigned long ERR_peek_error_line(const char **file, int *line); - unsigned long ERR_get_error_line_data(const char **file, int *line, - const char **data, int *flags); - unsigned long ERR_peek_error_line_data(const char **file, int *line, - const char **data, int *flags); - - int ERR_GET_LIB(unsigned long e); - int ERR_GET_FUNC(unsigned long e); - int ERR_GET_REASON(unsigned long e); - - void ERR_clear_error(void); - - char *ERR_error_string(unsigned long e, char *buf); - const char *ERR_lib_error_string(unsigned long e); - const char *ERR_func_error_string(unsigned long e); - const char *ERR_reason_error_string(unsigned long e); - - void ERR_print_errors(BIO *bp); - void ERR_print_errors_fp(FILE *fp); - - void ERR_load_crypto_strings(void); - - void ERR_put_error(int lib, int func, int reason, const char *file, - int line); - void ERR_add_error_data(int num, ...); - - void ERR_load_strings(int lib,ERR_STRING_DATA str[]); - unsigned long ERR_PACK(int lib, int func, int reason); - int ERR_get_next_error_library(void); - -Deprecated: - - #if OPENSSL_API_COMPAT < 0x10000000L - void ERR_remove_state(unsigned long pid); - #endif - - #if OPENSSL_API_COMPAT < 0x10100000L - void ERR_remove_thread_state(void *); - #endif - - #if OPENSSL_API_COMPAT < 0x10100000L - void ERR_free_strings(void) - #endif - - -=head1 DESCRIPTION - -When a call to the OpenSSL library fails, this is usually signaled -by the return value, and an error code is stored in an error queue -associated with the current thread. The B library provides -functions to obtain these error codes and textual error messages. - -The L manpage describes how to -access error codes. - -Error codes contain information about where the error occurred, and -what went wrong. L describes how to -extract this information. A method to obtain human-readable error -messages is described in L. - -L can be used to clear the -error queue. - -=head1 ADDING NEW ERROR CODES TO OPENSSL - -See L if you want to record error codes in the -OpenSSL error system from within your application. - -The remainder of this section is of interest only if you want to add -new error codes to OpenSSL or add error codes from external libraries. - -=head2 Reporting errors - -Each sub-library has a specific macro XXXerr() that is used to report -errors. Its first argument is a function code B, the second -argument is a reason code B. Function codes are derived -from the function names; reason codes consist of textual error -descriptions. For example, the function ssl3_read_bytes() reports a -"handshake failure" as follows: - - SSLerr(SSL_F_SSL3_READ_BYTES, SSL_R_SSL_HANDSHAKE_FAILURE); - -Function and reason codes should consist of upper case characters, -numbers and underscores only. The error file generation script translates -function codes into function names by looking in the header files -for an appropriate function name, if none is found it just uses -the capitalized form such as "SSL3_READ_BYTES" in the above example. - -The trailing section of a reason code (after the "_R_") is translated -into lower case and underscores changed to spaces. - -When you are using new function or reason codes, run B. -The necessary B<#define>s will then automatically be added to the -sub-library's header file. - -Although a library will normally report errors using its own specific -XXXerr macro, another library's macro can be used. This is normally -only done when a library wants to include ASN1 code which must use -the ASN1err() macro. - -=head2 Adding new libraries - -When adding a new sub-library to OpenSSL, assign it a library number -B, define a macro XXXerr() (both in B), add its -name to B (in B), and add -C to the ERR_load_crypto_strings() function -(in B). Finally, add an entry - - L XXX xxx.h xxx_err.c - -to B, and add B to the Makefile. -Running B will then generate a file B, and -add all error codes used in the library to B. - -Additionally the library include file must have a certain form. -Typically it will initially look like this: - - #ifndef HEADER_XXX_H - #define HEADER_XXX_H - - #ifdef __cplusplus - extern "C" { - #endif - - /* Include files */ - - #include - #include - - /* Macros, structures and function prototypes */ - - - /* BEGIN ERROR CODES */ - -The B sequence is used by the error code -generation script as the point to place new error codes, any text -after this point will be overwritten when B is run. -The closing #endif etc will be automatically added by the script. - -The generated C error code file B will load the header -files B, B and B so the -header file must load any additional header files containing any -definitions it uses. - -=head1 USING ERROR CODES IN EXTERNAL LIBRARIES - -It is also possible to use OpenSSL's error code scheme in external -libraries. The library needs to load its own codes and call the OpenSSL -error code insertion script B explicitly to add codes to -the header file and generate the C error code file. This will normally -be done if the external library needs to generate new ASN1 structures -but it can also be used to add more general purpose error code handling. - -=head1 INTERNALS - -The error queues are stored in a thread-local storage with one B -entry for each thread. ERR_get_state() returns the current thread's -B. An B can hold up to B error -codes. When more error codes are added, the old ones are overwritten, -on the assumption that the most recent errors are most important. - -Error strings are also stored in a hash table that can be obtained -by calling ERR_get_string_table(void). - -=head1 SEE ALSO - -L, -L, -L, -L, -L, -L, -L, -L, -L, -L - -=head1 HISTORY - -The ERR_load_crypto_strings() function was deprecated in OpenSSL 1.1.0 by -OPENSSL_init_crypto(). - -=head1 COPYRIGHT - -Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the OpenSSL license (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L. - -=cut diff --git a/doc/crypto/rand.pod b/doc/crypto/rand.pod deleted file mode 100644 index 76ec0b6b73..0000000000 --- a/doc/crypto/rand.pod +++ /dev/null @@ -1,90 +0,0 @@ -=pod - -=head1 NAME - -rand - pseudo-random number generator - -=head1 SYNOPSIS - - #include - - int RAND_set_rand_engine(ENGINE *engine); - - int RAND_bytes(unsigned char *buf, int num); - int RAND_pseudo_bytes(unsigned char *buf, int num); - - void RAND_seed(const void *buf, int num); - void RAND_add(const void *buf, int num, int entropy); - int RAND_status(void); - - int RAND_load_file(const char *file, long max_bytes); - int RAND_write_file(const char *file); - const char *RAND_file_name(char *file, size_t num); - - int RAND_egd(const char *path); - - void RAND_set_rand_method(const RAND_METHOD *meth); - const RAND_METHOD *RAND_get_rand_method(void); - RAND_METHOD *RAND_OpenSSL(void); - -Deprecated: - - #if OPENSSL_API_COMPAT < 0x10100000L - void RAND_cleanup(void) - #endif - -/* For Win32 only */ - - #if OPENSSL_API_COMPAT < 0x10100000L - void RAND_screen(void); - int RAND_event(UINT, WPARAM, LPARAM); - #endif - - -=head1 DESCRIPTION - -Since the introduction of the ENGINE API, the recommended way of controlling -default implementations is by using the ENGINE API functions. The default -B, as set by RAND_set_rand_method() and returned by -RAND_get_rand_method(), is only used if no ENGINE has been set as the default -"rand" implementation. Hence, these two functions are no longer the recommended -way to control defaults. - -If an alternative B implementation is being used (either set -directly or as provided by an ENGINE module), then it is entirely responsible -for the generation and management of a cryptographically secure PRNG stream. The -mechanisms described below relate solely to the software PRNG implementation -built in to OpenSSL and used by default. - -These functions implement a cryptographically secure pseudo-random -number generator (PRNG). It is used by other library functions for -example to generate random keys, and applications can use it when they -need randomness. - -A cryptographic PRNG must be seeded with unpredictable data such as -mouse movements or keys pressed at random by the user. This is -described in L. Its state can be saved in a seed file -(see L) to avoid having to go through the -seeding process whenever the application is started. - -L describes how to obtain random data from the -PRNG. - -=head1 SEE ALSO - -L, L, -L, L, -L, -L, -L - -=head1 COPYRIGHT - -Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the OpenSSL license (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L. - -=cut diff --git a/doc/crypto/x509.pod b/doc/crypto/x509.pod index a8969deea1..8319b15270 100644 --- a/doc/crypto/x509.pod +++ b/doc/crypto/x509.pod @@ -1,5 +1,7 @@ =pod +=for comment openssl_manual_section:7 + =head1 NAME x509 - X.509 certificate handling -- 2.25.1