wbrawner/openssl
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Clean up "generic" intro pod files.

Browse source 
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 <levitte@openssl.org>
This commit is contained in:
Rich Salz 2016-06-09 16:39:19 -04:00
parent 12ce9ea25d
commit 53934822ac
43 changed files with 133 additions and 964 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

0
doc/crypto/bn_internal.pod → crypto/bn/README.pod
View file

44
crypto/err/README Normal file
View file

@ -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 <openssl/bio.h>
#include <openssl/x509.h>
/* 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.

2
doc/crypto/blowfish.pod → doc/crypto/BF_encrypt.pod
View file

@ -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

11
doc/crypto/BIO_new.pod
View file

@ -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<type> 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:

0
doc/crypto/buffer.pod → doc/crypto/BUF_MEM_new.pod
View file

0
doc/crypto/threads.pod → doc/crypto/CRYPTO_THREAD_run_once.pod
View file

2
doc/crypto/stack.pod → doc/crypto/DEFINE_STACK_OF.pod
View file

@ -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 <openssl/safestack.h>

0
doc/crypto/des.pod → doc/crypto/DES_random_key.pod
View file

3
doc/crypto/DH_meth_new.pod
View file

@ -49,8 +49,7 @@ DH_meth_set_generate_params - Routines to build up DH methods
The B<DH_METHOD> 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<dh(3)> page for more
information.
implementation of the various DH capabilities.
DH_meth_new() creates a new B<DH_METHOD> structure. It should be given a
unique B<name> and a set of B<flags>. The B<name> should be a NULL terminated

1
doc/crypto/ecdsa.pod → doc/crypto/ECDSA_SIG_new.pod
View file

@ -182,7 +182,6 @@ ANSI X9.62, US Federal Information Processing Standard FIPS 186-2
=head1 SEE ALSO
L<dsa(3)>,
L<rsa(3)>,
L<EVP_DigestSignInit(3)>,
L<EVP_DigestVerifyInit(3)>

2
doc/crypto/engine.pod → doc/crypto/ENGINE_add.pod
View file

@ -555,7 +555,7 @@ extension).
=head1 SEE ALSO
L<OPENSSL_init_crypto(3)>, L<rsa(3)>, L<dsa(3)>, L<dh(3)>, L<rand(3)>
L<OPENSSL_init_crypto(3)>, L<RSA_new_method(3)>, L<dsa(3)>, L<dh(3)>, L<rand(3)>
=head1 HISTORY

30
doc/crypto/ERR_put_error.pod
View file

@ -27,6 +27,36 @@ L<ERR_load_strings(3)> 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<XXX_F_...>, the second
argument is a reason code B<XXX_R_...>. 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<make errors>.
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

0
doc/crypto/hmac.pod → doc/crypto/HMAC.pod
View file

0
doc/crypto/md5.pod → doc/crypto/MD5.pod
View file

0
doc/crypto/mdc2.pod → doc/crypto/MDC2_Init.pod
View file

2
doc/crypto/lhash.pod → doc/crypto/OPENSSL_LH_COMPFUNC.pod
View file

@ -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 <openssl/lhash.h>

0
doc/crypto/lh_stats.pod → doc/crypto/OPENSSL_LH_stats.pod
View file

0
doc/crypto/pem.pod → doc/crypto/PEM_read_bio_PrivateKey.pod
View file

0
doc/crypto/rc4.pod → doc/crypto/RC4_set_key.pod
View file

0
doc/crypto/ripemd.pod → doc/crypto/RIPEMD160_init.pod
View file

4
doc/crypto/RSA_blinding_on.pod
View file

@ -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<rsa(3)>, L<rand(3)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.

1
doc/crypto/RSA_check_key.pod
View file

@ -66,7 +66,6 @@ provide their own verifiers.
=head1 SEE ALSO
L<BN_is_prime_ex(3)>,
L<rsa(3)>,
L<ERR_get_error(3)>
=head1 HISTORY

4
doc/crypto/RSA_generate_key.pod
View file

@ -72,8 +72,8 @@ RSA_generate_key() goes into an infinite loop for illegal input values.
=head1 SEE ALSO
L<ERR_get_error(3)>, L<rand(3)>, L<rsa(3)>,
L<RSA_free(3)>, L<BN_generate_prime(3)>
L<ERR_get_error(3)>, L<rand(3)>,
L<RSA_generate_key(3)>, L<BN_generate_prime(3)>
=head1 COPYRIGHT

2
doc/crypto/RSA_meth_new.pod
View file

@ -215,7 +215,7 @@ success or 0 on failure.
=head1 SEE ALSO
L<rsa(3)>, L<RSA_new(3)>, L<RSA_generate_key(3)>, L<RSA_sign(3)>,
L<RSA_new(3)>, L<RSA_generate_key(3)>, L<RSA_sign(3)>,
L<RSA_set_method(3)>, L<RSA_size(3)>, L<RSA_get0_key(3)>
=head1 HISTORY

2
doc/crypto/RSA_new.pod
View file

@ -31,7 +31,7 @@ RSA_free() returns no value.
=head1 SEE ALSO
L<ERR_get_error(3)>, L<rsa(3)>,
L<ERR_get_error(3)>,
L<RSA_generate_key(3)>,
L<RSA_new_method(3)>

2
doc/crypto/RSA_print.pod
View file

@ -38,7 +38,7 @@ These functions return 1 on success, 0 on error.
=head1 SEE ALSO
L<dh(3)>, L<dsa(3)>, L<rsa(3)>, L<BN_bn2bin(3)>
L<BN_bn2bin(3)>
=head1 COPYRIGHT

54
doc/crypto/rsa.pod → doc/crypto/RSA_private_decrypt.pod
View file

@ -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 <openssl/rsa.h>
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<RSA> structure consists of the BIGNUM components B<n>, B<e>,
B<d>, B<p>, B<q>, B<dmp1>, B<dmq1> and B<iqmp>, which represent public
as well as private RSA keys.
In public keys, the private exponent B<d> and the related secret
values B<p>, B<q>, B<dmp1>, B<dmq1> and B<iqmp> are B<NULL>.
B<p>, B<q>, B<dmp1>, B<dmq1> and B<iqmp> may be B<NULL> in private
keys, but the RSA operations are much faster when these values are
available.
The B<RSA> structure represents public and private RSA keys.
Note that RSA keys may use non-standard B<RSA_METHOD> implementations,
either directly or by the use of B<ENGINE> 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<rsa(1)>, L<bn(3)>, L<dsa(3)>, L<dh(3)>,
L<bn(3)>, L<dsa(3)>, L<dh(3)>,
L<rand(3)>, L<engine(3)>, L<RSA_new(3)>, L<RSA_set0_key(3)>
L<RSA_public_encrypt(3)>,
L<RSA_sign(3)>, L<RSA_size(3)>,
L<RSA_size(3)>,
L<RSA_generate_key(3)>,
L<RSA_check_key(3)>,
L<RSA_blinding_on(3)>,
L<RSA_set_method(3)>, L<RSA_print(3)>,
L<RSA_get_ex_new_index(3)>,
L<RSA_private_encrypt(3)>,
L<RSA_sign_ASN1_OCTET_STRING(3)>,
L<RSA_padding_add_PKCS1_type_1(3)>

2
doc/crypto/RSA_private_encrypt.pod
View file

@ -59,7 +59,7 @@ obtained by L<ERR_get_error(3)>.
=head1 SEE ALSO
L<ERR_get_error(3)>, L<rsa(3)>,
L<ERR_get_error(3)>,
L<RSA_sign(3)>, L<RSA_verify(3)>
=head1 COPYRIGHT

2
doc/crypto/RSA_public_encrypt.pod
View file

@ -73,7 +73,7 @@ SSL, PKCS #1 v2.0
=head1 SEE ALSO
L<ERR_get_error(3)>, L<rand(3)>, L<rsa(3)>,
L<ERR_get_error(3)>, L<rand(3)>,
L<RSA_size(3)>
=head1 COPYRIGHT

2
doc/crypto/RSA_set_method.pod
View file

@ -166,7 +166,7 @@ not currently exist).
=head1 SEE ALSO
L<rsa(3)>, L<RSA_new(3)>
L<RSA_new(3)>
=head1 COPYRIGHT

2
doc/crypto/RSA_sign.pod
View file

@ -50,7 +50,7 @@ SSL, PKCS #1 v2.0
=head1 SEE ALSO
L<ERR_get_error(3)>,
L<rsa(3)>, L<RSA_private_encrypt(3)>,
L<RSA_private_encrypt(3)>,
L<RSA_public_decrypt(3)>
=head1 COPYRIGHT

2
doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod
View file

@ -48,7 +48,7 @@ These functions serve no recognizable purpose.
=head1 SEE ALSO
L<ERR_get_error(3)>,
L<rand(3)>, L<rsa(3)>, L<RSA_sign(3)>,
L<rand(3)>, L<RSA_sign(3)>,
L<RSA_verify(3)>
=head1 COPYRIGHT

2
doc/crypto/RSA_size.pod
View file

@ -28,7 +28,7 @@ The size.
=head1 SEE ALSO
L<rsa(3)>, L<BN_num_bits(3)>
L<BN_num_bits(3)>
=head1 HISTORY

0
doc/crypto/sha.pod → doc/crypto/SHA256_Init.pod
View file

6
doc/crypto/ui.pod → doc/crypto/UI_new.pod
View file

@ -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<ui_create(3)>, L<ui_compat(3)>
=head1 COPYRIGHT
Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.

27
doc/crypto/bio.pod
View file

@ -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<type> 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<BIO_ctrl(3)>,
@ -61,3 +85,4 @@ in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

197
doc/crypto/bn.pod
View file

@ -1,197 +0,0 @@
=pod
=head1 NAME
bn - multiprecision integer arithmetics
=head1 SYNOPSIS
#include <openssl/bn.h>
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<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.
The creation of B<BIGNUM> objects is described in L<BN_new(3)>;
L<BN_add(3)> describes most of the arithmetic operations.
Comparison is described in L<BN_cmp(3)>; L<BN_zero(3)>
describes certain assignments, L<BN_rand(3)> the generation of
random numbers, L<BN_generate_prime(3)> deals with prime
numbers and L<BN_set_bit(3)> with bit operations. The conversion
of B<BIGNUM>s to external formats is described in L<BN_bn2bin(3)>.
=head1 SEE ALSO
L<bn_internal(3)>,
L<dh(3)>, L<err(3)>, L<rand(3)>, L<rsa(3)>,
L<BN_new(3)>, L<BN_CTX_new(3)>,
L<BN_copy(3)>, L<BN_swap(3)>, L<BN_num_bytes(3)>,
L<BN_add(3)>, L<BN_add_word(3)>,
L<BN_cmp(3)>, L<BN_zero(3)>, L<BN_rand(3)>,
L<BN_generate_prime(3)>, L<BN_set_bit(3)>,
L<BN_bn2bin(3)>, L<BN_mod_inverse(3)>,
L<BN_mod_mul_reciprocal(3)>,
L<BN_mod_mul_montgomery(3)>,
L<BN_BLINDING_new(3)>
=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<https://www.openssl.org/source/license.html>.
=cut

69
doc/crypto/dh.pod
View file

@ -1,69 +0,0 @@
=pod
=head1 NAME
dh - Diffie-Hellman key agreement
=head1 SYNOPSIS
#include <openssl/dh.h>
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<DH_generate_parameters(3)>; L<DH_generate_key(3)> describes how
to perform a key agreement.
The B<DH> structure consists of several BIGNUM components. The prime B<p>, the
generate B<g>, the Private key B<priv_key> and the public key B<pub_key>.
Optionally there may also be an additional parameter B<q>.
Note that DH keys may use non-standard B<DH_METHOD> implementations,
either directly or by the use of B<ENGINE> 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<dhparam(1)>, L<bn(3)>, L<dsa(3)>, L<err(3)>,
L<rand(3)>, L<rsa(3)>, L<engine(3)>,
L<DH_set_method(3)>, L<DH_new(3)>,
L<DH_get_ex_new_index(3)>,
L<DH_generate_parameters(3)>,
L<DH_compute_key(3)>, L<DH_get0_pqg(3)>, L<DH_meth_new(3)>, L<d2i_DHparams(3)>,
L<RSA_print(3)>
=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<https://www.openssl.org/source/license.html>.
=cut

117
doc/crypto/dsa.pod
View file

@ -1,117 +0,0 @@
=pod
=head1 NAME
dsa - Digital Signature Algorithm
=head1 SYNOPSIS
#include <openssl/dsa.h>
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<DSA_generate_parameters(3)>;
L<DSA_generate_key(3)> describes how to
generate a signature key. Signature generation and verification are
described in L<DSA_sign(3)>.
The B<DSA> 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<priv_key> is NULL.
Note that DSA keys may use non-standard B<DSA_METHOD> implementations,
either directly or by the use of B<ENGINE> 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<bn(3)>, L<dh(3)>, L<err(3)>, L<rand(3)>,
L<rsa(3)>, L<sha(3)>, L<engine(3)>,
L<DSA_new(3)>,
L<DSA_size(3)>,
L<DSA_generate_parameters(3)>,
L<DSA_dup_DH(3)>,
L<DSA_generate_key(3)>,
L<DSA_sign(3)>, L<DSA_set_method(3)>,
L<DSA_get_ex_new_index(3)>,
L<RSA_print(3)>
=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<https://www.openssl.org/source/license.html>.
=cut

206
doc/crypto/ec.pod
View file

@ -1,206 +0,0 @@
=pod
=head1 NAME
ec - Elliptic Curve functions
=head1 SYNOPSIS
#include <openssl/ec.h>
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<EC_GROUP> structure is used to represent the definition of an elliptic curve. Points on a curve are stored using an
B<EC_POINT> structure. An B<EC_KEY> 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<EC_POINT>).
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<EC_METHOD> structure.
The creation and destruction of B<EC_GROUP> objects is described in L<EC_GROUP_new(3)>. Functions for
manipulating B<EC_GROUP> objects are described in L<EC_GROUP_copy(3)>.
Functions for creating, destroying and manipulating B<EC_POINT> objects are explained in L<EC_POINT_new(3)>,
whilst functions for performing mathematical operations and tests on B<EC_POINTs> are covered in L<EC_POINT_add(3)>.
For working with private and public keys refer to L<EC_KEY_new(3)>. Implementations are covered in
L<EC_GFp_simple_method(3)>.
For information on encoding and decoding curve parameters to and from ASN1 see L<d2i_ECPKParameters(3)>.
=head1 SEE ALSO
L<crypto(3)>, L<EC_GROUP_new(3)>, L<EC_GROUP_copy(3)>,
L<EC_POINT_new(3)>, L<EC_POINT_add(3)>, L<EC_KEY_new(3)>,
L<EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)>
=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<https://www.openssl.org/source/license.html>.
=cut

205
doc/crypto/err.pod
View file

@ -1,205 +0,0 @@
=pod
=head1 NAME
err - error codes
=head1 SYNOPSIS
#include <openssl/err.h>
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<err> library provides
functions to obtain these error codes and textual error messages.
The L<ERR_get_error(3)> manpage describes how to
access error codes.
Error codes contain information about where the error occurred, and
what went wrong. L<ERR_GET_LIB(3)> describes how to
extract this information. A method to obtain human-readable error
messages is described in L<ERR_error_string(3)>.
L<ERR_clear_error(3)> can be used to clear the
error queue.
=head1 ADDING NEW ERROR CODES TO OPENSSL
See L<ERR_put_error(3)> 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<XXX_F_...>, the second
argument is a reason code B<XXX_R_...>. 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<make errors>.
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<ERR_LIB_XXX>, define a macro XXXerr() (both in B<err.h>), add its
name to B<ERR_str_libraries[]> (in B<crypto/err/err.c>), and add
C<ERR_load_XXX_strings()> to the ERR_load_crypto_strings() function
(in B<crypto/err/err_all.c>). Finally, add an entry
L XXX xxx.h xxx_err.c
to B<crypto/err/openssl.ec>, and add B<xxx_err.c> to the Makefile.
Running B<make errors> will then generate a file B<xxx_err.c>, and
add all error codes used in the library to B<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 <openssl/bio.h>
#include <openssl/x509.h>
/* Macros, structures and function prototypes */
/* BEGIN ERROR CODES */
The B<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 B<make errors> is run.
The closing #endif etc will be automatically added by the script.
The generated C error code file B<xxx_err.c> will load the header
files B<stdio.h>, B<openssl/err.h> and B<openssl/xxx.h> 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<mkerr.pl> 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<ERR_STATE>
entry for each thread. ERR_get_state() returns the current thread's
B<ERR_STATE>. An B<ERR_STATE> can hold up to B<ERR_NUM_ERRORS> 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<CRYPTO_set_locking_callback(3)>,
L<ERR_get_error(3)>,
L<ERR_GET_LIB(3)>,
L<ERR_clear_error(3)>,
L<ERR_error_string(3)>,
L<ERR_print_errors(3)>,
L<ERR_load_crypto_strings(3)>,
L<ERR_put_error(3)>,
L<ERR_load_strings(3)>,
L<SSL_get_error(3)>
=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<https://www.openssl.org/source/license.html>.
=cut

90
doc/crypto/rand.pod
View file

@ -1,90 +0,0 @@
=pod
=head1 NAME
rand - pseudo-random number generator
=head1 SYNOPSIS
#include <openssl/rand.h>
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<RAND_METHOD>, 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<RAND_METHOD> 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<RAND_add(3)>. Its state can be saved in a seed file
(see L<RAND_load_file(3)>) to avoid having to go through the
seeding process whenever the application is started.
L<RAND_bytes(3)> describes how to obtain random data from the
PRNG.
=head1 SEE ALSO
L<BN_rand(3)>, L<RAND_add(3)>,
L<RAND_load_file(3)>, L<RAND_egd(3)>,
L<RAND_bytes(3)>,
L<RAND_set_rand_method(3)>,
L<RAND_cleanup(3)>
=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<https://www.openssl.org/source/license.html>.
=cut

2
doc/crypto/x509.pod
View file

@ -1,5 +1,7 @@
=pod
=for comment openssl_manual_section:7
=head1 NAME
x509 - X.509 certificate handling