abc/GmSSL
1
0
Fork 0
mirror of https://github.com/guanzhi/GmSSL.git synced 2026-06-30 01:33:39 +08:00
Code Issues Packages Projects Releases Wiki Activity

update

Browse Source
This commit is contained in:
Zhi Guan
2015-08-15 15:02:15 +08:00
parent 06df2fab54
commit 3bdc0ea895
2536 changed files with 417052 additions and 271997 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
doc/crypto/ASN1_STRING_length.pod
View File

@@ -3,7 +3,7 @@
=head1 NAME
ASN1_STRING_dup, ASN1_STRING_cmp, ASN1_STRING_set, ASN1_STRING_length,
ASN1_STRING_length_set, ASN1_STRING_type, ASN1_STRING_data -
ASN1_STRING_length_set, ASN1_STRING_type, ASN1_STRING_data, ASN1_STRING_to_UTF8 -
ASN1_STRING utility functions
=head1 SYNOPSIS

2
doc/crypto/ASN1_STRING_print_ex.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
ASN1_STRING_print_ex, ASN1_STRING_print_ex_fp - ASN1_STRING output routines.
ASN1_STRING_print_ex, ASN1_STRING_print_ex_fp, ASN1_STRING_print - ASN1_STRING output routines.
=head1 SYNOPSIS

129
doc/crypto/ASN1_TIME_set.pod Normal file
View File

@@ -0,0 +1,129 @@
=pod
=head1 NAME
ASN1_TIME_set, ASN1_TIME_adj, ASN1_TIME_check, ASN1_TIME_set_string,
ASN1_TIME_print, ASN1_TIME_diff - ASN.1 Time functions.
=head1 SYNOPSIS
ASN1_TIME *ASN1_TIME_set(ASN1_TIME *s, time_t t);
ASN1_TIME *ASN1_TIME_adj(ASN1_TIME *s, time_t t,
int offset_day, long offset_sec);
int ASN1_TIME_set_string(ASN1_TIME *s, const char *str);
int ASN1_TIME_check(const ASN1_TIME *t);
int ASN1_TIME_print(BIO *b, const ASN1_TIME *s);
int ASN1_TIME_diff(int *pday, int *psec,
const ASN1_TIME *from, const ASN1_TIME *to);
=head1 DESCRIPTION
The function ASN1_TIME_set() sets the ASN1_TIME structure B<s> to the
time represented by the time_t value B<t>. If B<s> is NULL a new ASN1_TIME
structure is allocated and returned.
ASN1_TIME_adj() sets the ASN1_TIME structure B<s> to the time represented
by the time B<offset_day> and B<offset_sec> after the time_t value B<t>.
The values of B<offset_day> or B<offset_sec> can be negative to set a
time before B<t>. The B<offset_sec> value can also exceed the number of
seconds in a day. If B<s> is NULL a new ASN1_TIME structure is allocated
and returned.
ASN1_TIME_set_string() sets ASN1_TIME structure B<s> to the time
represented by string B<str> which must be in appropriate ASN.1 time
format (for example YYMMDDHHMMSSZ or YYYYMMDDHHMMSSZ).
ASN1_TIME_check() checks the syntax of ASN1_TIME structure B<s>.
ASN1_TIME_print() prints out the time B<s> to BIO B<b> in human readable
format. It will be of the format MMM DD HH:MM:SS YYYY [GMT], for example
"Feb 3 00:55:52 2015 GMT" it does not include a newline. If the time
structure has invalid format it prints out "Bad time value" and returns
an error.
ASN1_TIME_diff() sets B<*pday> and B<*psec> to the time difference between
B<from> and B<to>. If B<to> represents a time later than B<from> then
one or both (depending on the time difference) of B<*pday> and B<*psec>
will be positive. If B<to> represents a time earlier than B<from> then
one or both of B<*pday> and B<*psec> will be negative. If B<to> and B<from>
represent the same time then B<*pday> and B<*psec> will both be zero.
If both B<*pday> and B<*psec> are non-zero they will always have the same
sign. The value of B<*psec> will always be less than the number of seconds
in a day. If B<from> or B<to> is NULL the current time is used.
=head1 NOTES
The ASN1_TIME structure corresponds to the ASN.1 structure B<Time>
defined in RFC5280 et al. The time setting functions obey the rules outlined
in RFC5280: if the date can be represented by UTCTime it is used, else
GeneralizedTime is used.
The ASN1_TIME structure is represented as an ASN1_STRING internally and can
be freed up using ASN1_STRING_free().
The ASN1_TIME structure can represent years from 0000 to 9999 but no attempt
is made to correct ancient calendar changes (for example from Julian to
Gregorian calendars).
Some applications add offset times directly to a time_t value and pass the
results to ASN1_TIME_set() (or equivalent). This can cause problems as the
time_t value can overflow on some systems resulting in unexpected results.
New applications should use ASN1_TIME_adj() instead and pass the offset value
in the B<offset_sec> and B<offset_day> parameters instead of directly
manipulating a time_t value.
=head1 BUGS
ASN1_TIME_print() currently does not print out the time zone: it either prints
out "GMT" or nothing. But all certificates complying with RFC5280 et al use GMT
anyway.
=head1 EXAMPLES
Set a time structure to one hour after the current time and print it out:
#include <time.h>
#include <openssl/asn1.h>
ASN1_TIME *tm;
time_t t;
BIO *b;
t = time(NULL);
tm = ASN1_TIME_adj(NULL, t, 0, 60 * 60);
b = BIO_new_fp(stdout, BIO_NOCLOSE);
ASN1_TIME_print(b, tm);
ASN1_STRING_free(tm);
BIO_free(b);
Determine if one time is later or sooner than the current time:
int day, sec;
if (!ASN1_TIME_diff(&day, &sec, NULL, to))
/* Invalid time format */
if (day > 0 || sec > 0)
printf("Later\n");
else if (day < 0 || sec < 0)
printf("Sooner\n");
else
printf("Same\n");
=head1 RETURN VALUES
ASN1_TIME_set() and ASN1_TIME_adj() return a pointer to an ASN1_TIME structure
or NULL if an error occurred.
ASN1_TIME_set_string() returns 1 if the time value is successfully set and
0 otherwise.
ASN1_TIME_check() returns 1 if the structure is syntactically correct and 0
otherwise.
ASN1_TIME_print() returns 1 if the time is successfully printed out and 0 if
an error occurred (I/O error or invalid time format).
ASN1_TIME_diff() returns 1 for sucess and 0 for failure. It can fail if the
pass ASN1_TIME structure has invalid syntax for example.
=cut

2
doc/crypto/ASN1_generate_nconf.pod
View File

@@ -61,7 +61,7 @@ Encode the B<NULL> type, the B<value> string must not be present.
=item B<INTEGER>, B<INT>
Encodes an ASN1 B<INTEGER> type. The B<value> string represents
the value of the integer, it can be preceeded by a minus sign and
the value of the integer, it can be prefaced by a minus sign and
is normally interpreted as a decimal value unless the prefix B<0x>
is included.

15
doc/crypto/BIO_f_base64.pod
View File

@@ -46,11 +46,11 @@ to standard output:
b64 = BIO_new(BIO_f_base64());
bio = BIO_new_fp(stdout, BIO_NOCLOSE);
bio = BIO_push(b64, bio);
BIO_write(bio, message, strlen(message));
BIO_flush(bio);
BIO_push(b64, bio);
BIO_write(b64, message, strlen(message));
BIO_flush(b64);
BIO_free_all(bio);
BIO_free_all(b64);
Read Base64 encoded data from standard input and write the decoded
data to standard output:
@@ -62,11 +62,12 @@ data to standard output:
b64 = BIO_new(BIO_f_base64());
bio = BIO_new_fp(stdin, BIO_NOCLOSE);
bio_out = BIO_new_fp(stdout, BIO_NOCLOSE);
bio = BIO_push(b64, bio);
while((inlen = BIO_read(bio, inbuf, 512)) > 0)
BIO_push(b64, bio);
while((inlen = BIO_read(b64, inbuf, 512)) > 0)
BIO_write(bio_out, inbuf, inlen);
BIO_free_all(bio);
BIO_flush(bio_out);
BIO_free_all(b64);
=head1 BUGS

2
doc/crypto/BIO_f_ssl.pod
View File

@@ -108,7 +108,7 @@ SSL BIOs are exceptional in that if the underlying transport
is non blocking they can still request a retry in exceptional
circumstances. Specifically this will happen if a session
renegotiation takes place during a BIO_read() operation, one
case where this happens is when SGC or step up occurs.
case where this happens is when step up occurs.
In OpenSSL 0.9.6 and later the SSL flag SSL_AUTO_RETRY can be
set to disable this behaviour. That is when this flag is set

2
doc/crypto/BIO_find_type.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
BIO_find_type, BIO_next - BIO chain traversal
BIO_find_type, BIO_next, BIO_method_type - BIO chain traversal
=head1 SYNOPSIS

2
doc/crypto/BIO_push.pod
View File

@@ -40,7 +40,7 @@ If the call:
BIO_push(b64, f);
is made then the new chain will be B<b64-chain>. After making the calls
is made then the new chain will be B<b64-f>. After making the calls
BIO_push(md2, b64);
BIO_push(md1, md2);

6
doc/crypto/BIO_s_accept.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
BIO_s_accept, BIO_set_accept_port, BIO_get_accept_port,
BIO_s_accept, BIO_set_accept_port, BIO_get_accept_port, BIO_new_accept,
BIO_set_nbio_accept, BIO_set_accept_bios, BIO_set_bind_mode,
BIO_get_bind_mode, BIO_do_accept - accept BIO
@@ -59,8 +59,8 @@ the accept socket. See L<BIO_s_fd(3)|BIO_s_fd(3)>
BIO_set_accept_port() uses the string B<name> to set the accept
port. The port is represented as a string of the form "host:port",
where "host" is the interface to use and "port" is the port.
Either or both values can be "*" which is interpreted as meaning
any interface or port respectively. "port" has the same syntax
The host can be can be "*" which is interpreted as meaning
any interface; "port" has the same syntax
as the port specified in BIO_set_conn_port() for connect BIOs,
that is it can be a numerical port string or a string to lookup
using getservbyname() and a string table.

2
doc/crypto/BIO_s_connect.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
BIO_s_connect, BIO_set_conn_hostname, BIO_set_conn_port,
BIO_s_connect, BIO_new_connect, BIO_set_conn_hostname, BIO_set_conn_port,
BIO_set_conn_ip, BIO_set_conn_int_port, BIO_get_conn_hostname,
BIO_get_conn_port, BIO_get_conn_ip, BIO_get_conn_int_port,
BIO_set_nbio, BIO_do_connect - connect BIO

6
doc/crypto/BN_BLINDING_new.pod
View File

@@ -4,7 +4,7 @@
BN_BLINDING_new, BN_BLINDING_free, BN_BLINDING_update, BN_BLINDING_convert,
BN_BLINDING_invert, BN_BLINDING_convert_ex, BN_BLINDING_invert_ex,
BN_BLINDING_get_thread_id, BN_BLINDING_set_thread_id, BN_BLINDING_get_flags,
BN_BLINDING_get_thread_id, BN_BLINDING_set_thread_id, BN_BLINDING_thread_id, BN_BLINDING_get_flags,
BN_BLINDING_set_flags, BN_BLINDING_create_param - blinding related BIGNUM
functions.
@@ -48,7 +48,7 @@ necessary parameters are set, by re-creating the blinding parameters.
BN_BLINDING_convert_ex() multiplies B<n> with the blinding factor B<A>.
If B<r> is not NULL a copy the inverse blinding factor B<Ai> will be
returned in B<r> (this is useful if a B<RSA> object is shared amoung
returned in B<r> (this is useful if a B<RSA> object is shared among
several threads). BN_BLINDING_invert_ex() multiplies B<n> with the
inverse blinding factor B<Ai>. If B<r> is not NULL it will be used as
the inverse blinding.
@@ -84,7 +84,7 @@ or NULL in case of an error.
BN_BLINDING_update(), BN_BLINDING_convert(), BN_BLINDING_invert(),
BN_BLINDING_convert_ex() and BN_BLINDING_invert_ex() return 1 on
success and 0 if an error occured.
success and 0 if an error occurred.
BN_BLINDING_thread_id() returns a pointer to the thread id object
within a B<BN_BLINDING> object.

10
doc/crypto/BN_CTX_new.pod
View File

@@ -10,9 +10,12 @@ BN_CTX_new, BN_CTX_init, BN_CTX_free - allocate and free BN_CTX structures
BN_CTX *BN_CTX_new(void);
void BN_CTX_free(BN_CTX *c);
Deprecated:
void BN_CTX_init(BN_CTX *c);
void BN_CTX_free(BN_CTX *c);
=head1 DESCRIPTION
@@ -22,8 +25,7 @@ is rather expensive when used in conjunction with repeated subroutine
calls, the B<BN_CTX> structure is used.
BN_CTX_new() allocates and initializes a B<BN_CTX>
structure. BN_CTX_init() initializes an existing uninitialized
B<BN_CTX>.
structure.
BN_CTX_free() frees the components of the B<BN_CTX>, and if it was
created by BN_CTX_new(), also the structure itself.
@@ -31,6 +33,8 @@ If L<BN_CTX_start(3)|BN_CTX_start(3)> has been used on the B<BN_CTX>,
L<BN_CTX_end(3)|BN_CTX_end(3)> must be called before the B<BN_CTX>
may be freed by BN_CTX_free().
BN_CTX_init() (deprecated) initializes an existing uninitialized B<BN_CTX>.
This should not be used for new programs. Use BN_CTX_new() instead.
=head1 RETURN VALUES

90
doc/crypto/BN_generate_prime.pod
View File

@@ -2,12 +2,31 @@
=head1 NAME
BN_generate_prime, BN_is_prime, BN_is_prime_fasttest - generate primes and test for primality
BN_generate_prime_ex, BN_is_prime_ex, BN_is_prime_fasttest_ex, BN_GENCB_call,
BN_GENCB_set_old, BN_GENCB_set, BN_generate_prime, BN_is_prime,
BN_is_prime_fasttest - generate primes and test for primality
=head1 SYNOPSIS
#include <openssl/bn.h>
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);
#define BN_GENCB_set_old(gencb, callback, cb_arg) ...
#define BN_GENCB_set(gencb, callback, cb_arg) ...
Deprecated:
BIGNUM *BN_generate_prime(BIGNUM *ret, int num, int safe, BIGNUM *add,
BIGNUM *rem, void (*callback)(int, int, void *), void *cb_arg);
@@ -20,27 +39,27 @@ BN_generate_prime, BN_is_prime, BN_is_prime_fasttest - generate primes and test
=head1 DESCRIPTION
BN_generate_prime() generates a pseudo-random prime number of B<num>
bits.
BN_generate_prime_ex() generates a pseudo-random prime number of
bit length B<bits>.
If B<ret> is not B<NULL>, it will be used to store the number.
If B<callback> is not B<NULL>, it is called as follows:
If B<cb> is not B<NULL>, it is used as follows:
=over 4
=item *
B<callback(0, i, cb_arg)> is called after generating the i-th
B<BN_GENCB_call(cb, 0, i)> is called after generating the i-th
potential prime number.
=item *
While the number is being tested for primality, B<callback(1, j,
cb_arg)> is called as described below.
While the number is being tested for primality,
B<BN_GENCB_call(cb, 1, j)> is called as described below.
=item *
When a prime has been found, B<callback(2, i, cb_arg)> is called.
When a prime has been found, B<BN_GENCB_call(cb, 2, i)> is called.
=back
@@ -54,37 +73,66 @@ generator.
If B<safe> is true, it will be a safe prime (i.e. a prime p so
that (p-1)/2 is also prime).
The PRNG must be seeded prior to calling BN_generate_prime().
The PRNG must be seeded prior to calling BN_generate_prime_ex().
The prime number generation has a negligible error probability.
BN_is_prime() and BN_is_prime_fasttest() test if the number B<a> is
BN_is_prime_ex() and BN_is_prime_fasttest_ex() test if the number B<p> is
prime. The following tests are performed until one of them shows that
B<a> is composite; if B<a> passes all these tests, it is considered
B<p> is composite; if B<p> passes all these tests, it is considered
prime.
BN_is_prime_fasttest(), when called with B<do_trial_division == 1>,
BN_is_prime_fasttest_ex(), when called with B<do_trial_division == 1>,
first attempts trial division by a number of small primes;
if no divisors are found by this test and B<callback> is not B<NULL>,
B<callback(1, -1, cb_arg)> is called.
if no divisors are found by this test and B<cb> is not B<NULL>,
B<BN_GENCB_call(cb, 1, -1)> is called.
If B<do_trial_division == 0>, this test is skipped.
Both BN_is_prime() and BN_is_prime_fasttest() perform a Miller-Rabin
probabilistic primality test with B<checks> iterations. If
B<checks == BN_prime_checks>, a number of iterations is used that
Both BN_is_prime_ex() and BN_is_prime_fasttest_ex() perform a Miller-Rabin
probabilistic primality test with B<nchecks> iterations. If
B<nchecks == BN_prime_checks>, a number of iterations is used that
yields a false positive rate of at most 2^-80 for random input.
If B<callback> is not B<NULL>, B<callback(1, j, cb_arg)> is called
If B<cb> is not B<NULL>, B<BN_GENCB_call(cb, 1, j)> is called
after the j-th iteration (j = 0, 1, ...). B<ctx> is a
pre-allocated B<BN_CTX> (to save the overhead of allocating and
freeing the structure in a loop), or B<NULL>.
BN_GENCB_call calls the callback function held in the B<BN_GENCB> structure
and passes the ints B<a> and B<b> as arguments. There are two types of
B<BN_GENCB> structure that are supported: "new" style and "old" style. New
programs should prefer the "new" style, whilst the "old" style is provided
for backwards compatibility purposes.
For "new" style callbacks a BN_GENCB structure should be initialised with a
call to BN_GENCB_set, where B<gencb> is a B<BN_GENCB *>, B<callback> is of
type B<int (*callback)(int, int, BN_GENCB *)> and B<cb_arg> is a B<void *>.
"Old" style callbacks are the same except they are initialised with a call
to BN_GENCB_set_old and B<callback> is of type
B<void (*callback)(int, int, void *)>.
A callback is invoked through a call to B<BN_GENCB_call>. This will check
the type of the callback and will invoke B<callback(a, b, gencb)> for new
style callbacks or B<callback(a, b, cb_arg)> for old style.
BN_generate_prime (deprecated) works in the same way as
BN_generate_prime_ex but expects an old style callback function
directly in the B<callback> parameter, and an argument to pass to it in
the B<cb_arg>. Similarly BN_is_prime and BN_is_prime_fasttest are
deprecated and can be compared to BN_is_prime_ex and
BN_is_prime_fasttest_ex respectively.
=head1 RETURN VALUES
BN_generate_prime_ex() return 1 on success or 0 on error.
BN_is_prime_ex(), BN_is_prime_fasttest_ex(), BN_is_prime() and
BN_is_prime_fasttest() return 0 if the number is composite, 1 if it is
prime with an error probability of less than 0.25^B<nchecks>, and
-1 on error.
BN_generate_prime() returns the prime number on success, B<NULL> otherwise.
BN_is_prime() returns 0 if the number is composite, 1 if it is
prime with an error probability of less than 0.25^B<checks>, and
-1 on error.
Callback functions should return 1 on success or 0 on error.
The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.

5
doc/crypto/BN_rand.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
BN_rand, BN_pseudo_rand - generate pseudo-random number
BN_rand, BN_pseudo_rand, BN_rand_range, BN_pseudo_rand_range - generate pseudo-random number
=head1 SYNOPSIS
@@ -24,7 +24,8 @@ most significant bit of the random number can be zero. If B<top> is 0,
it is set to 1, and if B<top> is 1, the two most significant bits of
the number will be set to 1, so that the product of two such random
numbers will always have 2*B<bits> length. If B<bottom> is true, the
number will be odd.
number will be odd. The value of B<bits> must be zero or greater. If B<bits> is
1 then B<top> cannot also be 1.
BN_pseudo_rand() does the same, but pseudo-random numbers generated by
this function are not necessarily unpredictable. They can be used for

8
doc/crypto/BN_set_bit.pod
View File

@@ -37,12 +37,12 @@ BN_mask_bits() truncates B<a> to an B<n> bit number
shorter than B<n> bits.
BN_lshift() shifts B<a> left by B<n> bits and places the result in
B<r> (C<r=a*2^n>). BN_lshift1() shifts B<a> left by one and places
the result in B<r> (C<r=2*a>).
B<r> (C<r=a*2^n>). Note that B<n> must be non-negative. BN_lshift1() shifts
B<a> left by one and places the result in B<r> (C<r=2*a>).
BN_rshift() shifts B<a> right by B<n> bits and places the result in
B<r> (C<r=a/2^n>). BN_rshift1() shifts B<a> right by one and places
the result in B<r> (C<r=a/2>).
B<r> (C<r=a/2^n>). Note that B<n> must be non-negative. BN_rshift1() shifts
B<a> right by one and places the result in B<r> (C<r=a/2>).
For the shift functions, B<r> and B<a> may be the same variable.

2
doc/crypto/CMS_add0_cert.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
CMS_add0_cert, CMS_add1_cert, CMS_get1_certs, CMS_add0_crl, CMS_get1_crls, - CMS certificate and CRL utility functions
CMS_add0_cert, CMS_add1_cert, CMS_get1_certs, CMS_add0_crl, CMS_add1_crl, CMS_get1_crls, - CMS certificate and CRL utility functions
=head1 SYNOPSIS

101
doc/crypto/CMS_add1_signer.pod Normal file
View File

@@ -0,0 +1,101 @@
=pod
=head1 NAME
CMS_add1_signer, CMS_SignerInfo_sign - add a signer to a CMS_ContentInfo signed data structure.
=head1 SYNOPSIS
#include <openssl/cms.h>
CMS_SignerInfo *CMS_add1_signer(CMS_ContentInfo *cms, X509 *signcert, EVP_PKEY *pkey, const EVP_MD *md, unsigned int flags);
int CMS_SignerInfo_sign(CMS_SignerInfo *si);
=head1 DESCRIPTION
CMS_add1_signer() adds a signer with certificate B<signcert> and private
key B<pkey> using message digest B<md> to CMS_ContentInfo SignedData
structure B<cms>.
The CMS_ContentInfo structure should be obtained from an initial call to
CMS_sign() with the flag B<CMS_PARTIAL> set or in the case or re-signing a
valid CMS_ContentInfo SignedData structure.
If the B<md> parameter is B<NULL> then the default digest for the public
key algorithm will be used.
Unless the B<CMS_REUSE_DIGEST> flag is set the returned CMS_ContentInfo
structure is not complete and must be finalized either by streaming (if
applicable) or a call to CMS_final().
The CMS_SignerInfo_sign() function will explicitly sign a CMS_SignerInfo
structure, its main use is when B<CMS_REUSE_DIGEST> and B<CMS_PARTIAL> flags
are both set.
=head1 NOTES
The main purpose of CMS_add1_signer() is to provide finer control
over a CMS signed data structure where the simpler CMS_sign() function defaults
are not appropriate. For example if multiple signers or non default digest
algorithms are needed. New attributes can also be added using the returned
CMS_SignerInfo structure and the CMS attribute utility functions or the
CMS signed receipt request functions.
Any of the following flags (ored together) can be passed in the B<flags>
parameter.
If B<CMS_REUSE_DIGEST> is set then an attempt is made to copy the content
digest value from the CMS_ContentInfo structure: to add a signer to an existing
structure. An error occurs if a matching digest value cannot be found to copy.
The returned CMS_ContentInfo structure will be valid and finalized when this
flag is set.
If B<CMS_PARTIAL> is set in addition to B<CMS_REUSE_DIGEST> then the
CMS_SignerInfo structure will not be finalized so additional attributes
can be added. In this case an explicit call to CMS_SignerInfo_sign() is
needed to finalize it.
If B<CMS_NOCERTS> is set the signer's certificate will not be included in the
CMS_ContentInfo structure, the signer's certificate must still be supplied in
the B<signcert> parameter though. This can reduce the size of the signature if
the signers certificate can be obtained by other means: for example a
previously signed message.
The SignedData structure includes several CMS signedAttributes including the
signing time, the CMS content type and the supported list of ciphers in an
SMIMECapabilities attribute. If B<CMS_NOATTR> is set then no signedAttributes
will be used. If B<CMS_NOSMIMECAP> is set then just the SMIMECapabilities are
omitted.
OpenSSL will by default identify signing certificates using issuer name
and serial number. If B<CMS_USE_KEYID> is set it will use the subject key
identifier value instead. An error occurs if the signing certificate does not
have a subject key identifier extension.
If present the SMIMECapabilities attribute indicates support for the following
algorithms in preference order: 256 bit AES, Gost R3411-94, Gost 28147-89, 192
bit AES, 128 bit AES, triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2.
If any of these algorithms is not available then it will not be included: for example the GOST algorithms will not be included if the GOST ENGINE is
not loaded.
CMS_add1_signer() returns an internal pointer to the CMS_SignerInfo
structure just added, this can be used to set additional attributes
before it is finalized.
=head1 RETURN VALUES
CMS_add1_signer() returns an internal pointer to the CMS_SignerInfo
structure just added or NULL if an error occurs.
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>,
L<CMS_final(3)|CMS_final(3)>,
=head1 HISTORY
CMS_add1_signer() was added to OpenSSL 0.9.8
=cut

16
doc/crypto/CMS_decrypt.pod
View File

@@ -27,7 +27,21 @@ function or errors about unknown algorithms will occur.
Although the recipients certificate is not needed to decrypt the data it is
needed to locate the appropriate (of possible several) recipients in the CMS
structure. If B<cert> is set to NULL all possible recipients are tried.
structure.
If B<cert> is set to NULL all possible recipients are tried. This case however
is problematic. To thwart the MMA attack (Bleichenbacher's attack on
PKCS #1 v1.5 RSA padding) all recipients are tried whether they succeed or
not. If no recipient succeeds then a random symmetric key is used to decrypt
the content: this will typically output garbage and may (but is not guaranteed
to) ultimately return a padding error only. If CMS_decrypt() just returned an
error when all recipient encrypted keys failed to decrypt an attacker could
use this in a timing attack. If the special flag B<CMS_DEBUG_DECRYPT> is set
then the above behaviour is modified and an error B<is> returned if no
recipient encrypted key can be decrypted B<without> generating a random
content encryption key. Applications should use this flag with
B<extreme caution> especially in automated gateways as it can leave them
open to attack.
It is possible to determine the correct recipient key by other means (for
example looking them up in a database) and setting them in the CMS structure

16
doc/crypto/CMS_get0_RecipientInfos.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
CMS_get0_RecipientInfos, CMS_RecipientInfo_type, CMS_RecipientInfo_ktri_get0_signer_id,CMS_RecipientInfo_ktri_cert_cmp, CMS_RecipientInfo_set0_pkey, CMS_RecipientInfo_kekri_get0_id, CMS_RecipientInfo_kekri_id_cmp, CMS_RecipientInfo_set0_key, CMS_RecipientInfo_decrypt - CMS envelopedData RecipientInfo routines
CMS_get0_RecipientInfos, CMS_RecipientInfo_type, CMS_RecipientInfo_ktri_get0_signer_id,CMS_RecipientInfo_ktri_cert_cmp, CMS_RecipientInfo_set0_pkey, CMS_RecipientInfo_kekri_get0_id, CMS_RecipientInfo_kekri_id_cmp, CMS_RecipientInfo_set0_key, CMS_RecipientInfo_decrypt, CMS_RecipientInfo_encrypt - CMS envelopedData RecipientInfo routines
=head1 SYNOPSIS
@@ -20,6 +20,7 @@
int CMS_RecipientInfo_set0_key(CMS_RecipientInfo *ri, unsigned char *key, size_t keylen);
int CMS_RecipientInfo_decrypt(CMS_ContentInfo *cms, CMS_RecipientInfo *ri);
int CMS_RecipientInfo_encrypt(CMS_ContentInfo *cms, CMS_RecipientInfo *ri);
=head1 DESCRIPTION
@@ -66,6 +67,11 @@ CMS_RecipientInfo_decrypt() attempts to decrypt CMS_RecipientInfo structure
B<ri> in structure B<cms>. A key must have been associated with the structure
first.
CMS_RecipientInfo_encrypt() attempts to encrypt CMS_RecipientInfo structure
B<ri> in structure B<cms>. A key must have been associated with the structure
first and the content encryption key must be available: for example by a
previous call to CMS_RecipientInfo_decrypt().
=head1 NOTES
The main purpose of these functions is to enable an application to lookup
@@ -81,6 +87,13 @@ any appropriate means it can then associated with the structure and
CMS_RecpientInfo_decrypt() called. If successful CMS_decrypt() can be called
with a NULL key to decrypt the enveloped content.
The CMS_RecipientInfo_encrypt() can be used to add a new recipient to an
existing enveloped data structure. Typically an application will first decrypt
an appropriate CMS_RecipientInfo structure to make the content encrypt key
available, it will then add a new recipient using a function such as
CMS_add1_recipient_cert() and finally encrypt the content encryption key
using CMS_RecipientInfo_encrypt().
=head1 RETURN VALUES
CMS_get0_RecipientInfos() returns all CMS_RecipientInfo structures, or NULL if
@@ -89,6 +102,7 @@ an error occurs.
CMS_RecipientInfo_ktri_get0_signer_id(), CMS_RecipientInfo_set0_pkey(),
CMS_RecipientInfo_kekri_get0_id(), CMS_RecipientInfo_set0_key() and
CMS_RecipientInfo_decrypt() return 1 for success or 0 if an error occurs.
CMS_RecipientInfo_encrypt() return 1 for success or 0 if an error occurs.
CMS_RecipientInfo_ktri_cert_cmp() and CMS_RecipientInfo_kekri_cmp() return 0
for a successful comparison and non zero otherwise.

8
doc/crypto/CMS_get0_SignerInfos.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
CMS_get0_SignerInfos, CMS_SignerInfo_get0_signer_id, CMS_SignerInfo_cert_cmp, CMS_set1_signer_certs - CMS signedData signer functions.
CMS_get0_SignerInfos, CMS_SignerInfo_get0_signer_id, CMS_SignerInfo_get0_signature, CMS_SignerInfo_cert_cmp, CMS_set1_signer_cert - CMS signedData signer functions.
=head1 SYNOPSIS
@@ -11,6 +11,7 @@
STACK_OF(CMS_SignerInfo) *CMS_get0_SignerInfos(CMS_ContentInfo *cms);
int CMS_SignerInfo_get0_signer_id(CMS_SignerInfo *si, ASN1_OCTET_STRING **keyid, X509_NAME **issuer, ASN1_INTEGER **sno);
ASN1_OCTET_STRING *CMS_SignerInfo_get0_signature(CMS_SignerInfo *si);
int CMS_SignerInfo_cert_cmp(CMS_SignerInfo *si, X509 *cert);
void CMS_SignerInfo_set1_signer_cert(CMS_SignerInfo *si, X509 *signer);
@@ -24,6 +25,11 @@ associated with a specific CMS_SignerInfo structure B<si>. Either the
keyidentifier will be set in B<keyid> or B<both> issuer name and serial number
in B<issuer> and B<sno>.
CMS_SignerInfo_get0_signature() retrieves the signature associated with
B<si> in a pointer to an ASN1_OCTET_STRING structure. This pointer returned
corresponds to the internal signature value if B<si> so it may be read or
modified.
CMS_SignerInfo_cert_cmp() compares the certificate B<cert> against the signer
identifier B<si>. It returns zero if the comparison is successful and non zero
if not.

22
doc/crypto/CMS_get0_type.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
CMS_get0_type, CMS_set1_eContentType, CMS_get0_eContentType - get and set CMS content types
CMS_get0_type, CMS_set1_eContentType, CMS_get0_eContentType, CMS_get0_content - get and set CMS content types and content
=head1 SYNOPSIS
@@ -11,6 +11,7 @@
const ASN1_OBJECT *CMS_get0_type(CMS_ContentInfo *cms);
int CMS_set1_eContentType(CMS_ContentInfo *cms, const ASN1_OBJECT *oid);
const ASN1_OBJECT *CMS_get0_eContentType(CMS_ContentInfo *cms);
ASN1_OCTET_STRING **CMS_get0_content(CMS_ContentInfo *cms);
=head1 DESCRIPTION
@@ -26,11 +27,15 @@ undefined.
ASN1_OBJECT *CMS_get0_eContentType() returns a pointer to the embedded
content type.
CMS_get0_content() returns a pointer to the B<ASN1_OCTET_STRING> pointer
containing the embedded content.
=head1 NOTES
As the B<0> implies CMS_get0_type() and CMS_get0_eContentType() return internal
pointers which should B<not> be freed up. CMS_set1_eContentType() copies the
supplied OID and it B<should> be freed up after use.
As the B<0> implies CMS_get0_type(), CMS_get0_eContentType() and
CMS_get0_content() return internal pointers which should B<not> be freed up.
CMS_set1_eContentType() copies the supplied OID and it B<should> be freed up
after use.
The B<ASN1_OBJECT> values returned can be converted to an integer B<NID> value
using OBJ_obj2nid(). For the currently supported content types the following
@@ -43,6 +48,15 @@ values are returned:
NID_pkcs7_encrypted
NID_pkcs7_enveloped
The return value of CMS_get0_content() is a pointer to the B<ASN1_OCTET_STRING>
content pointer. That means that for example:
ASN1_OCTET_STRING **pconf = CMS_get0_content(cms);
B<*pconf> could be NULL if there is no embedded content. Applications can
access, modify or create the embedded content in a B<CMS_ContentInfo> structure
using this function. Applications usually will not need to modify the
embedded content as it is normally set by higher level functions.
=head1 RETURN VALUES

2
doc/crypto/CMS_verify.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
CMS_verify - verify a CMS SignedData structure
CMS_verify, CMS_get0_signers - verify a CMS SignedData structure
=head1 SYNOPSIS

2
doc/crypto/CONF_modules_free.pod
View File

@@ -37,7 +37,7 @@ None of the functions return a value.
=head1 SEE ALSO
L<conf(5)|conf(5)>, L<OPENSSL_config(3)|OPENSSL_config(3)>,
L<CONF_modules_load_file(3), CONF_modules_load_file(3)>
L<CONF_modules_load_file(3)|CONF_modules_load_file(3)>
=head1 HISTORY

89
doc/crypto/CONF_modules_load_file.pod
View File

@@ -9,9 +9,9 @@
#include <openssl/conf.h>
int CONF_modules_load_file(const char *filename, const char *appname,
unsigned long flags);
unsigned long flags);
int CONF_modules_load(const CONF *cnf, const char *appname,
unsigned long flags);
unsigned long flags);
=head1 DESCRIPTION
@@ -22,7 +22,7 @@ NULL the standard OpenSSL application name B<openssl_conf> is used.
The behaviour can be cutomized using B<flags>.
CONF_modules_load() is idential to CONF_modules_load_file() except it
read configuration information from B<cnf>.
reads configuration information from B<cnf>.
=head1 NOTES
@@ -30,7 +30,7 @@ The following B<flags> are currently recognized:
B<CONF_MFLAGS_IGNORE_ERRORS> if set errors returned by individual
configuration modules are ignored. If not set the first module error is
considered fatal and no further modules are loads.
considered fatal and no further modules are loaded.
Normally any modules errors will add error information to the error queue. If
B<CONF_MFLAGS_SILENT> is set no error information is added.
@@ -42,7 +42,84 @@ B<CONF_MFLAGS_IGNORE_MISSING_FILE> if set will make CONF_load_modules_file()
ignore missing configuration files. Normally a missing configuration file
return an error.
=head1 RETURN VALUE
B<CONF_MFLAGS_DEFAULT_SECTION> if set and B<appname> is not NULL will use the
default section pointed to by B<openssl_conf> if B<appname> does not exist.
Applications should call these functions after loading builtin modules using
OPENSSL_load_builtin_modules(), any ENGINEs for example using
ENGINE_load_builtin_engines(), any algorithms for example
OPENSSL_add_all_algorithms() and (if the application uses libssl)
SSL_library_init().
By using CONF_modules_load_file() with appropriate flags an application can
customise application configuration to best suit its needs. In some cases the
use of a configuration file is optional and its absence is not an error: in
this case B<CONF_MFLAGS_IGNORE_MISSING_FILE> would be set.
Errors during configuration may also be handled differently by different
applications. For example in some cases an error may simply print out a warning
message and the application continue. In other cases an application might
consider a configuration file error as fatal and exit immediately.
Applications can use the CONF_modules_load() function if they wish to load a
configuration file themselves and have finer control over how errors are
treated.
=head1 EXAMPLES
Load a configuration file and print out any errors and exit (missing file
considered fatal):
if (CONF_modules_load_file(NULL, NULL, 0) <= 0) {
fprintf(stderr, "FATAL: error loading configuration file\n");
ERR_print_errors_fp(stderr);
exit(1);
}
Load default configuration file using the section indicated by "myapp",
tolerate missing files, but exit on other errors:
if (CONF_modules_load_file(NULL, "myapp",
CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) {
fprintf(stderr, "FATAL: error loading configuration file\n");
ERR_print_errors_fp(stderr);
exit(1);
}
Load custom configuration file and section, only print warnings on error,
missing configuration file ignored:
if (CONF_modules_load_file("/something/app.cnf", "myapp",
CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) {
fprintf(stderr, "WARNING: error loading configuration file\n");
ERR_print_errors_fp(stderr);
}
Load and parse configuration file manually, custom error handling:
FILE *fp;
CONF *cnf = NULL;
long eline;
fp = fopen("/somepath/app.cnf", "r");
if (fp == NULL) {
fprintf(stderr, "Error opening configuration file\n");
/* Other missing configuration file behaviour */
} else {
cnf = NCONF_new(NULL);
if (NCONF_load_fp(cnf, fp, &eline) == 0) {
fprintf(stderr, "Error on line %ld of configuration file\n", eline);
ERR_print_errors_fp(stderr);
/* Other malformed configuration file behaviour */
} else if (CONF_modules_load(cnf, "appname", 0) <= 0) {
fprintf(stderr, "Error configuring application\n");
ERR_print_errors_fp(stderr);
/* Other configuration error behaviour */
}
fclose(fp);
NCONF_free(cnf);
}
=head1 RETURN VALUES
These functions return 1 for success and a zero or negative value for
failure. If module errors are not ignored the return code will reflect the
@@ -51,7 +128,7 @@ return value of the failing module (this will always be zero or negative).
=head1 SEE ALSO
L<conf(5)|conf(5)>, L<OPENSSL_config(3)|OPENSSL_config(3)>,
L<CONF_free(3), CONF_free(3)>, L<err(3),err(3)>
L<CONF_free(3)|CONF_free(3)>, L<err(3)|err(3)>
=head1 HISTORY

43
doc/crypto/DH_generate_parameters.pod
View File

@@ -2,32 +2,39 @@
=head1 NAME
DH_generate_parameters, DH_check - generate and check Diffie-Hellman parameters
DH_generate_parameters_ex, DH_generate_parameters,
DH_check - generate and check Diffie-Hellman parameters
=head1 SYNOPSIS
#include <openssl/dh.h>
DH *DH_generate_parameters(int prime_len, int generator,
void (*callback)(int, int, void *), void *cb_arg);
int DH_generate_parameters_ex(DH *dh, int prime_len,int generator, BN_GENCB *cb);
int DH_check(DH *dh, int *codes);
Deprecated:
DH *DH_generate_parameters(int prime_len, int generator,
void (*callback)(int, int, void *), void *cb_arg);
=head1 DESCRIPTION
DH_generate_parameters() generates Diffie-Hellman parameters that can
be shared among a group of users, and returns them in a newly
allocated B<DH> structure. The pseudo-random number generator must be
DH_generate_parameters_ex() generates Diffie-Hellman parameters that can
be shared among a group of users, and stores them in the provided B<DH>
structure. The pseudo-random number generator must be
seeded prior to calling DH_generate_parameters().
B<prime_len> is the length in bits of the safe prime to be generated.
B<generator> is a small number E<gt> 1, typically 2 or 5.
A callback function may be used to provide feedback about the progress
of the key generation. If B<callback> is not B<NULL>, it will be
of the key generation. If B<cb> is not B<NULL>, it will be
called as described in L<BN_generate_prime(3)|BN_generate_prime(3)> while a random prime
number is generated, and when a prime has been found, B<callback(3,
0, cb_arg)> is called.
number is generated, and when a prime has been found, B<BN_GENCB_call(cb, 3, 0)>
is called. See L<BN_generate_prime(3)|BN_generate_prime(3)> for information on
the BN_GENCB_call() function.
DH_check() validates Diffie-Hellman parameters. It checks that B<p> is
a safe prime, and that B<g> is a suitable generator. In the case of an
@@ -38,19 +45,21 @@ checked, i.e. it does not equal 2 or 5.
=head1 RETURN VALUES
DH_generate_parameters() returns a pointer to the DH structure, or
NULL if the parameter generation fails. The error codes can be
obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
DH_generate_parameters_ex() and DH_check() return 1 if the check could be
performed, 0 otherwise.
DH_check() returns 1 if the check could be performed, 0 otherwise.
DH_generate_parameters() (deprecated) returns a pointer to the DH structure, or
NULL if the parameter generation fails.
The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
=head1 NOTES
DH_generate_parameters() may run for several hours before finding a
suitable prime.
DH_generate_parameters_ex() and DH_generate_parameters() may run for several
hours before finding a suitable prime.
The parameters generated by DH_generate_parameters() are not to be
used in signature schemes.
The parameters generated by DH_generate_parameters_ex() and DH_generate_parameters()
are not to be used in signature schemes.
=head1 BUGS

54
doc/crypto/DSA_generate_parameters.pod
View File

@@ -2,20 +2,26 @@
=head1 NAME
DSA_generate_parameters - generate DSA parameters
DSA_generate_parameters_ex, DSA_generate_parameters - generate DSA parameters
=head1 SYNOPSIS
#include <openssl/dsa.h>
int DSA_generate_parameters_ex(DSA *dsa, int bits,
const unsigned char *seed,int seed_len,
int *counter_ret, unsigned long *h_ret, BN_GENCB *cb);
Deprecated:
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);
=head1 DESCRIPTION
DSA_generate_parameters() generates primes p and q and a generator g
for use in the DSA.
DSA_generate_parameters_ex() generates primes p and q and a generator g
for use in the DSA and stores the result in B<dsa>.
B<bits> is the length of the prime to be generated; the DSS allows a
maximum of 1024 bits.
@@ -25,64 +31,74 @@ generated at random. Otherwise, the seed is used to generate
them. If the given seed does not yield a prime q, a new random
seed is chosen and placed at B<seed>.
DSA_generate_parameters() places the iteration count in
DSA_generate_parameters_ex() places the iteration count in
*B<counter_ret> and a counter used for finding a generator in
*B<h_ret>, unless these are B<NULL>.
A callback function may be used to provide feedback about the progress
of the key generation. If B<callback> is not B<NULL>, it will be
called as follows:
of the key generation. If B<cb> is not B<NULL>, it will be
called as shown below. For information on the BN_GENCB structure and the
BN_GENCB_call function discussed below, refer to
L<BN_generate_prime(3)|BN_generate_prime(3)>.
=over 4
=item *
When a candidate for q is generated, B<callback(0, m++, cb_arg)> is called
When a candidate for q is generated, B<BN_GENCB_call(cb, 0, m++)> is called
(m is 0 for the first candidate).
=item *
When a candidate for q has passed a test by trial division,
B<callback(1, -1, cb_arg)> is called.
B<BN_GENCB_call(cb, 1, -1)> is called.
While a candidate for q is tested by Miller-Rabin primality tests,
B<callback(1, i, cb_arg)> is called in the outer loop
B<BN_GENCB_call(cb, 1, i)> is called in the outer loop
(once for each witness that confirms that the candidate may be prime);
i is the loop counter (starting at 0).
=item *
When a prime q has been found, B<callback(2, 0, cb_arg)> and
B<callback(3, 0, cb_arg)> are called.
When a prime q has been found, B<BN_GENCB_call(cb, 2, 0)> and
B<BN_GENCB_call(cb, 3, 0)> are called.
=item *
Before a candidate for p (other than the first) is generated and tested,
B<callback(0, counter, cb_arg)> is called.
B<BN_GENCB_call(cb, 0, counter)> is called.
=item *
When a candidate for p has passed the test by trial division,
B<callback(1, -1, cb_arg)> is called.
B<BN_GENCB_call(cb, 1, -1)> is called.
While it is tested by the Miller-Rabin primality test,
B<callback(1, i, cb_arg)> is called in the outer loop
B<BN_GENCB_call(cb, 1, i)> is called in the outer loop
(once for each witness that confirms that the candidate may be prime).
i is the loop counter (starting at 0).
=item *
When p has been found, B<callback(2, 1, cb_arg)> is called.
When p has been found, B<BN_GENCB_call(cb, 2, 1)> is called.
=item *
When the generator has been found, B<callback(3, 1, cb_arg)> is called.
When the generator has been found, B<BN_GENCB_call(cb, 3, 1)> is called.
=back
DSA_generate_parameters() (deprecated) works in much the same way as for DSA_generate_parameters_ex, except that no B<dsa> parameter is passed and
instead a newly allocated B<DSA> structure is returned. Additionally "old
style" callbacks are used instead of the newer BN_GENCB based approach.
Refer to L<BN_generate_prime(3)|BN_generate_prime(3)> for further information.
=head1 RETURN VALUE
DSA_generate_parameters_ex() returns a 1 on success, or 0 otherwise.
DSA_generate_parameters() returns a pointer to the DSA structure, or
B<NULL> if the parameter generation fails. The error codes can be
obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
B<NULL> if the parameter generation fails.
The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
=head1 BUGS
@@ -91,7 +107,7 @@ Seed lengths E<gt> 20 are not supported.
=head1 SEE ALSO
L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>,
L<DSA_free(3)|DSA_free(3)>
L<DSA_free(3)|DSA_free(3)>, L<BN_generate_prime(3)|BN_generate_prime(3)>
=head1 HISTORY

60
doc/crypto/EC_GFp_simple_method.pod Normal file
View File

@@ -0,0 +1,60 @@
=pod
=head1 NAME
EC_GFp_simple_method, EC_GFp_mont_method, EC_GFp_nist_method, EC_GFp_nistp224_method, EC_GFp_nistp256_method, EC_GFp_nistp521_method, EC_GF2m_simple_method, EC_METHOD_get_field_type - Functions for obtaining B<EC_METHOD> objects.
=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);
int EC_METHOD_get_field_type(const EC_METHOD *meth);
=head1 DESCRIPTION
The Elliptic Curve library provides a number of different implementations through a single common interface.
When constructing a curve using EC_GROUP_new (see L<EC_GROUP_new(3)|EC_GROUP_new(3)>) an
implementation method must be provided. The functions described here all return a const pointer to an
B<EC_METHOD> structure that can be passed to EC_GROUP_NEW. It is important that the correct implementation
type for the form of curve selected is used.
For F2^m curves there is only one implementation choice, i.e. EC_GF2_simple_method.
For Fp curves the lowest common denominator implementation is the EC_GFp_simple_method implementation. All
other implementations are based on this one. EC_GFp_mont_method builds on EC_GFp_simple_method but adds the
use of montgomery multiplication (see L<BN_mod_mul_montgomery(3)|BN_mod_mul_montgomery(3)>). EC_GFp_nist_method
offers an implementation optimised for use with NIST recommended curves (NIST curves are available through
EC_GROUP_new_by_curve_name as described in L<EC_GROUP_new(3)|EC_GROUP_new(3)>).
The functions EC_GFp_nistp224_method, EC_GFp_nistp256_method and EC_GFp_nistp521_method offer 64 bit
optimised implementations for the NIST P224, P256 and P521 curves respectively. Note, however, that these
implementations are not available on all platforms.
EC_METHOD_get_field_type identifies what type of field the EC_METHOD structure supports, which will be either
F2^m or Fp. If the field type is Fp then the value B<NID_X9_62_prime_field> is returned. If the field type is
F2^m then the value B<NID_X9_62_characteristic_two_field> is returned. These values are defined in the
obj_mac.h header file.
=head1 RETURN VALUES
All EC_GFp* functions and EC_GF2m_simple_method always return a const pointer to an EC_METHOD structure.
EC_METHOD_get_field_type returns an integer that identifies the type of field the EC_METHOD structure supports.
=head1 SEE ALSO
L<crypto(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>, L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>,
L<EC_POINT_new(3)|EC_POINT_new(3)>, L<EC_POINT_add(3)|EC_POINT_add(3)>, L<EC_KEY_new(3)|EC_KEY_new(3)>,
L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)>,
L<BN_mod_mul_montgomery(3)|BN_mod_mul_montgomery(3)>
=cut

174
doc/crypto/EC_GROUP_copy.pod Normal file
View File

@@ -0,0 +1,174 @@
=pod
=head1 NAME
EC_GROUP_copy, EC_GROUP_dup, EC_GROUP_method_of, EC_GROUP_set_generator, EC_GROUP_get0_generator, EC_GROUP_get_order, EC_GROUP_get_cofactor, EC_GROUP_set_curve_name, EC_GROUP_get_curve_name, EC_GROUP_set_asn1_flag, EC_GROUP_get_asn1_flag, EC_GROUP_set_point_conversion_form, EC_GROUP_get_point_conversion_form, EC_GROUP_get0_seed, EC_GROUP_get_seed_len, EC_GROUP_set_seed, EC_GROUP_get_degree, EC_GROUP_check, EC_GROUP_check_discriminant, EC_GROUP_cmp, EC_GROUP_get_basis_type, EC_GROUP_get_trinomial_basis, EC_GROUP_get_pentanomial_basis - Functions for manipulating B<EC_GROUP> objects.
=head1 SYNOPSIS
#include <openssl/ec.h>
#include <openssl/bn.h>
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_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_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);
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);
=head1 DESCRIPTION
EC_GROUP_copy copies the curve B<src> into B<dst>. Both B<src> and B<dst> must use the same EC_METHOD.
EC_GROUP_dup creates a new EC_GROUP object and copies the content from B<src> to the newly created
EC_GROUP object.
EC_GROUP_method_of obtains the EC_METHOD of B<group>.
EC_GROUP_set_generator sets curve paramaters that must be agreed by all participants using the curve. These
paramaters include the B<generator>, the B<order> and the B<cofactor>. The B<generator> is a well defined point on the
curve chosen for cryptographic operations. Integers used for point multiplications will be between 0 and
n-1 where n is the B<order>. The B<order> multipied by the B<cofactor> gives the number of points on the curve.
EC_GROUP_get0_generator returns the generator for the identified B<group>.
The functions EC_GROUP_get_order and EC_GROUP_get_cofactor populate the provided B<order> and B<cofactor> parameters
with the respective order and cofactors for the B<group>.
The functions EC_GROUP_set_curve_name and EC_GROUP_get_curve_name, set and get the NID for the curve respectively
(see L<EC_GROUP_new(3)|EC_GROUP_new(3)>). If a curve does not have a NID associated with it, then EC_GROUP_get_curve_name
will return 0.
The asn1_flag value on a curve is used to determine whether there is a specific ASN1 OID to describe the curve or not.
If the asn1_flag is 1 then this is a named curve with an associated ASN1 OID. If not then asn1_flag is 0. The functions
EC_GROUP_get_asn1_flag and EC_GROUP_set_asn1_flag get and set the status of the asn1_flag for the curve. If set then
the curve_name must also be set.
The point_coversion_form for a curve controls how EC_POINT data is encoded as ASN1 as defined in X9.62 (ECDSA).
point_conversion_form_t is an enum defined as follows:
typedef enum {
/** the point is encoded as z||x, where the octet z specifies
* which solution of the quadratic equation y is */
POINT_CONVERSION_COMPRESSED = 2,
/** the point is encoded as z||x||y, where z is the octet 0x02 */
POINT_CONVERSION_UNCOMPRESSED = 4,
/** the point is encoded as z||x||y, where the octet z specifies
* which solution of the quadratic equation y is */
POINT_CONVERSION_HYBRID = 6
} point_conversion_form_t;
For POINT_CONVERSION_UNCOMPRESSED the point is encoded as an octet signifying the UNCOMPRESSED form has been used followed by
the octets for x, followed by the octets for y.
For any given x co-ordinate for a point on a curve it is possible to derive two possible y values. For
POINT_CONVERSION_COMPRESSED the point is encoded as an octet signifying that the COMPRESSED form has been used AND which of
the two possible solutions for y has been used, followed by the octets for x.
For POINT_CONVERSION_HYBRID the point is encoded as an octet signifying the HYBRID form has been used AND which of the two
possible solutions for y has been used, followed by the octets for x, followed by the octets for y.
The functions EC_GROUP_set_point_conversion_form and EC_GROUP_get_point_conversion_form set and get the point_conversion_form
for the curve respectively.
ANSI X9.62 (ECDSA standard) defines a method of generating the curve parameter b from a random number. This provides advantages
in that a parameter obtained in this way is highly unlikely to be susceptible to special purpose attacks, or have any trapdoors in it.
If the seed is present for a curve then the b parameter was generated in a verifiable fashion using that seed. The OpenSSL EC library
does not use this seed value but does enable you to inspect it using EC_GROUP_get0_seed. This returns a pointer to a memory block
containing the seed that was used. The length of the memory block can be obtained using EC_GROUP_get_seed_len. A number of the
builtin curves within the library provide seed values that can be obtained. It is also possible to set a custom seed using
EC_GROUP_set_seed and passing a pointer to a memory block, along with the length of the seed. Again, the EC library will not use
this seed value, although it will be preserved in any ASN1 based communications.
EC_GROUP_get_degree gets the degree of the field. For Fp fields this will be the number of bits in p. For F2^m fields this will be
the value m.
The function EC_GROUP_check_discriminant calculates the discriminant for the curve and verifies that it is valid.
For a curve defined over Fp the discriminant is given by the formula 4*a^3 + 27*b^2 whilst for F2^m curves the discriminant is
simply b. In either case for the curve to be valid the discriminant must be non zero.
The function EC_GROUP_check performs a number of checks on a curve to verify that it is valid. Checks performed include
verifying that the discriminant is non zero; that a generator has been defined; that the generator is on the curve and has
the correct order.
EC_GROUP_cmp compares B<a> and B<b> to determine whether they represent the same curve or not.
The functions EC_GROUP_get_basis_type, EC_GROUP_get_trinomial_basis and EC_GROUP_get_pentanomial_basis should only be called for curves
defined over an F2^m field. Addition and multiplication operations within an F2^m field are performed using an irreducible polynomial
function f(x). This function is either a trinomial of the form:
f(x) = x^m + x^k + 1 with m > k >= 1
or a pentanomial of the form:
f(x) = x^m + x^k3 + x^k2 + x^k1 + 1 with m > k3 > k2 > k1 >= 1
The function EC_GROUP_get_basis_type returns a NID identifying whether a trinomial or pentanomial is in use for the field. The
function EC_GROUP_get_trinomial_basis must only be called where f(x) is of the trinomial form, and returns the value of B<k>. Similary
the function EC_GROUP_get_pentanomial_basis must only be called where f(x) is of the pentanomial form, and returns the values of B<k1>,
B<k2> and B<k3> respectively.
=head1 RETURN VALUES
The following functions return 1 on success or 0 on error: EC_GROUP_copy, EC_GROUP_set_generator, EC_GROUP_check,
EC_GROUP_check_discriminant, EC_GROUP_get_trinomial_basis and EC_GROUP_get_pentanomial_basis.
EC_GROUP_dup returns a pointer to the duplicated curve, or NULL on error.
EC_GROUP_method_of returns the EC_METHOD implementation in use for the given curve or NULL on error.
EC_GROUP_get0_generator returns the generator for the given curve or NULL on error.
EC_GROUP_get_order, EC_GROUP_get_cofactor, EC_GROUP_get_curve_name, EC_GROUP_get_asn1_flag, EC_GROUP_get_point_conversion_form
and EC_GROUP_get_degree return the order, cofactor, curve name (NID), ASN1 flag, point_conversion_form and degree for the
specified curve respectively. If there is no curve name associated with a curve then EC_GROUP_get_curve_name will return 0.
EC_GROUP_get0_seed returns a pointer to the seed that was used to generate the parameter b, or NULL if the seed is not
specified. EC_GROUP_get_seed_len returns the length of the seed or 0 if the seed is not specified.
EC_GROUP_set_seed returns the length of the seed that has been set. If the supplied seed is NULL, or the supplied seed length is
0, the the return value will be 1. On error 0 is returned.
EC_GROUP_cmp returns 0 if the curves are equal, 1 if they are not equal, or -1 on error.
EC_GROUP_get_basis_type returns the values NID_X9_62_tpBasis or NID_X9_62_ppBasis (as defined in <openssl/obj_mac.h>) for a
trinomial or pentanomial respectively. Alternatively in the event of an error a 0 is returned.
=head1 SEE ALSO
L<crypto(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>,
L<EC_POINT_new(3)|EC_POINT_new(3)>, L<EC_POINT_add(3)|EC_POINT_add(3)>, L<EC_KEY_new(3)|EC_KEY_new(3)>,
L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)>
=cut

95
doc/crypto/EC_GROUP_new.pod Normal file
View File

@@ -0,0 +1,95 @@
=pod
=head1 NAME
EC_GROUP_new, EC_GROUP_free, EC_GROUP_clear_free, EC_GROUP_new_curve_GFp, EC_GROUP_new_curve_GF2m, EC_GROUP_new_by_curve_name, EC_GROUP_set_curve_GFp, EC_GROUP_get_curve_GFp, EC_GROUP_set_curve_GF2m, EC_GROUP_get_curve_GF2m, EC_get_builtin_curves - Functions for creating and destroying B<EC_GROUP> objects.
=head1 SYNOPSIS
#include <openssl/ec.h>
#include <openssl/bn.h>
EC_GROUP *EC_GROUP_new(const EC_METHOD *meth);
void EC_GROUP_free(EC_GROUP *group);
void EC_GROUP_clear_free(EC_GROUP *group);
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);
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);
size_t EC_get_builtin_curves(EC_builtin_curve *r, size_t nitems);
=head1 DESCRIPTION
Within the library there are two forms of elliptic curve that are of interest. The first form is those defined over the
prime field Fp. The elements of Fp are the integers 0 to p-1, where p is a prime number. This gives us a revised
elliptic curve equation as follows:
y^2 mod p = x^3 +ax + b mod p
The second form is those defined over a binary field F2^m where the elements of the field are integers of length at
most m bits. For this form the elliptic curve equation is modified to:
y^2 + xy = x^3 + ax^2 + b (where b != 0)
Operations in a binary field are performed relative to an B<irreducible polynomial>. All such curves with OpenSSL
use a trinomial or a pentanomial for this parameter.
A new curve can be constructed by calling EC_GROUP_new, using the implementation provided by B<meth> (see
L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>). It is then necessary to call either EC_GROUP_set_curve_GFp or
EC_GROUP_set_curve_GF2m as appropriate to create a curve defined over Fp or over F2^m respectively.
EC_GROUP_set_curve_GFp sets the curve parameters B<p>, B<a> and B<b> for a curve over Fp stored in B<group>.
EC_group_get_curve_GFp obtains the previously set curve parameters.
EC_GROUP_set_curve_GF2m sets the equivalent curve parameters for a curve over F2^m. In this case B<p> represents
the irreducible polybnomial - each bit represents a term in the polynomial. Therefore there will either be three
or five bits set dependant on whether the polynomial is a trinomial or a pentanomial.
EC_group_get_curve_GF2m obtains the previously set curve parameters.
The functions EC_GROUP_new_curve_GFp and EC_GROUP_new_curve_GF2m are shortcuts for calling EC_GROUP_new and the
appropriate EC_group_set_curve function. An appropriate default implementation method will be used.
Whilst the library can be used to create any curve using the functions described above, there are also a number of
predefined curves that are available. In order to obtain a list of all of the predefined curves, call the function
EC_get_builtin_curves. The parameter B<r> should be an array of EC_builtin_curve structures of size B<nitems>. The function
will populate the B<r> array with information about the builtin curves. If B<nitems> is less than the total number of
curves available, then the first B<nitems> curves will be returned. Otherwise the total number of curves will be
provided. The return value is the total number of curves available (whether that number has been populated in B<r> or
not). Passing a NULL B<r>, or setting B<nitems> to 0 will do nothing other than return the total number of curves available.
The EC_builtin_curve structure is defined as follows:
typedef struct {
int nid;
const char *comment;
} EC_builtin_curve;
Each EC_builtin_curve item has a unique integer id (B<nid>), and a human readable comment string describing the curve.
In order to construct a builtin curve use the function EC_GROUP_new_by_curve_name and provide the B<nid> of the curve to
be constructed.
EC_GROUP_free frees the memory associated with the EC_GROUP.
EC_GROUP_clear_free destroys any sensitive data held within the EC_GROUP and then frees its memory.
=head1 RETURN VALUES
All EC_GROUP_new* functions return a pointer to the newly constructed group, or NULL on error.
EC_get_builtin_curves returns the number of builtin curves that are available.
EC_GROUP_set_curve_GFp, EC_GROUP_get_curve_GFp, EC_GROUP_set_curve_GF2m, EC_GROUP_get_curve_GF2m return 1 on success or 0 on error.
=head1 SEE ALSO
L<crypto(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>,
L<EC_POINT_new(3)|EC_POINT_new(3)>, L<EC_POINT_add(3)|EC_POINT_add(3)>, L<EC_KEY_new(3)|EC_KEY_new(3)>,
L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)>
=cut

108
doc/crypto/EC_KEY_new.pod Normal file
View File

@@ -0,0 +1,108 @@
=pod
=head1 NAME
EC_KEY_new, EC_KEY_get_flags, EC_KEY_set_flags, EC_KEY_clear_flags, EC_KEY_new_by_curve_name, EC_KEY_free, EC_KEY_copy, EC_KEY_dup, EC_KEY_up_ref, EC_KEY_get0_group, EC_KEY_set_group, EC_KEY_get0_private_key, EC_KEY_set_private_key, EC_KEY_get0_public_key, EC_KEY_set_public_key, EC_KEY_get_enc_flags, EC_KEY_set_enc_flags, EC_KEY_get_conv_form, EC_KEY_set_conv_form, EC_KEY_get_key_method_data, EC_KEY_insert_key_method_data, EC_KEY_set_asn1_flag, EC_KEY_precompute_mult, EC_KEY_generate_key, EC_KEY_check_key, EC_KEY_set_public_key_affine_coordinates - Functions for creating, destroying and manipulating B<EC_KEY> objects.
=head1 SYNOPSIS
#include <openssl/ec.h>
#include <openssl/bn.h>
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);
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_get_key_method_data(EC_KEY *key,
void *(*dup_func)(void *), void (*free_func)(void *), void (*clear_free_func)(void *));
void EC_KEY_insert_key_method_data(EC_KEY *key, void *data,
void *(*dup_func)(void *), void (*free_func)(void *), void (*clear_free_func)(void *));
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);
=head1 DESCRIPTION
An EC_KEY represents a public key and (optionaly) an associated private key. A new EC_KEY (with no associated curve) can be constructed by calling EC_KEY_new.
The reference count for the newly created EC_KEY is initially set to 1. A curve can be associated with the EC_KEY by calling
EC_KEY_set_group.
Alternatively a new EC_KEY can be constructed by calling EC_KEY_new_by_curve_name and supplying the nid of the associated curve. Refer to L<EC_GROUP_new(3)|EC_GROUP_new(3)> for a description of curve names. This function simply wraps calls to EC_KEY_new and
EC_GROUP_new_by_curve_name.
Calling EC_KEY_free decrements the reference count for the EC_KEY object, and if it has dropped to zero then frees the memory associated
with it.
EC_KEY_copy copies the contents of the EC_KEY in B<src> into B<dest>.
EC_KEY_dup creates a new EC_KEY object and copies B<ec_key> into it.
EC_KEY_up_ref increments the reference count associated with the EC_KEY object.
EC_KEY_generate_key generates a new public and private key for the supplied B<eckey> object. B<eckey> must have an EC_GROUP object
associated with it before calling this function. The private key is a random integer (0 < priv_key < order, where order is the order
of the EC_GROUP object). The public key is an EC_POINT on the curve calculated by multiplying the generator for the curve by the
private key.
EC_KEY_check_key performs various sanity checks on the EC_KEY object to confirm that it is valid.
EC_KEY_set_public_key_affine_coordinates sets the public key for B<key> based on its affine co-ordinates, i.e. it constructs an EC_POINT
object based on the supplied B<x> and B<y> values and sets the public key to be this EC_POINT. It will also performs certain sanity checks
on the key to confirm that it is valid.
The functions EC_KEY_get0_group, EC_KEY_set_group, EC_KEY_get0_private_key, EC_KEY_set_private_key, EC_KEY_get0_public_key, and EC_KEY_set_public_key get and set the EC_GROUP object, the private key and the EC_POINT public key for the B<key> respectively.
The functions EC_KEY_get_conv_form and EC_KEY_set_conv_form get and set the point_conversion_form for the B<key>. For a description
of point_conversion_forms please refer to L<EC_POINT_new(3)|EC_POINT_new(3)>.
EC_KEY_insert_key_method_data and EC_KEY_get_key_method_data enable the caller to associate arbitary additional data specific to the
elliptic curve scheme being used with the EC_KEY object. This data is treated as a "black box" by the ec library. The data to be stored by EC_KEY_insert_key_method_data is provided in the B<data> parameter, which must have have associated functions for duplicating, freeing and "clear_freeing" the data item. If a subsequent EC_KEY_get_key_method_data call is issued, the functions for duplicating, freeing and "clear_freeing" the data item must be provided again, and they must be the same as they were when the data item was inserted.
EC_KEY_set_flags sets the flags in the B<flags> parameter on the EC_KEY object. Any flags that are already set are left set. The currently defined standard flags are EC_FLAG_NON_FIPS_ALLOW and EC_FLAG_FIPS_CHECKED. In addition there is the flag EC_FLAG_COFACTOR_ECDH which is specific to ECDH and is defined in ecdh.h. EC_KEY_get_flags returns the current flags that are set for this EC_KEY. EC_KEY_clear_flags clears the flags indicated by the B<flags> parameter. All other flags are left in their existing state.
EC_KEY_set_asn1_flag sets the asn1_flag on the underlying EC_GROUP object (if set). Refer to L<EC_GROUP_copy(3)|EC_GROUP_copy(3)> for further information on the asn1_flag.
EC_KEY_precompute_mult stores multiples of the underlying EC_GROUP generator for faster point multiplication. See also L<EC_POINT_add(3)|EC_POINT_add(3)>.
=head1 RETURN VALUES
EC_KEY_new, EC_KEY_new_by_curve_name and EC_KEY_dup return a pointer to the newly created EC_KEY object, or NULL on error.
EC_KEY_get_flags returns the flags associated with the EC_KEY object as an integer.
EC_KEY_copy returns a pointer to the destination key, or NULL on error.
EC_KEY_up_ref, EC_KEY_set_group, EC_KEY_set_private_key, EC_KEY_set_public_key, EC_KEY_precompute_mult, EC_KEY_generate_key, EC_KEY_check_key and EC_KEY_set_public_key_affine_coordinates return 1 on success or 0 on error.
EC_KEY_get0_group returns the EC_GROUP associated with the EC_KEY.
EC_KEY_get0_private_key returns the private key associated with the EC_KEY.
EC_KEY_get_conv_form return the point_conversion_form for the EC_KEY.
=head1 SEE ALSO
L<crypto(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>,
L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>, L<EC_POINT_new(3)|EC_POINT_new(3)>,
L<EC_POINT_add(3)|EC_POINT_add(3)>,
L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>,
L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)>
=cut

72
doc/crypto/EC_POINT_add.pod Normal file
View File

@@ -0,0 +1,72 @@
=pod
=head1 NAME
EC_POINT_add, EC_POINT_dbl, EC_POINT_invert, EC_POINT_is_at_infinity, EC_POINT_is_on_curve, EC_POINT_cmp, EC_POINT_make_affine, EC_POINTs_make_affine, EC_POINTs_mul, EC_POINT_mul, EC_GROUP_precompute_mult, EC_GROUP_have_precompute_mult - Functions for performing mathematical operations and tests on B<EC_POINT> objects.
=head1 SYNOPSIS
#include <openssl/ec.h>
#include <openssl/bn.h>
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);
=head1 DESCRIPTION
EC_POINT_add adds the two points B<a> and B<b> and places the result in B<r>. Similarly EC_POINT_dbl doubles the point B<a> and places the
result in B<r>. In both cases it is valid for B<r> to be one of B<a> or B<b>.
EC_POINT_invert calculates the inverse of the supplied point B<a>. The result is placed back in B<a>.
The function EC_POINT_is_at_infinity tests whether the supplied point is at infinity or not.
EC_POINT_is_on_curve tests whether the supplied point is on the curve or not.
EC_POINT_cmp compares the two supplied points and tests whether or not they are equal.
The functions EC_POINT_make_affine and EC_POINTs_make_affine force the internal representation of the EC_POINT(s) into the affine
co-ordinate system. In the case of EC_POINTs_make_affine the value B<num> provides the number of points in the array B<points> to be
forced.
EC_POINT_mul calculates the value generator * B<n> + B<q> * B<m> and stores the result in B<r>. The value B<n> may be NULL in which case the result is just B<q> * B<m>.
EC_POINTs_mul calculates the value generator * B<n> + B<q[0]> * B<m[0]> + ... + B<q[num-1]> * B<m[num-1]>. As for EC_POINT_mul the value
B<n> may be NULL.
The function EC_GROUP_precompute_mult stores multiples of the generator for faster point multiplication, whilst
EC_GROUP_have_precompute_mult tests whether precomputation has already been done. See L<EC_GROUP_copy(3)|EC_GROUP_copy(3)> for information
about the generator.
=head1 RETURN VALUES
The following functions return 1 on success or 0 on error: EC_POINT_add, EC_POINT_dbl, EC_POINT_invert, EC_POINT_make_affine,
EC_POINTs_make_affine, EC_POINTs_make_affine, EC_POINT_mul, EC_POINTs_mul and EC_GROUP_precompute_mult.
EC_POINT_is_at_infinity returns 1 if the point is at infinity, or 0 otherwise.
EC_POINT_is_on_curve returns 1 if the point is on the curve, 0 if not, or -1 on error.
EC_POINT_cmp returns 1 if the points are not equal, 0 if they are, or -1 on error.
EC_GROUP_have_precompute_mult return 1 if a precomputation has been done, or 0 if not.
=head1 SEE ALSO
L<crypto(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>, L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>,
L<EC_POINT_new(3)|EC_POINT_new(3)>, L<EC_KEY_new(3)|EC_KEY_new(3)>,
L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)>
=cut

128
doc/crypto/EC_POINT_new.pod Normal file
View File

@@ -0,0 +1,128 @@
=pod
=head1 NAME
EC_POINT_new, EC_POINT_free, EC_POINT_clear_free, EC_POINT_copy, EC_POINT_dup, EC_POINT_method_of, EC_POINT_set_to_infinity, EC_POINT_set_Jprojective_coordinates, EC_POINT_get_Jprojective_coordinates_GFp, EC_POINT_set_affine_coordinates_GFp, EC_POINT_get_affine_coordinates_GFp, EC_POINT_set_compressed_coordinates_GFp, EC_POINT_set_affine_coordinates_GF2m, EC_POINT_get_affine_coordinates_GF2m, EC_POINT_set_compressed_coordinates_GF2m, EC_POINT_point2oct, EC_POINT_oct2point, EC_POINT_point2bn, EC_POINT_bn2point, EC_POINT_point2hex, EC_POINT_hex2point - Functions for creating, destroying and manipulating B<EC_POINT> objects.
=head1 SYNOPSIS
#include <openssl/ec.h>
#include <openssl/bn.h>
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 *);
=head1 DESCRIPTION
An EC_POINT represents a point on a curve. A new point is constructed by calling the function EC_POINT_new and providing the B<group>
object that the point relates to.
EC_POINT_free frees the memory associated with the EC_POINT.
EC_POINT_clear_free destroys any sensitive data held within the EC_POINT and then frees its memory.
EC_POINT_copy copies the point B<src> into B<dst>. Both B<src> and B<dst> must use the same EC_METHOD.
EC_POINT_dup creates a new EC_POINT object and copies the content from B<src> to the newly created
EC_POINT object.
EC_POINT_method_of obtains the EC_METHOD associated with B<point>.
A valid point on a curve is the special point at infinity. A point is set to be at infinity by calling EC_POINT_set_to_infinity.
The affine co-ordinates for a point describe a point in terms of its x and y position. The functions
EC_POINT_set_affine_coordinates_GFp and EC_POINT_set_affine_coordinates_GF2m set the B<x> and B<y> co-ordinates for the point
B<p> defined over the curve given in B<group>.
As well as the affine co-ordinates, a point can alternatively be described in terms of its Jacobian
projective co-ordinates (for Fp curves only). Jacobian projective co-ordinates are expressed as three values x, y and z. Working in
this co-ordinate system provides more efficient point multiplication operations.
A mapping exists between Jacobian projective co-ordinates and affine co-ordinates. A Jacobian projective co-ordinate (x, y, z) can be written as an affine co-ordinate as (x/(z^2), y/(z^3)). Conversion to Jacobian projective to affine co-ordinates is simple. The co-ordinate (x, y) is
mapped to (x, y, 1). To set or get the projective co-ordinates use EC_POINT_set_Jprojective_coordinates_GFp and
EC_POINT_get_Jprojective_coordinates_GFp respectively.
Points can also be described in terms of their compressed co-ordinates. For a point (x, y), for any given value for x such that the point is
on the curve there will only ever be two possible values for y. Therefore a point can be set using the EC_POINT_set_compressed_coordinates_GFp
and EC_POINT_set_compressed_coordinates_GF2m functions where B<x> is the x co-ordinate and B<y_bit> is a value 0 or 1 to identify which of
the two possible values for y should be used.
In addition EC_POINTs can be converted to and from various external
representations. Supported representations are octet strings, BIGNUMs and
hexadecimal. Octet strings are stored in a buffer along with an associated
buffer length. A point held in a BIGNUM is calculated by converting the point to
an octet string and then converting that octet string into a BIGNUM integer.
Points in hexadecimal format are stored in a NULL terminated character string
where each character is one of the printable values 0-9 or A-F (or a-f).
The functions EC_POINT_point2oct, EC_POINT_oct2point, EC_POINT_point2bn, EC_POINT_bn2point, EC_POINT_point2hex and EC_POINT_hex2point convert
from and to EC_POINTs for the formats: octet string, BIGNUM and hexadecimal respectively.
The function EC_POINT_point2oct must be supplied with a buffer long enough to store the octet string. The return value provides the number of
octets stored. Calling the function with a NULL buffer will not perform the conversion but will still return the required buffer length.
The function EC_POINT_point2hex will allocate sufficient memory to store the hexadecimal string. It is the caller's responsibility to free
this memory with a subsequent call to OPENSSL_free().
=head1 RETURN VALUES
EC_POINT_new and EC_POINT_dup return the newly allocated EC_POINT or NULL on error.
The following functions return 1 on success or 0 on error: EC_POINT_copy, EC_POINT_set_to_infinity, EC_POINT_set_Jprojective_coordinates_GFp,
EC_POINT_get_Jprojective_coordinates_GFp, EC_POINT_set_affine_coordinates_GFp, EC_POINT_get_affine_coordinates_GFp,
EC_POINT_set_compressed_coordinates_GFp, EC_POINT_set_affine_coordinates_GF2m, EC_POINT_get_affine_coordinates_GF2m,
EC_POINT_set_compressed_coordinates_GF2m and EC_POINT_oct2point.
EC_POINT_method_of returns the EC_METHOD associated with the supplied EC_POINT.
EC_POINT_point2oct returns the length of the required buffer, or 0 on error.
EC_POINT_point2bn returns the pointer to the BIGNUM supplied, or NULL on error.
EC_POINT_bn2point returns the pointer to the EC_POINT supplied, or NULL on error.
EC_POINT_point2hex returns a pointer to the hex string, or NULL on error.
EC_POINT_hex2point returns the pointer to the EC_POINT supplied, or NULL on error.
=head1 SEE ALSO
L<crypto(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>, L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>,
L<EC_POINT_add(3)|EC_POINT_add(3)>, L<EC_KEY_new(3)|EC_KEY_new(3)>,
L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)>
=cut

9
doc/crypto/ERR_get_error.pod
View File

@@ -49,11 +49,14 @@ additionally store the file name and line number where
the error occurred in *B<file> and *B<line>, unless these are B<NULL>.
ERR_get_error_line_data(), ERR_peek_error_line_data() and
ERR_get_last_error_line_data() store additional data and flags
ERR_peek_last_error_line_data() store additional data and flags
associated with the error code in *B<data>
and *B<flags>, unless these are B<NULL>. *B<data> contains a string
if *B<flags>&B<ERR_TXT_STRING>. If it has been allocated by OPENSSL_malloc(),
*B<flags>&B<ERR_TXT_MALLOCED> is true.
if *B<flags>&B<ERR_TXT_STRING> is true.
An application B<MUST NOT> free the *B<data> pointer (or any other pointers
returned by these functions) with OPENSSL_free() as freeing is handled
automatically by the error library.
=head1 RETURN VALUES

21
doc/crypto/ERR_remove_state.pod
View File

@@ -2,26 +2,35 @@
=head1 NAME
ERR_remove_state - free a thread's error queue
ERR_remove_thread_state, ERR_remove_state - free a thread's error queue
=head1 SYNOPSIS
#include <openssl/err.h>
void ERR_remove_thread_state(const CRYPTO_THREADID *tid);
Deprecated:
void ERR_remove_state(unsigned long pid);
=head1 DESCRIPTION
ERR_remove_state() frees the error queue associated with thread B<pid>.
If B<pid> == 0, the current thread will have its error queue removed.
ERR_remove_thread_state() frees the error queue associated with thread B<tid>.
If B<tid> == B<NULL>, the current thread will have its error queue removed.
Since error queue data structures are allocated automatically for new
threads, they must be freed when threads are terminated in order to
avoid memory leaks.
ERR_remove_state is deprecated and has been replaced by
ERR_remove_thread_state. Since threads in OpenSSL are no longer identified
by unsigned long values any argument to this function is ignored. Calling
ERR_remove_state is equivalent to B<ERR_remove_thread_state(NULL)>.
=head1 RETURN VALUE
ERR_remove_state() returns no value.
ERR_remove_thread_state and ERR_remove_state() return no value.
=head1 SEE ALSO
@@ -29,6 +38,8 @@ L<err(3)|err(3)>
=head1 HISTORY
ERR_remove_state() is available in all versions of SSLeay and OpenSSL.
ERR_remove_state() is available in all versions of SSLeay and OpenSSL. It
was deprecated in OpenSSL 1.0.0 when ERR_remove_thread_state was introduced
and thread IDs were introduced to identify threads instead of 'unsigned long'.
=cut

11
doc/crypto/EVP_BytesToKey.pod
View File

@@ -17,7 +17,7 @@ EVP_BytesToKey - password based encryption routine
EVP_BytesToKey() derives a key and IV from various parameters. B<type> is
the cipher to derive the key and IV for. B<md> is the message digest to use.
The B<salt> paramter is used as a salt in the derivation: it should point to
The B<salt> parameter is used as a salt in the derivation: it should point to
an 8 byte buffer or NULL if no salt is used. B<data> is a buffer containing
B<datal> bytes which is used to derive the keying data. B<count> is the
iteration count to use. The derived key and IV will be written to B<key>
@@ -36,8 +36,8 @@ If the total key and IV length is less than the digest length and
B<MD5> is used then the derivation algorithm is compatible with PKCS#5 v1.5
otherwise a non standard extension is used to derive the extra data.
Newer applications should use more standard algorithms such as PKCS#5
v2.0 for key derivation.
Newer applications should use a more modern algorithm such as PBKDF2 as
defined in PKCS#5v2.1 and provided by PKCS5_PBKDF2_HMAC.
=head1 KEY DERIVATION ALGORITHM
@@ -55,7 +55,10 @@ the IV.
=head1 RETURN VALUES
EVP_BytesToKey() returns the size of the derived key in bytes.
If B<data> is NULL, then EVP_BytesToKey() returns the number of bytes
needed to store the derived key.
Otherwise, EVP_BytesToKey() returns the size of the derived key in bytes,
or 0 on error.
=head1 SEE ALSO

103
doc/crypto/EVP_DigestInit.pod
View File

@@ -4,9 +4,10 @@
EVP_MD_CTX_init, EVP_MD_CTX_create, EVP_DigestInit_ex, EVP_DigestUpdate,
EVP_DigestFinal_ex, EVP_MD_CTX_cleanup, EVP_MD_CTX_destroy, EVP_MAX_MD_SIZE,
EVP_MD_CTX_copy_ex, EVP_MD_CTX_copy, EVP_MD_type, EVP_MD_pkey_type, EVP_MD_size,
EVP_MD_block_size, EVP_MD_CTX_md, EVP_MD_CTX_size, EVP_MD_CTX_block_size, EVP_MD_CTX_type,
EVP_md_null, EVP_md2, EVP_md5, EVP_sha, EVP_sha1, EVP_dss, EVP_dss1, EVP_mdc2,
EVP_MD_CTX_copy_ex, EVP_DigestInit, EVP_DigestFinal, EVP_MD_CTX_copy, EVP_MD_type,
EVP_MD_pkey_type, EVP_MD_size, EVP_MD_block_size, EVP_MD_CTX_md, EVP_MD_CTX_size,
EVP_MD_CTX_block_size, EVP_MD_CTX_type, EVP_md_null, EVP_md2, EVP_md5, EVP_sha, EVP_sha1,
EVP_sha224, EVP_sha256, EVP_sha384, EVP_sha512, EVP_dss, EVP_dss1, EVP_mdc2,
EVP_ripemd160, EVP_get_digestbyname, EVP_get_digestbynid, EVP_get_digestbyobj -
EVP digest routines
@@ -25,24 +26,23 @@ EVP digest routines
int EVP_MD_CTX_cleanup(EVP_MD_CTX *ctx);
void EVP_MD_CTX_destroy(EVP_MD_CTX *ctx);
int EVP_MD_CTX_copy_ex(EVP_MD_CTX *out,const EVP_MD_CTX *in);
int EVP_MD_CTX_copy_ex(EVP_MD_CTX *out,const EVP_MD_CTX *in);
int EVP_DigestInit(EVP_MD_CTX *ctx, const EVP_MD *type);
int EVP_DigestFinal(EVP_MD_CTX *ctx, unsigned char *md,
unsigned int *s);
int EVP_MD_CTX_copy(EVP_MD_CTX *out,EVP_MD_CTX *in);
int EVP_MD_CTX_copy(EVP_MD_CTX *out,EVP_MD_CTX *in);
#define EVP_MAX_MD_SIZE (16+20) /* The SSLv3 md5+sha1 type */
#define EVP_MAX_MD_SIZE 64 /* SHA512 */
int EVP_MD_type(const EVP_MD *md);
int EVP_MD_pkey_type(const EVP_MD *md);
int EVP_MD_size(const EVP_MD *md);
int EVP_MD_block_size(const EVP_MD *md);
#define EVP_MD_type(e) ((e)->type)
#define EVP_MD_pkey_type(e) ((e)->pkey_type)
#define EVP_MD_size(e) ((e)->md_size)
#define EVP_MD_block_size(e) ((e)->block_size)
#define EVP_MD_CTX_md(e) (e)->digest)
#define EVP_MD_CTX_size(e) EVP_MD_size((e)->digest)
const EVP_MD *EVP_MD_CTX_md(const EVP_MD_CTX *ctx);
#define EVP_MD_CTX_size(e) EVP_MD_size(EVP_MD_CTX_md(e))
#define EVP_MD_CTX_block_size(e) EVP_MD_block_size((e)->digest)
#define EVP_MD_CTX_type(e) EVP_MD_type((e)->digest)
@@ -56,6 +56,11 @@ EVP digest routines
const EVP_MD *EVP_mdc2(void);
const EVP_MD *EVP_ripemd160(void);
const EVP_MD *EVP_sha224(void);
const EVP_MD *EVP_sha256(void);
const EVP_MD *EVP_sha384(void);
const EVP_MD *EVP_sha512(void);
const EVP_MD *EVP_get_digestbyname(const char *name);
#define EVP_get_digestbynid(a) EVP_get_digestbyname(OBJ_nid2sn(a))
#define EVP_get_digestbyobj(a) EVP_get_digestbynid(OBJ_obj2nid(a))
@@ -124,15 +129,17 @@ B<EVP_MD_CTX>.
EVP_MD_pkey_type() returns the NID of the public key signing algorithm associated
with this digest. For example EVP_sha1() is associated with RSA so this will
return B<NID_sha1WithRSAEncryption>. This "link" between digests and signature
algorithms may not be retained in future versions of OpenSSL.
return B<NID_sha1WithRSAEncryption>. Since digests and signature algorithms
are no longer linked this function is only retained for compatibility
reasons.
EVP_md2(), EVP_md5(), EVP_sha(), EVP_sha1(), EVP_mdc2() and EVP_ripemd160()
return B<EVP_MD> structures for the MD2, MD5, SHA, SHA1, MDC2 and RIPEMD160 digest
algorithms respectively. The associated signature algorithm is RSA in each case.
EVP_md2(), EVP_md5(), EVP_sha(), EVP_sha1(), EVP_sha224(), EVP_sha256(),
EVP_sha384(), EVP_sha512(), EVP_mdc2() and EVP_ripemd160() return B<EVP_MD>
structures for the MD2, MD5, SHA, SHA1, SHA224, SHA256, SHA384, SHA512, MDC2
and RIPEMD160 digest algorithms respectively.
EVP_dss() and EVP_dss1() return B<EVP_MD> structures for SHA and SHA1 digest
algorithms but using DSS (DSA) for the signature algorithm. Note: there is
algorithms but using DSS (DSA) for the signature algorithm. Note: there is
no need to use these pseudo-digests in OpenSSL 1.0.0 and later, they are
however retained for compatibility.
@@ -154,9 +161,8 @@ EVP_MD_CTX_copy_ex() returns 1 if successful or 0 for failure.
EVP_MD_type(), EVP_MD_pkey_type() and EVP_MD_type() return the NID of the
corresponding OBJECT IDENTIFIER or NID_undef if none exists.
EVP_MD_size(), EVP_MD_block_size(), EVP_MD_CTX_size(e), EVP_MD_size(),
EVP_MD_CTX_block_size() and EVP_MD_block_size() return the digest or block
size in bytes.
EVP_MD_size(), EVP_MD_block_size(), EVP_MD_CTX_size() and
EVP_MD_CTX_block_size() return the digest or block size in bytes.
EVP_md_null(), EVP_md2(), EVP_md5(), EVP_sha(), EVP_sha1(), EVP_dss(),
EVP_dss1(), EVP_mdc2() and EVP_ripemd160() return pointers to the
@@ -171,21 +177,34 @@ The B<EVP> interface to message digests should almost always be used in
preference to the low level interfaces. This is because the code then becomes
transparent to the digest used and much more flexible.
SHA1 is the digest of choice for new applications. The other digest algorithms
are still in common use.
New applications should use the SHA2 digest algorithms such as SHA256.
The other digest algorithms are still in common use.
For most applications the B<impl> parameter to EVP_DigestInit_ex() will be
set to NULL to use the default digest implementation.
The functions EVP_DigestInit(), EVP_DigestFinal() and EVP_MD_CTX_copy() are
The functions EVP_DigestInit(), EVP_DigestFinal() and EVP_MD_CTX_copy() are
obsolete but are retained to maintain compatibility with existing code. New
applications should use EVP_DigestInit_ex(), EVP_DigestFinal_ex() and
applications should use EVP_DigestInit_ex(), EVP_DigestFinal_ex() and
EVP_MD_CTX_copy_ex() because they can efficiently reuse a digest context
instead of initializing and cleaning it up on each call and allow non default
implementations of digests to be specified.
In OpenSSL 0.9.7 and later if digest contexts are not cleaned up after use
memory leaks will occur.
memory leaks will occur.
Stack allocation of EVP_MD_CTX structures is common, for example:
EVP_MD_CTX mctx;
EVP_MD_CTX_init(&mctx);
This will cause binary compatibility issues if the size of EVP_MD_CTX
structure changes (this will only happen with a major release of OpenSSL).
Applications wishing to avoid this should use EVP_MD_CTX_create() instead:
EVP_MD_CTX *mctx;
mctx = EVP_MD_CTX_create();
=head1 EXAMPLE
@@ -197,7 +216,7 @@ digest name passed on the command line.
main(int argc, char *argv[])
{
EVP_MD_CTX mdctx;
EVP_MD_CTX *mdctx;
const EVP_MD *md;
char mess1[] = "Test Message\n";
char mess2[] = "Hello World\n";
@@ -218,23 +237,27 @@ digest name passed on the command line.
exit(1);
}
EVP_MD_CTX_init(&mdctx);
EVP_DigestInit_ex(&mdctx, md, NULL);
EVP_DigestUpdate(&mdctx, mess1, strlen(mess1));
EVP_DigestUpdate(&mdctx, mess2, strlen(mess2));
EVP_DigestFinal_ex(&mdctx, md_value, &md_len);
EVP_MD_CTX_cleanup(&mdctx);
mdctx = EVP_MD_CTX_create();
EVP_DigestInit_ex(mdctx, md, NULL);
EVP_DigestUpdate(mdctx, mess1, strlen(mess1));
EVP_DigestUpdate(mdctx, mess2, strlen(mess2));
EVP_DigestFinal_ex(mdctx, md_value, &md_len);
EVP_MD_CTX_destroy(mdctx);
printf("Digest is: ");
for(i = 0; i < md_len; i++) printf("%02x", md_value[i]);
for(i = 0; i < md_len; i++)
printf("%02x", md_value[i]);
printf("\n");
/* Call this once before exit. */
EVP_cleanup();
exit(0);
}
=head1 SEE ALSO
L<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>,
L<md5(3)|md5(3)>, L<mdc2(3)|mdc2(3)>, L<ripemd(3)|ripemd(3)>,
L<sha(3)|sha(3)>, L<dgst(1)|dgst(1)>
L<dgst(1)|dgst(1)>,
L<evp(3)|evp(3)>
=head1 HISTORY
@@ -247,10 +270,10 @@ and EVP_DigestFinal_ex() were added in OpenSSL 0.9.7.
EVP_md_null(), EVP_md2(), EVP_md5(), EVP_sha(), EVP_sha1(),
EVP_dss(), EVP_dss1(), EVP_mdc2() and EVP_ripemd160() were
changed to return truely const EVP_MD * in OpenSSL 0.9.7.
changed to return truly const EVP_MD * in OpenSSL 0.9.7.
The link between digests and signing algorithms was fixed in OpenSSL 1.0 and
later, so now EVP_sha1() can be used with RSA and DSA, there is no need to
later, so now EVP_sha1() can be used with RSA and DSA; there is no need to
use EVP_dss1() any more.
OpenSSL 1.0 and later does not include the MD2 digest algorithm in the

6
doc/crypto/EVP_DigestVerifyInit.pod
View File

@@ -11,7 +11,7 @@ EVP_DigestVerifyInit, EVP_DigestVerifyUpdate, EVP_DigestVerifyFinal - EVP signat
int EVP_DigestVerifyInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx,
const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey);
int EVP_DigestVerifyUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt);
int EVP_DigestVerifyFinal(EVP_MD_CTX *ctx, unsigned char *sig, size_t siglen);
int EVP_DigestVerifyFinal(EVP_MD_CTX *ctx, const unsigned char *sig, size_t siglen);
=head1 DESCRIPTION
@@ -38,7 +38,7 @@ or a negative value for failure. In particular a return value of -2 indicates
the operation is not supported by the public key algorithm.
Unlike other functions the return value 0 from EVP_DigestVerifyFinal() only
indicates that the signature did not not verify successfully (that is tbs did
indicates that the signature did not verify successfully (that is tbs did
not match the original data or the signature was of invalid form) it is not an
indication of a more serious error.
@@ -59,7 +59,7 @@ For some key types and parameters the random number generator must be seeded
or the operation will fail.
The call to EVP_DigestVerifyFinal() internally finalizes a copy of the digest
context. This means that calls to EVP_VerifyUpdate() and EVP_VerifyFinal() can
context. This means that EVP_VerifyUpdate() and EVP_VerifyFinal() can
be called later to digest and verify additional data.
Since only a copy of the digest context is ever finalized the context must

160
doc/crypto/EVP_EncryptInit.pod
View File

@@ -16,7 +16,17 @@ EVP_CIPHER_CTX_nid, EVP_CIPHER_CTX_block_size, EVP_CIPHER_CTX_key_length,
EVP_CIPHER_CTX_iv_length, EVP_CIPHER_CTX_get_app_data,
EVP_CIPHER_CTX_set_app_data, EVP_CIPHER_CTX_type, EVP_CIPHER_CTX_flags,
EVP_CIPHER_CTX_mode, EVP_CIPHER_param_to_asn1, EVP_CIPHER_asn1_to_param,
EVP_CIPHER_CTX_set_padding - EVP cipher routines
EVP_CIPHER_CTX_set_padding, EVP_enc_null, EVP_des_cbc, EVP_des_ecb,
EVP_des_cfb, EVP_des_ofb, EVP_des_ede_cbc, EVP_des_ede, EVP_des_ede_ofb,
EVP_des_ede_cfb, EVP_des_ede3_cbc, EVP_des_ede3, EVP_des_ede3_ofb,
EVP_des_ede3_cfb, EVP_desx_cbc, EVP_rc4, EVP_rc4_40, EVP_idea_cbc,
EVP_idea_ecb, EVP_idea_cfb, EVP_idea_ofb, EVP_idea_cbc, EVP_rc2_cbc,
EVP_rc2_ecb, EVP_rc2_cfb, EVP_rc2_ofb, EVP_rc2_40_cbc, EVP_rc2_64_cbc,
EVP_bf_cbc, EVP_bf_ecb, EVP_bf_cfb, EVP_bf_ofb, EVP_cast5_cbc,
EVP_cast5_ecb, EVP_cast5_cfb, EVP_cast5_ofb, EVP_rc5_32_12_16_cbc,
EVP_rc5_32_12_16_ecb, EVP_rc5_32_12_16_cfb, EVP_rc5_32_12_16_ofb,
EVP_aes_128_gcm, EVP_aes_192_gcm, EVP_aes_256_gcm, EVP_aes_128_ccm,
EVP_aes_192_ccm, EVP_aes_256_ccm - EVP cipher routines
=head1 SYNOPSIS
@@ -115,7 +125,7 @@ writes the encrypted version to B<out>. This function can be called
multiple times to encrypt successive blocks of data. The amount
of data written depends on the block alignment of the encrypted data:
as a result the amount of data written may be anything from zero bytes
to (inl + cipher_block_size - 1) so B<outl> should contain sufficient
to (inl + cipher_block_size - 1) so B<out> should contain sufficient
room. The actual number of bytes written is placed in B<outl>.
If padding is enabled (the default) then EVP_EncryptFinal_ex() encrypts
@@ -152,7 +162,7 @@ does not remain in memory.
EVP_EncryptInit(), EVP_DecryptInit() and EVP_CipherInit() behave in a
similar way to EVP_EncryptInit_ex(), EVP_DecryptInit_ex and
EVP_CipherInit_ex() except the B<ctx> paramter does not need to be
EVP_CipherInit_ex() except the B<ctx> parameter does not need to be
initialized and they always use the default cipher implementation.
EVP_EncryptFinal(), EVP_DecryptFinal() and EVP_CipherFinal() behave in a
@@ -231,8 +241,7 @@ or the parameters cannot be set (for example the RC2 effective key length
is not supported.
EVP_CIPHER_CTX_ctrl() allows various cipher specific parameters to be determined
and set. Currently only the RC2 effective key length and the number of rounds of
RC5 can be set.
and set.
=head1 RETURN VALUES
@@ -338,13 +347,96 @@ RC5 encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a
cipher with an additional "number of rounds" parameter. By default the key length is set to 128
bits and 12 rounds.
=item EVP_aes_128_gcm(void), EVP_aes_192_gcm(void), EVP_aes_256_gcm(void)
AES Galois Counter Mode (GCM) for 128, 192 and 256 bit keys respectively.
These ciphers require additional control operations to function correctly: see
L<GCM mode> section below for details.
=item EVP_aes_128_ccm(void), EVP_aes_192_ccm(void), EVP_aes_256_ccm(void)
AES Counter with CBC-MAC Mode (CCM) for 128, 192 and 256 bit keys respectively.
These ciphers require additional control operations to function correctly: see
CCM mode section below for details.
=back
=head1 GCM Mode
For GCM mode ciphers the behaviour of the EVP interface is subtly altered and
several GCM specific ctrl operations are supported.
To specify any additional authenticated data (AAD) a call to EVP_CipherUpdate(),
EVP_EncryptUpdate() or EVP_DecryptUpdate() should be made with the output
parameter B<out> set to B<NULL>.
When decrypting the return value of EVP_DecryptFinal() or EVP_CipherFinal()
indicates if the operation was successful. If it does not indicate success
the authentication operation has failed and any output data B<MUST NOT>
be used as it is corrupted.
The following ctrls are supported in GCM mode:
EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_SET_IVLEN, ivlen, NULL);
Sets the GCM IV length: this call can only be made before specifying an IV. If
not called a default IV length is used (96 bits for AES).
EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_GET_TAG, taglen, tag);
Writes B<taglen> bytes of the tag value to the buffer indicated by B<tag>.
This call can only be made when encrypting data and B<after> all data has been
processed (e.g. after an EVP_EncryptFinal() call).
EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_SET_TAG, taglen, tag);
Sets the expected tag to B<taglen> bytes from B<tag>. This call is only legal
when decrypting data and must be made B<before> any data is processed (e.g.
before any EVP_DecryptUpdate() call).
See L<EXAMPLES> below for an example of the use of GCM mode.
=head1 CCM Mode
The behaviour of CCM mode ciphers is similar to CCM mode but with a few
additional requirements and different ctrl values.
Like GCM mode any additional authenticated data (AAD) is passed by calling
EVP_CipherUpdate(), EVP_EncryptUpdate() or EVP_DecryptUpdate() with the output
parameter B<out> set to B<NULL>. Additionally the total plaintext or ciphertext
length B<MUST> be passed to EVP_CipherUpdate(), EVP_EncryptUpdate() or
EVP_DecryptUpdate() with the output and input parameters (B<in> and B<out>)
set to B<NULL> and the length passed in the B<inl> parameter.
The following ctrls are supported in CCM mode:
EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_TAG, taglen, tag);
This call is made to set the expected B<CCM> tag value when decrypting or
the length of the tag (with the B<tag> parameter set to NULL) when encrypting.
The tag length is often referred to as B<M>. If not set a default value is
used (12 for AES).
EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_L, ivlen, NULL);
Sets the CCM B<L> value. If not set a default is used (8 for AES).
EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_IVLEN, ivlen, NULL);
Sets the CCM nonce (IV) length: this call can only be made before specifying
an nonce value. The nonce length is given by B<15 - L> so it is 7 by default
for AES.
=head1 NOTES
Where possible the B<EVP> interface to symmetric ciphers should be used in
preference to the low level interfaces. This is because the code then becomes
transparent to the cipher used and much more flexible.
transparent to the cipher used and much more flexible. Additionally, the
B<EVP> interface will ensure the use of platform specific cryptographic
acceleration such as AES-NI (the low level interfaces do not provide the
guarantee).
PKCS padding works by adding B<n> padding bytes of value B<n> to make the total
length of the encrypted data a multiple of the block size. Padding is always
@@ -384,27 +476,7 @@ for certain common S/MIME ciphers (RC2, DES, triple DES) in CBC mode.
=head1 EXAMPLES
Get the number of rounds used in RC5:
int nrounds;
EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_RC5_ROUNDS, 0, &nrounds);
Get the RC2 effective key length:
int key_bits;
EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_RC2_KEY_BITS, 0, &key_bits);
Set the number of rounds used in RC5:
int nrounds;
EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_RC5_ROUNDS, nrounds, NULL);
Set the effective key length used in RC2:
int key_bits;
EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_RC2_KEY_BITS, key_bits, NULL);
Encrypt a string using blowfish:
Encrypt a string using IDEA:
int do_crypt(char *outfile)
{
@@ -418,8 +490,9 @@ Encrypt a string using blowfish:
char intext[] = "Some Crypto Text";
EVP_CIPHER_CTX ctx;
FILE *out;
EVP_CIPHER_CTX_init(&ctx);
EVP_EncryptInit_ex(&ctx, EVP_bf_cbc(), NULL, key, iv);
EVP_EncryptInit_ex(&ctx, EVP_idea_cbc(), NULL, key, iv);
if(!EVP_EncryptUpdate(&ctx, outbuf, &outlen, intext, strlen(intext)))
{
@@ -448,28 +521,34 @@ Encrypt a string using blowfish:
}
The ciphertext from the above example can be decrypted using the B<openssl>
utility with the command line:
utility with the command line (shown on two lines for clarity):
S<openssl bf -in cipher.bin -K 000102030405060708090A0B0C0D0E0F -iv 0102030405060708 -d>
openssl idea -d <filename
-K 000102030405060708090A0B0C0D0E0F -iv 0102030405060708
General encryption, decryption function example using FILE I/O and RC2 with an
80 bit key:
General encryption and decryption function example using FILE I/O and AES128
with a 128-bit key:
int do_crypt(FILE *in, FILE *out, int do_encrypt)
{
/* Allow enough space in output buffer for additional block */
inbuf[1024], outbuf[1024 + EVP_MAX_BLOCK_LENGTH];
unsigned char inbuf[1024], outbuf[1024 + EVP_MAX_BLOCK_LENGTH];
int inlen, outlen;
EVP_CIPHER_CTX ctx;
/* Bogus key and IV: we'd normally set these from
* another source.
*/
unsigned char key[] = "0123456789";
unsigned char iv[] = "12345678";
/* Don't set key or IV because we will modify the parameters */
unsigned char key[] = "0123456789abcdeF";
unsigned char iv[] = "1234567887654321";
/* Don't set key or IV right away; we want to check lengths */
EVP_CIPHER_CTX_init(&ctx);
EVP_CipherInit_ex(&ctx, EVP_rc2(), NULL, NULL, NULL, do_encrypt);
EVP_CIPHER_CTX_set_key_length(&ctx, 10);
/* We finished modifying parameters so now we can set key and IV */
EVP_CipherInit_ex(&ctx, EVP_aes_128_cbc(), NULL, NULL, NULL,
do_encrypt);
OPENSSL_assert(EVP_CIPHER_CTX_key_length(&ctx) == 16);
OPENSSL_assert(EVP_CIPHER_CTX_iv_length(&ctx) == 16);
/* Now we can set key and IV */
EVP_CipherInit_ex(&ctx, NULL, NULL, key, iv, do_encrypt);
for(;;)
@@ -508,4 +587,7 @@ EVP_DecryptInit_ex(), EVP_DecryptFinal_ex(), EVP_CipherInit_ex(),
EVP_CipherFinal_ex() and EVP_CIPHER_CTX_set_padding() appeared in
OpenSSL 0.9.7.
IDEA appeared in OpenSSL 0.9.7 but was often disabled due to
patent concerns; the last patents expired in 2012.
=cut

12
doc/crypto/EVP_PKEY_CTX_ctrl.pod
View File

@@ -2,7 +2,13 @@
=head1 NAME
EVP_PKEY_ctrl, EVP_PKEY_ctrl_str - algorithm specific control operations
EVP_PKEY_CTX_ctrl, EVP_PKEY_CTX_ctrl_str, EVP_PKEY_get_default_digest_nid,
EVP_PKEY_CTX_set_signature_md, EVP_PKEY_CTX_set_rsa_padding,
EVP_PKEY_CTX_set_rsa_pss_saltlen, EVP_PKEY_CTX_set_rsa_rsa_keygen_bits,
EVP_PKEY_CTX_set_rsa_keygen_pubexp, EVP_PKEY_CTX_set_dsa_paramgen_bits,
EVP_PKEY_CTX_set_dh_paramgen_prime_len,
EVP_PKEY_CTX_set_dh_paramgen_generator,
EVP_PKEY_CTX_set_ec_paramgen_curve_nid - algorithm specific control operations
=head1 SYNOPSIS
@@ -45,7 +51,7 @@ B<p1> and B<p2>.
Applications will not normally call EVP_PKEY_CTX_ctrl() directly but will
instead call one of the algorithm specific macros below.
The function EVP_PKEY_ctrl_str() allows an application to send an algorithm
The function EVP_PKEY_CTX_ctrl_str() allows an application to send an algorithm
specific control operation to a context B<ctx> in string form. This is
intended to be used for options specified on the command line or in text
files. The commands supported are documented in the openssl utility
@@ -117,7 +123,7 @@ L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>,
L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>,
L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>,
L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>,
L<EVP_PKEY_verifyrecover(3)|EVP_PKEY_verifyrecover(3)>,
L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>,
L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)>
L<EVP_PKEY_keygen(3)|EVP_PKEY_keygen(3)>

4
doc/crypto/EVP_PKEY_cmp.pod
View File

@@ -23,10 +23,10 @@ doesn't use parameters.
The function EVP_PKEY_copy_parameters() copies the parameters from key
B<from> to key B<to>.
The funcion EVP_PKEY_cmp_parameters() compares the parameters of keys
The function EVP_PKEY_cmp_parameters() compares the parameters of keys
B<a> and B<b>.
The funcion EVP_PKEY_cmp() compares the public key components and paramters
The function EVP_PKEY_cmp() compares the public key components and paramters
(if present) of keys B<a> and B<b>.
=head1 NOTES

2
doc/crypto/EVP_PKEY_decrypt.pod
View File

@@ -83,7 +83,7 @@ L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>,
L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>,
L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>,
L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>,
L<EVP_PKEY_verifyrecover(3)|EVP_PKEY_verifyrecover(3)>,
L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>,
L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)>
=head1 HISTORY

2
doc/crypto/EVP_PKEY_derive.pod
View File

@@ -84,7 +84,7 @@ L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>,
L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>,
L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>,
L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>,
L<EVP_PKEY_verifyrecover(3)|EVP_PKEY_verifyrecover(3)>,
L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>,
=head1 HISTORY

14
doc/crypto/EVP_PKEY_encrypt.pod
View File

@@ -43,19 +43,23 @@ indicates the operation is not supported by the public key algorithm.
=head1 EXAMPLE
Encrypt data using OAEP (for RSA keys):
Encrypt data using OAEP (for RSA keys). See also L<PEM_read_PUBKEY(3)|pem(3)> or
L<d2i_X509(3)|d2i_X509(3)> for means to load a public key. You may also simply
set 'eng = NULL;' to start with the default OpenSSL RSA implementation:
#include <openssl/evp.h>
#include <openssl/rsa.h>
#include <openssl/engine.h>
EVP_PKEY_CTX *ctx;
ENGINE *eng;
unsigned char *out, *in;
size_t outlen, inlen;
EVP_PKEY *key;
/* NB: assumes key in, inlen are already set up
/* NB: assumes eng, key, in, inlen are already set up,
* and that key is an RSA public key
*/
ctx = EVP_PKEY_CTX_new(key);
ctx = EVP_PKEY_CTX_new(key,eng);
if (!ctx)
/* Error occurred */
if (EVP_PKEY_encrypt_init(ctx) <= 0)
@@ -79,11 +83,13 @@ Encrypt data using OAEP (for RSA keys):
=head1 SEE ALSO
L<d2i_X509(3)|d2i_X509(3)>,
L<engine(3)|engine(3)>,
L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>,
L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>,
L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>,
L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>,
L<EVP_PKEY_verifyrecover(3)|EVP_PKEY_verifyrecover(3)>,
L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>,
L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)>
=head1 HISTORY

2
doc/crypto/EVP_PKEY_get_default_digest.pod
View File

@@ -32,7 +32,7 @@ public key algorithm.
L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>,
L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>,
L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>,
L<EVP_PKEY_verifyrecover(3)|EVP_PKEY_verifyrecover(3)>,
L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>,
=head1 HISTORY

2
doc/crypto/EVP_PKEY_keygen.pod
View File

@@ -151,7 +151,7 @@ L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>,
L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>,
L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>,
L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>,
L<EVP_PKEY_verifyrecover(3)|EVP_PKEY_verifyrecover(3)>,
L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>,
L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)>
=head1 HISTORY

8
doc/crypto/EVP_PKEY_set1_RSA.pod
View File

@@ -37,7 +37,7 @@ EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and
EVP_PKEY_get1_EC_KEY() return the referenced key in B<pkey> or
B<NULL> if the key is not of the correct type.
EVP_PKEY_assign_RSA() EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH()
EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH()
and EVP_PKEY_assign_EC_KEY() also set the referenced key to B<key>
however these use the supplied B<key> internally and so B<key>
will be freed when the parent B<pkey> is freed.
@@ -54,8 +54,8 @@ In accordance with the OpenSSL naming convention the key obtained
from or assigned to the B<pkey> using the B<1> functions must be
freed as well as B<pkey>.
EVP_PKEY_assign_RSA() EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH()
EVP_PKEY_assign_EC_KEY() are implemented as macros.
EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH()
and EVP_PKEY_assign_EC_KEY() are implemented as macros.
=head1 RETURN VALUES
@@ -66,7 +66,7 @@ EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and
EVP_PKEY_get1_EC_KEY() return the referenced key or B<NULL> if
an error occurred.
EVP_PKEY_assign_RSA() EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH()
EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH()
and EVP_PKEY_assign_EC_KEY() return 1 for success and 0 for failure.
=head1 SEE ALSO

22
doc/crypto/EVP_PKEY_sign.pod
View File

@@ -28,9 +28,14 @@ B<sig> and the amount of data written to B<siglen>.
=head1 NOTES
EVP_PKEY_sign() does not hash the data to be signed, and therefore is
normally used to sign digests. For signing arbitrary messages, see the
L<EVP_DigestSignInit(3)|EVP_DigestSignInit(3)> and
L<EVP_SignInit(3)|EVP_SignInit(3)> signing interfaces instead.
After the call to EVP_PKEY_sign_init() algorithm specific control
operations can be performed to set any appropriate parameters for the
operation.
operation (see L<EVP_PKEY_CTX_ctrl(3)|EVP_PKEY_CTX_ctrl(3)>).
The function EVP_PKEY_sign() can be called more than once on the same
context if several operations are performed using the same parameters.
@@ -49,13 +54,17 @@ Sign data using RSA with PKCS#1 padding and SHA256 digest:
#include <openssl/rsa.h>
EVP_PKEY_CTX *ctx;
/* md is a SHA-256 digest in this example. */
unsigned char *md, *sig;
size_t mdlen, siglen;
size_t mdlen = 32, siglen;
EVP_PKEY *signing_key;
/* NB: assumes signing_key, md and mdlen are already set up
* and that signing_key is an RSA private key
/*
* NB: assumes signing_key and md are set up before the next
* step. signing_key must be an RSA private key and md must
* point to the SHA-256 digest to be signed.
*/
ctx = EVP_PKEY_CTX_new(signing_key);
ctx = EVP_PKEY_CTX_new(signing_key, NULL /* no engine */);
if (!ctx)
/* Error occurred */
if (EVP_PKEY_sign_init(ctx) <= 0)
@@ -83,10 +92,11 @@ Sign data using RSA with PKCS#1 padding and SHA256 digest:
=head1 SEE ALSO
L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>,
L<EVP_PKEY_CTX_ctrl(3)|EVP_PKEY_CTX_ctrl(3)>,
L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>,
L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>,
L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>,
L<EVP_PKEY_verifyrecover(3)|EVP_PKEY_verifyrecover(3)>,
L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>,
L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)>
=head1 HISTORY

2
doc/crypto/EVP_PKEY_verify.pod
View File

@@ -81,7 +81,7 @@ L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>,
L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>,
L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>,
L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>,
L<EVP_PKEY_verifyrecover(3)|EVP_PKEY_verifyrecover(3)>,
L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>,
L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)>
=head1 HISTORY

103
doc/crypto/EVP_PKEY_verify_recover.pod Normal file
View File

@@ -0,0 +1,103 @@
=pod
=head1 NAME
EVP_PKEY_verify_recover_init, EVP_PKEY_verify_recover - recover signature using a public key algorithm
=head1 SYNOPSIS
#include <openssl/evp.h>
int EVP_PKEY_verify_recover_init(EVP_PKEY_CTX *ctx);
int EVP_PKEY_verify_recover(EVP_PKEY_CTX *ctx,
unsigned char *rout, size_t *routlen,
const unsigned char *sig, size_t siglen);
=head1 DESCRIPTION
The EVP_PKEY_verify_recover_init() function initializes a public key algorithm
context using key B<pkey> for a verify recover operation.
The EVP_PKEY_verify_recover() function recovers signed data
using B<ctx>. The signature is specified using the B<sig> and
B<siglen> parameters. If B<rout> is B<NULL> then the maximum size of the output
buffer is written to the B<routlen> parameter. If B<rout> is not B<NULL> then
before the call the B<routlen> parameter should contain the length of the
B<rout> buffer, if the call is successful recovered data is written to
B<rout> and the amount of data written to B<routlen>.
=head1 NOTES
Normally an application is only interested in whether a signature verification
operation is successful in those cases the EVP_verify() function should be
used.
Sometimes however it is useful to obtain the data originally signed using a
signing operation. Only certain public key algorithms can recover a signature
in this way (for example RSA in PKCS padding mode).
After the call to EVP_PKEY_verify_recover_init() algorithm specific control
operations can be performed to set any appropriate parameters for the
operation.
The function EVP_PKEY_verify_recover() can be called more than once on the same
context if several operations are performed using the same parameters.
=head1 RETURN VALUES
EVP_PKEY_verify_recover_init() and EVP_PKEY_verify_recover() return 1 for success
and 0 or a negative value for failure. In particular a return value of -2
indicates the operation is not supported by the public key algorithm.
=head1 EXAMPLE
Recover digest originally signed using PKCS#1 and SHA256 digest:
#include <openssl/evp.h>
#include <openssl/rsa.h>
EVP_PKEY_CTX *ctx;
unsigned char *rout, *sig;
size_t routlen, siglen;
EVP_PKEY *verify_key;
/* NB: assumes verify_key, sig and siglen are already set up
* and that verify_key is an RSA public key
*/
ctx = EVP_PKEY_CTX_new(verify_key);
if (!ctx)
/* Error occurred */
if (EVP_PKEY_verify_recover_init(ctx) <= 0)
/* Error */
if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_PADDING) <= 0)
/* Error */
if (EVP_PKEY_CTX_set_signature_md(ctx, EVP_sha256()) <= 0)
/* Error */
/* Determine buffer length */
if (EVP_PKEY_verify_recover(ctx, NULL, &routlen, sig, siglen) <= 0)
/* Error */
rout = OPENSSL_malloc(routlen);
if (!rout)
/* malloc failure */
if (EVP_PKEY_verify_recover(ctx, rout, &routlen, sig, siglen) <= 0)
/* Error */
/* Recovered data is routlen bytes written to buffer rout */
=head1 SEE ALSO
L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>,
L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>,
L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>,
L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>,
L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>,
L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)>
=head1 HISTORY
These functions were first added to OpenSSL 1.0.0.
=cut

8
doc/crypto/EVP_SignInit.pod
View File

@@ -30,9 +30,11 @@ signature context B<ctx>. This function can be called several times on the
same B<ctx> to include additional data.
EVP_SignFinal() signs the data in B<ctx> using the private key B<pkey> and
places the signature in B<sig>. The number of bytes of data written (i.e. the
length of the signature) will be written to the integer at B<s>, at most
EVP_PKEY_size(pkey) bytes will be written.
places the signature in B<sig>. B<sig> must be at least EVP_PKEY_size(pkey)
bytes in size. B<s> is an OUT paramter, and not used as an IN parameter.
The number of bytes of data written (i.e. the length of the signature)
will be written to the integer at B<s>, at most EVP_PKEY_size(pkey) bytes
will be written.
EVP_SignInit() initializes a signing context B<ctx> to use the default
implementation of digest B<type>.

2
doc/crypto/OPENSSL_VERSION_NUMBER.pod
View File

@@ -17,7 +17,7 @@ OPENSSL_VERSION_NUMBER, SSLeay, SSLeay_version - get OpenSSL version number
OPENSSL_VERSION_NUMBER is a numeric release version identifier:
MMNNFFPPS: major minor fix patch status
MNNFFPPS: major minor fix patch status
The status nibble has one of the values 0 for development, 1 to e for betas
1 to 14, and f for release.

44
doc/crypto/OPENSSL_config.pod
View File

@@ -15,31 +15,24 @@ OPENSSL_config, OPENSSL_no_config - simple OpenSSL configuration functions
OPENSSL_config() configures OpenSSL using the standard B<openssl.cnf>
configuration file name using B<config_name>. If B<config_name> is NULL then
the default name B<openssl_conf> will be used. Any errors are ignored. Further
calls to OPENSSL_config() will have no effect. The configuration file format
is documented in the L<conf(5)|conf(5)> manual page.
the file specified in the environment variable B<OPENSSL_CONF> will be used,
and if that is not set then a system default location is used.
Errors are silently ignored.
Multiple calls have no effect.
OPENSSL_no_config() disables configuration. If called before OPENSSL_config()
no configuration takes place.
=head1 NOTES
It is B<strongly> recommended that B<all> new applications call OPENSSL_config()
or the more sophisticated functions such as CONF_modules_load() during
initialization (that is before starting any threads). By doing this
an application does not need to keep track of all configuration options
and some new functionality can be supported automatically.
It is also possible to automatically call OPENSSL_config() when an application
calls OPENSSL_add_all_algorithms() by compiling an application with the
preprocessor symbol B<OPENSSL_LOAD_CONF> #define'd. In this way configuration
can be added without source changes.
The environment variable B<OPENSSL_CONF> can be set to specify the location
of the configuration file.
Currently ASN1 OBJECTs and ENGINE configuration can be performed future
versions of OpenSSL will add new configuration options.
The OPENSSL_config() function is designed to be a very simple "call it and
forget it" function.
It is however B<much> better than nothing. Applications which need finer
control over their configuration functionality should use the configuration
functions such as CONF_modules_load() directly. This function is deprecated
and its use should be avoided.
Applications should instead call CONF_modules_load() during
initialization (that is before starting any threads).
There are several reasons why calling the OpenSSL configuration routines is
advisable. For example new ENGINE functionality was added to OpenSSL 0.9.7.
@@ -55,17 +48,6 @@ configuration file.
Applications should free up configuration at application closedown by calling
CONF_modules_free().
=head1 RESTRICTIONS
The OPENSSL_config() function is designed to be a very simple "call it and
forget it" function. As a result its behaviour is somewhat limited. It ignores
all errors silently and it can only load from the standard configuration file
location for example.
It is however B<much> better than nothing. Applications which need finer
control over their configuration functionality should use the configuration
functions such as CONF_load_modules() directly.
=head1 RETURN VALUES
Neither OPENSSL_config() nor OPENSSL_no_config() return a value.
@@ -73,7 +55,7 @@ Neither OPENSSL_config() nor OPENSSL_no_config() return a value.
=head1 SEE ALSO
L<conf(5)|conf(5)>, L<CONF_load_modules_file(3)|CONF_load_modules_file(3)>,
L<CONF_modules_free(3),CONF_modules_free(3)>
L<CONF_modules_free(3)|CONF_modules_free(3)>
=head1 HISTORY

109
doc/crypto/OPENSSL_ia32cap.pod
View File

@@ -2,42 +2,95 @@
=head1 NAME
OPENSSL_ia32cap - finding the IA-32 processor capabilities
OPENSSL_ia32cap, OPENSSL_ia32cap_loc - the IA-32 processor capabilities vector
=head1 SYNOPSIS
unsigned long *OPENSSL_ia32cap_loc(void);
#define OPENSSL_ia32cap (*(OPENSSL_ia32cap_loc()))
unsigned int *OPENSSL_ia32cap_loc(void);
#define OPENSSL_ia32cap ((OPENSSL_ia32cap_loc())[0])
=head1 DESCRIPTION
Value returned by OPENSSL_ia32cap_loc() is address of a variable
containing IA-32 processor capabilities bit vector as it appears in EDX
register after executing CPUID instruction with EAX=1 input value (see
Intel Application Note #241618). Naturally it's meaningful on IA-32[E]
platforms only. The variable is normally set up automatically upon
toolkit initialization, but can be manipulated afterwards to modify
crypto library behaviour. For the moment of this writing six bits are
significant, namely:
containing IA-32 processor capabilities bit vector as it appears in
EDX:ECX register pair after executing CPUID instruction with EAX=1
input value (see Intel Application Note #241618). Naturally it's
meaningful on x86 and x86_64 platforms only. The variable is normally
set up automatically upon toolkit initialization, but can be
manipulated afterwards to modify crypto library behaviour. For the
moment of this writing following bits are significant:
1. bit #28 denoting Hyperthreading, which is used to distiguish
cores with shared cache;
2. bit #26 denoting SSE2 support;
3. bit #25 denoting SSE support;
4. bit #23 denoting MMX support;
5. bit #20, reserved by Intel, is used to choose between RC4 code
pathes;
6. bit #4 denoting presence of Time-Stamp Counter.
=over
=item bit #4 denoting presence of Time-Stamp Counter.
=item bit #19 denoting availability of CLFLUSH instruction;
=item bit #20, reserved by Intel, is used to choose among RC4 code paths;
=item bit #23 denoting MMX support;
=item bit #24, FXSR bit, denoting availability of XMM registers;
=item bit #25 denoting SSE support;
=item bit #26 denoting SSE2 support;
=item bit #28 denoting Hyperthreading, which is used to distinguish
cores with shared cache;
=item bit #30, reserved by Intel, denotes specifically Intel CPUs;
=item bit #33 denoting availability of PCLMULQDQ instruction;
=item bit #41 denoting SSSE3, Supplemental SSE3, support;
=item bit #43 denoting AMD XOP support (forced to zero on non-AMD CPUs);
=item bit #57 denoting AES-NI instruction set extension;
=item bit #59, OSXSAVE bit, denoting availability of YMM registers;
=item bit #60 denoting AVX extension;
=item bit #62 denoting availability of RDRAND instruction;
=back
For example, clearing bit #26 at run-time disables high-performance
SSE2 code present in the crypto library. You might have to do this if
target OpenSSL application is executed on SSE2 capable CPU, but under
control of OS which does not support SSE2 extentions. Even though you
can manipulate the value programmatically, you most likely will find it
more appropriate to set up an environment variable with the same name
prior starting target application, e.g. on Intel P4 processor 'env
OPENSSL_ia32cap=0x12900010 apps/openssl', to achieve same effect
without modifying the application source code. Alternatively you can
reconfigure the toolkit with no-sse2 option and recompile.
SSE2 code present in the crypto library, while clearing bit #24
disables SSE2 code operating on 128-bit XMM register bank. You might
have to do the latter if target OpenSSL application is executed on SSE2
capable CPU, but under control of OS that does not enable XMM
registers. Even though you can manipulate the value programmatically,
you most likely will find it more appropriate to set up an environment
variable with the same name prior starting target application, e.g. on
Intel P4 processor 'env OPENSSL_ia32cap=0x16980010 apps/openssl', or
better yet 'env OPENSSL_ia32cap=~0x1000000 apps/openssl' to achieve same
effect without modifying the application source code. Alternatively you
can reconfigure the toolkit with no-sse2 option and recompile.
=cut
Less intuitive is clearing bit #28. The truth is that it's not copied
from CPUID output verbatim, but is adjusted to reflect whether or not
the data cache is actually shared between logical cores. This in turn
affects the decision on whether or not expensive countermeasures
against cache-timing attacks are applied, most notably in AES assembler
module.
The vector is further extended with EBX value returned by CPUID with
EAX=7 and ECX=0 as input. Following bits are significant:
=over
=item bit #64+3 denoting availability of BMI1 instructions, e.g. ANDN;
=item bit #64+5 denoting availability of AVX2 instructions;
=item bit #64+8 denoting availability of BMI2 instructions, e.g. MUXL
and RORX;
=item bit #64+18 denoting availability of RDSEED instruction;
=item bit #64+19 denoting availability of ADCX and ADOX instructions;
=back

42
doc/crypto/OPENSSL_instrument_bus.pod Normal file
View File

@@ -0,0 +1,42 @@
=pod
=head1 NAME
OPENSSL_instrument_bus, OPENSSL_instrument_bus2 - instrument references to memory bus
=head1 SYNOPSIS
#ifdef OPENSSL_CPUID_OBJ
size_t OPENSSL_instrument_bus (int *vector,size_t num);
size_t OPENSSL_instrument_bus2(int *vector,size_t num,size_t max);
#endif
=head1 DESCRIPTION
It was empirically found that timings of references to primary memory
are subject to irregular, apparently non-deterministic variations. The
subroutines in question instrument these references for purposes of
gathering entropy for random number generator. In order to make it
bus-bound a 'flush cache line' instruction is used between probes. In
addition probes are added to B<vector> elements in atomic or
interlocked manner, which should contribute additional noise on
multi-processor systems. This also means that B<vector[num]> should be
zeroed upon invocation (if you want to retrieve actual probe values).
OPENSSL_instrument_bus performs B<num> probes and records the number of
oscillator cycles every probe took.
OPENSSL_instrument_bus2 on the other hand B<accumulates> consecutive
probes with the same value, i.e. in a way it records duration of
periods when probe values appeared deterministic. The subroutine
performs at most B<max> probes in attempt to fill the B<vector[num]>,
with B<max> value of 0 meaning "as many as it takes."
=head1 RETURN VALUE
Return value of 0 indicates that CPU is not capable of performing the
benchmark, either because oscillator counter or 'flush cache line' is
not available on current platform. For reference, on x86 'flush cache
line' was introduced with the SSE2 extensions.
Otherwise number of recorded values is returned.

2
doc/crypto/OPENSSL_load_builtin_modules.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
OPENSSL_load_builtin_modules - add standard configuration modules
OPENSSL_load_builtin_modules, ASN1_add_oid_module, ENGINE_add_conf_module - add standard configuration modules
=head1 SYNOPSIS

2
doc/crypto/OpenSSL_add_all_algorithms.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
OpenSSL_add_all_algorithms, OpenSSL_add_all_ciphers, OpenSSL_add_all_digests -
OpenSSL_add_all_algorithms, OpenSSL_add_all_ciphers, OpenSSL_add_all_digests, EVP_cleanup -
add algorithms to internal table
=head1 SYNOPSIS

6
doc/crypto/PKCS7_verify.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
PKCS7_verify - verify a PKCS#7 signedData structure
PKCS7_verify, PKCS7_get0_signers - verify a PKCS#7 signedData structure
=head1 SYNOPSIS
@@ -91,8 +91,8 @@ timestamp).
=head1 RETURN VALUES
PKCS7_verify() returns 1 for a successful verification and zero or a negative
value if an error occurs.
PKCS7_verify() returns one for a successful verification and zero
if an error occurs.
PKCS7_get0_signers() returns all signers or B<NULL> if an error occurred.

2
doc/crypto/RAND_egd.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
RAND_egd - query entropy gathering daemon
RAND_egd, RAND_egd_bytes, RAND_query_egd_bytes - query entropy gathering daemon
=head1 SYNOPSIS

39
doc/crypto/RSA_generate_key.pod
View File

@@ -2,28 +2,33 @@
=head1 NAME
RSA_generate_key - generate RSA key pair
RSA_generate_key_ex, RSA_generate_key - generate RSA key pair
=head1 SYNOPSIS
#include <openssl/rsa.h>
int RSA_generate_key_ex(RSA *rsa, int bits, BIGNUM *e, BN_GENCB *cb);
Deprecated:
RSA *RSA_generate_key(int num, unsigned long e,
void (*callback)(int,int,void *), void *cb_arg);
=head1 DESCRIPTION
RSA_generate_key() generates a key pair and returns it in a newly
allocated B<RSA> structure. The pseudo-random number generator must
be seeded prior to calling RSA_generate_key().
RSA_generate_key_ex() generates a key pair and stores it in the B<RSA>
structure provided in B<rsa>. The pseudo-random number generator must
be seeded prior to calling RSA_generate_key_ex().
The modulus size will be B<num> bits, and the public exponent will be
The modulus size will be of length B<bits>, and the public exponent will be
B<e>. Key sizes with B<num> E<lt> 1024 should be considered insecure.
The exponent is an odd number, typically 3, 17 or 65537.
A callback function may be used to provide feedback about the
progress of the key generation. If B<callback> is not B<NULL>, it
will be called as follows:
progress of the key generation. If B<cb> is not B<NULL>, it
will be called as follows using the BN_GENCB_call() function
described on the L<BN_generate_prime(3)|BN_generate_prime(3)> page.
=over 4
@@ -35,32 +40,38 @@ described in L<BN_generate_prime(3)|BN_generate_prime(3)>.
=item *
When the n-th randomly generated prime is rejected as not
suitable for the key, B<callback(2, n, cb_arg)> is called.
suitable for the key, B<BN_GENCB_call(cb, 2, n)> is called.
=item *
When a random p has been found with p-1 relatively prime to B<e>,
it is called as B<callback(3, 0, cb_arg)>.
it is called as B<BN_GENCB_call(cb, 3, 0)>.
=back
The process is then repeated for prime q with B<callback(3, 1, cb_arg)>.
The process is then repeated for prime q with B<BN_GENCB_call(cb, 3, 1)>.
RSA_generate_key is deprecated (new applications should use
RSA_generate_key_ex instead). RSA_generate_key works in the same was as
RSA_generate_key_ex except it uses "old style" call backs. See
L<BN_generate_prime(3)|BN_generate_prime(3)> for further details.
=head1 RETURN VALUE
If key generation fails, RSA_generate_key() returns B<NULL>; the
error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
If key generation fails, RSA_generate_key() returns B<NULL>.
The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
=head1 BUGS
B<callback(2, x, cb_arg)> is used with two different meanings.
B<BN_GENCB_call(cb, 2, x)> is used with two different meanings.
RSA_generate_key() goes into an infinite loop for illegal input values.
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>,
L<RSA_free(3)|RSA_free(3)>
L<RSA_free(3)|RSA_free(3)>, L<BN_generate_prime(3)|BN_generate_prime(3)>
=head1 HISTORY

14
doc/crypto/RSA_set_method.pod
View File

@@ -125,14 +125,18 @@ the default method is used.
/* sign. For backward compatibility, this is used only
* if (flags & RSA_FLAG_SIGN_VER)
*/
int (*rsa_sign)(int type, unsigned char *m, unsigned int m_len,
unsigned char *sigret, unsigned int *siglen, RSA *rsa);
int (*rsa_sign)(int type,
const unsigned char *m, unsigned int m_length,
unsigned char *sigret, unsigned int *siglen, const RSA *rsa);
/* verify. For backward compatibility, this is used only
* if (flags & RSA_FLAG_SIGN_VER)
*/
int (*rsa_verify)(int type, unsigned char *m, unsigned int m_len,
unsigned char *sigbuf, unsigned int siglen, RSA *rsa);
int (*rsa_verify)(int dtype,
const unsigned char *m, unsigned int m_length,
const unsigned char *sigbuf, unsigned int siglen,
const RSA *rsa);
/* keygen. If NULL builtin RSA key generation will be used */
int (*rsa_keygen)(RSA *rsa, int bits, BIGNUM *e, BN_GENCB *cb);
} RSA_METHOD;

4
doc/crypto/RSA_sign.pod
View File

@@ -20,6 +20,10 @@ RSA_sign() signs the message digest B<m> of size B<m_len> using the
private key B<rsa> as specified in PKCS #1 v2.0. It stores the
signature in B<sigret> and the signature size in B<siglen>. B<sigret>
must point to RSA_size(B<rsa>) bytes of memory.
Note that PKCS #1 adds meta-data, placing limits on the size of the
key that can be used.
See L<RSA_private_encrypt(3)|RSA_private_encrypt(3)> for lower-level
operations.
B<type> denotes the message digest algorithm that was used to generate
B<m>. It usually is one of B<NID_sha1>, B<NID_ripemd160> and B<NID_md5>;

74
doc/crypto/SSLeay_version.pod Normal file
View File

@@ -0,0 +1,74 @@
=pod
=head1 NAME
SSLeay_version - retrieve version/build information about OpenSSL library
=head1 SYNOPSIS
#include <openssl/crypto.h>
const char *SSLeay_version(int type);
=head1 DESCRIPTION
SSLeay_version() returns a pointer to a constant string describing the
version of the OpenSSL library or giving information about the library
build.
The following B<type> values are supported:
=over 4
=item SSLEAY_VERSION
The version of the OpenSSL library including the release date.
=item SSLEAY_CFLAGS
The compiler flags set for the compilation process in the form
"compiler: ..." if available or "compiler: information not available"
otherwise.
=item SSLEAY_BUILT_ON
The date of the build process in the form "built on: ..." if available
or "built on: date not available" otherwise.
=item SSLEAY_PLATFORM
The "Configure" target of the library build in the form "platform: ..."
if available or "platform: information not available" otherwise.
=item SSLEAY_DIR
The "OPENSSLDIR" setting of the library build in the form "OPENSSLDIR: "...""
if available or "OPENSSLDIR: N/A" otherwise.
=back
=head1 RETURN VALUES
The following return values can occur:
=over 4
=item "not available"
An invalid value for B<type> was given.
=item Pointer to constant string
Textual description.
=back
=head1 SEE ALSO
L<crypto(3)|crypto(3)>
=head1 HISTORY
B<SSLEAY_DIR> was added in OpenSSL 0.9.7.
=cut

2
doc/crypto/X509_NAME_ENTRY_get_object.pod
View File

@@ -65,7 +65,7 @@ set first so the relevant field information can be looked up internally.
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>, L<d2i_X509_NAME(3)|d2i_X509_NAME(3)>,
L<OBJ_nid2obj(3),OBJ_nid2obj(3)>
L<OBJ_nid2obj(3)|OBJ_nid2obj(3)>
=head1 HISTORY

14
doc/crypto/X509_NAME_add_entry_by_txt.pod
View File

@@ -44,7 +44,7 @@ B<loc>. The deleted entry is returned and must be freed up.
=head1 NOTES
The use of string types such as B<MBSTRING_ASC> or B<MBSTRING_UTF8>
is strongly recommened for the B<type> parameter. This allows the
is strongly recommended for the B<type> parameter. This allows the
internal code to correctly determine the type of the field and to
apply length checks according to the relevant standards. This is
done using ASN1_STRING_set_by_NID().
@@ -81,14 +81,14 @@ Create an B<X509_NAME> structure:
nm = X509_NAME_new();
if (nm == NULL)
/* Some error */
if (!X509_NAME_add_entry_by_txt(nm, MBSTRING_ASC,
"C", "UK", -1, -1, 0))
if (!X509_NAME_add_entry_by_txt(nm, "C", MBSTRING_ASC,
"UK", -1, -1, 0))
/* Error */
if (!X509_NAME_add_entry_by_txt(nm, MBSTRING_ASC,
"O", "Disorganized Organization", -1, -1, 0))
if (!X509_NAME_add_entry_by_txt(nm, "O", MBSTRING_ASC,
"Disorganized Organization", -1, -1, 0))
/* Error */
if (!X509_NAME_add_entry_by_txt(nm, MBSTRING_ASC,
"CN", "Joe Bloggs", -1, -1, 0))
if (!X509_NAME_add_entry_by_txt(nm, "CN", MBSTRING_ASC,
"Joe Bloggs", -1, -1, 0))
/* Error */
=head1 RETURN VALUES

11
doc/crypto/X509_NAME_get_index_by_NID.pod
View File

@@ -29,6 +29,7 @@ and issuer names.
X509_NAME_get_index_by_NID() and X509_NAME_get_index_by_OBJ() retrieve
the next index matching B<nid> or B<obj> after B<lastpos>. B<lastpos>
should initially be set to -1. If there are no more entries -1 is returned.
If B<nid> is invalid (doesn't correspond to a valid OID) then -2 is returned.
X509_NAME_entry_count() returns the total number of entries in B<name>.
@@ -59,6 +60,14 @@ X509_NAME_get_index_by_OBJ() should be used followed by
X509_NAME_get_entry() on any matching indices and then the
various B<X509_NAME_ENTRY> utility functions on the result.
The list of all relevant B<NID_*> and B<OBJ_* codes> can be found in
the source code header files E<lt>openssl/obj_mac.hE<gt> and/or
E<lt>openssl/objects.hE<gt>.
Applications which could pass invalid NIDs to X509_NAME_get_index_by_NID()
should check for the return value of -2. Alternatively the NID validity
can be determined first by checking OBJ_nid2obj(nid) is not NULL.
=head1 EXAMPLES
Process all entries:
@@ -91,6 +100,8 @@ Process all commonName entries:
X509_NAME_get_index_by_NID() and X509_NAME_get_index_by_OBJ()
return the index of the next matching entry or -1 if not found.
X509_NAME_get_index_by_NID() can also return -2 if the supplied
NID is invalid.
X509_NAME_entry_count() returns the total number of entries.

10
doc/crypto/X509_STORE_CTX_get_error.pod
View File

@@ -32,7 +32,7 @@ checks.
X509_STORE_CTX_get_error_depth() returns the B<depth> of the error. This is a
non-negative integer representing where in the certificate chain the error
occurred. If it is zero it occured in the end entity certificate, one if
occurred. If it is zero it occurred in the end entity certificate, one if
it is the certificate which signed the end entity certificate and so on.
X509_STORE_CTX_get_current_cert() returns the certificate in B<ctx> which
@@ -246,11 +246,11 @@ Some feature of a certificate extension is not supported. Unused.
=item B<X509_V_ERR_PERMITTED_VIOLATION: permitted subtree violation>
A name constraint violation occured in the permitted subtrees.
A name constraint violation occurred in the permitted subtrees.
=item B<X509_V_ERR_EXCLUDED_VIOLATION: excluded subtree violation>
A name constraint violation occured in the excluded subtrees.
A name constraint violation occurred in the excluded subtrees.
=item B<X509_V_ERR_SUBTREE_MINMAX: name constraints minimum and maximum not supported>
@@ -270,7 +270,7 @@ a garbage extension or some new feature not currently supported.
=item B<X509_V_ERR_CRL_PATH_VALIDATION_ERROR: CRL path validation error>
An error occured when attempting to verify the CRL path. This error can only
An error occurred when attempting to verify the CRL path. This error can only
happen if extended CRL checking is enabled.
=item B<X509_V_ERR_APPLICATION_VERIFICATION: application verification failure>
@@ -278,6 +278,8 @@ happen if extended CRL checking is enabled.
an application specific error. This will never be returned unless explicitly
set by an application.
=back
=head1 NOTES
The above functions should be used instead of directly referencing the fields

2
doc/crypto/X509_STORE_CTX_get_ex_new_index.pod
View File

@@ -15,7 +15,7 @@ X509_STORE_CTX_get_ex_new_index, X509_STORE_CTX_set_ex_data, X509_STORE_CTX_get_
int X509_STORE_CTX_set_ex_data(X509_STORE_CTX *d, int idx, void *arg);
char *X509_STORE_CTX_get_ex_data(X509_STORE_CTX *d, int idx);
void *X509_STORE_CTX_get_ex_data(X509_STORE_CTX *d, int idx);
=head1 DESCRIPTION

13
doc/crypto/X509_STORE_CTX_new.pod
View File

@@ -39,10 +39,15 @@ X509_STORE_CTX_free() completely frees up B<ctx>. After this call B<ctx>
is no longer valid.
X509_STORE_CTX_init() sets up B<ctx> for a subsequent verification operation.
The trusted certificate store is set to B<store>, the end entity certificate
to be verified is set to B<x509> and a set of additional certificates (which
will be untrusted but may be used to build the chain) in B<chain>. Any or
all of the B<store>, B<x509> and B<chain> parameters can be B<NULL>.
It must be called before each call to X509_verify_cert(), i.e. a B<ctx> is only
good for one call to X509_verify_cert(); if you want to verify a second
certificate with the same B<ctx> then you must call X509_XTORE_CTX_cleanup()
and then X509_STORE_CTX_init() again before the second call to
X509_verify_cert(). The trusted certificate store is set to B<store>, the end
entity certificate to be verified is set to B<x509> and a set of additional
certificates (which will be untrusted but may be used to build the chain) in
B<chain>. Any or all of the B<store>, B<x509> and B<chain> parameters can be
B<NULL>.
X509_STORE_CTX_trusted_stack() sets the set of trusted certificates of B<ctx>
to B<sk>. This is an alternative way of specifying trusted certificates

87
doc/crypto/X509_VERIFY_PARAM_set_flags.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
X509_VERIFY_PARAM_set_flags, X509_VERIFY_PARAM_clear_flags, X509_VERIFY_PARAM_get_flags, X509_VERIFY_PARAM_set_purpose, X509_VERIFY_PARAM_set_trust, X509_VERIFY_PARAM_set_depth, X509_VERIFY_PARAM_get_depth, X509_VERIFY_PARAM_set_time, X509_VERIFY_PARAM_add0_policy, X509_VERIFY_PARAM_set1_policies - X509 verification parameters
X509_VERIFY_PARAM_set_flags, X509_VERIFY_PARAM_clear_flags, X509_VERIFY_PARAM_get_flags, X509_VERIFY_PARAM_set_purpose, X509_VERIFY_PARAM_set_trust, X509_VERIFY_PARAM_set_depth, X509_VERIFY_PARAM_get_depth, X509_VERIFY_PARAM_set_time, X509_VERIFY_PARAM_add0_policy, X509_VERIFY_PARAM_set1_policies, X509_VERIFY_PARAM_set1_host, X509_VERIFY_PARAM_add1_host, X509_VERIFY_PARAM_set_hostflags, X509_VERIFY_PARAM_get0_peername, X509_VERIFY_PARAM_set1_email, X509_VERIFY_PARAM_set1_ip, X509_VERIFY_PARAM_set1_ip_asc - X509 verification parameters
=head1 SYNOPSIS
@@ -26,6 +26,19 @@ X509_VERIFY_PARAM_set_flags, X509_VERIFY_PARAM_clear_flags, X509_VERIFY_PARAM_ge
void X509_VERIFY_PARAM_set_depth(X509_VERIFY_PARAM *param, int depth);
int X509_VERIFY_PARAM_get_depth(const X509_VERIFY_PARAM *param);
int X509_VERIFY_PARAM_set1_host(X509_VERIFY_PARAM *param,
const char *name, size_t namelen);
int X509_VERIFY_PARAM_add1_host(X509_VERIFY_PARAM *param,
const char *name, size_t namelen);
void X509_VERIFY_PARAM_set_hostflags(X509_VERIFY_PARAM *param,
unsigned int flags);
char *X509_VERIFY_PARAM_get0_peername(X509_VERIFY_PARAM *param);
int X509_VERIFY_PARAM_set1_email(X509_VERIFY_PARAM *param,
const char *email, size_t emaillen);
int X509_VERIFY_PARAM_set1_ip(X509_VERIFY_PARAM *param,
const unsigned char *ip, size_t iplen);
int X509_VERIFY_PARAM_set1_ip_asc(X509_VERIFY_PARAM *param, const char *ipasc);
=head1 DESCRIPTION
These functions manipulate the B<X509_VERIFY_PARAM> structure associated with
@@ -61,12 +74,63 @@ X509_VERIFY_PARAM_set_depth() sets the maximum verification depth to B<depth>.
That is the maximum number of untrusted CA certificates that can appear in a
chain.
X509_VERIFY_PARAM_set1_host() sets the expected DNS hostname to
B<name> clearing any previously specified host name or names. If
B<name> is NULL, or empty the list of hostnames is cleared, and
name checks are not performed on the peer certificate. If B<name>
is NUL-terminated, B<namelen> may be zero, otherwise B<namelen>
must be set to the length of B<name>. When a hostname is specified,
certificate verification automatically invokes L<X509_check_host(3)>
with flags equal to the B<flags> argument given to
B<X509_VERIFY_PARAM_set_hostflags()> (default zero). Applications
are strongly advised to use this interface in preference to explicitly
calling L<X509_check_host(3)>, hostname checks are out of scope
with the DANE-EE(3) certificate usage, and the internal check will
be suppressed as appropriate when DANE support is added to OpenSSL.
X509_VERIFY_PARAM_add1_host() adds B<name> as an additional reference
identifer that can match the peer's certificate. Any previous names
set via X509_VERIFY_PARAM_set1_host() or X509_VERIFY_PARAM_add1_host()
are retained, no change is made if B<name> is NULL or empty. When
multiple names are configured, the peer is considered verified when
any name matches.
X509_VERIFY_PARAM_get0_peername() returns the DNS hostname or subject
CommonName from the peer certificate that matched one of the reference
identifiers. When wildcard matching is not disabled, or when a
reference identifier specifies a parent domain (starts with ".")
rather than a hostname, the peer name may be a wildcard name or a
sub-domain of the reference identifier respectively. The return
string is allocated by the library and is no longer valid once the
associated B<param> argument is freed. Applications must not free
the return value.
X509_VERIFY_PARAM_set1_email() sets the expected RFC822 email address to
B<email>. If B<email> is NUL-terminated, B<emaillen> may be zero, otherwise
B<emaillen> must be set to the length of B<email>. When an email address
is specified, certificate verification automatically invokes
L<X509_check_email(3)>.
X509_VERIFY_PARAM_set1_ip() sets the expected IP address to B<ip>.
The B<ip> argument is in binary format, in network byte-order and
B<iplen> must be set to 4 for IPv4 and 16 for IPv6. When an IP
address is specified, certificate verification automatically invokes
L<X509_check_ip(3)>.
X509_VERIFY_PARAM_set1_ip_asc() sets the expected IP address to
B<ipasc>. The B<ipasc> argument is a NUL-terminal ASCII string:
dotted decimal quad for IPv4 and colon-separated hexadecimal for
IPv6. The condensed "::" notation is supported for IPv6 addresses.
=head1 RETURN VALUES
X509_VERIFY_PARAM_set_flags(), X509_VERIFY_PARAM_clear_flags(),
X509_VERIFY_PARAM_set_flags(), X509_VERIFY_PARAM_clear_flags(),
X509_VERIFY_PARAM_set_purpose(), X509_VERIFY_PARAM_set_trust(),
X509_VERIFY_PARAM_add0_policy() and X509_VERIFY_PARAM_set1_policies() return 1
for success and 0 for failure.
X509_VERIFY_PARAM_add0_policy() X509_VERIFY_PARAM_set1_policies(),
X509_VERIFY_PARAM_set1_host(), X509_VERIFY_PARAM_set_hostflags(),
X509_VERIFY_PARAM_set1_email(), X509_VERIFY_PARAM_set1_ip() and
X509_VERIFY_PARAM_set1_ip_asc() return 1 for success and 0 for
failure.
X509_VERIFY_PARAM_get_flags() returns the current verification flags.
@@ -113,7 +177,7 @@ a special status code is set to the verification callback. This permits it
to examine the valid policy tree and perform additional checks or simply
log it for debugging purposes.
By default some addtional features such as indirect CRLs and CRLs signed by
By default some additional features such as indirect CRLs and CRLs signed by
different keys are disabled. If B<X509_V_FLAG_EXTENDED_CRL_SUPPORT> is set
they are enabled.
@@ -133,6 +197,12 @@ verification. If this flag is set then additional status codes will be sent
to the verification callback and it B<must> be prepared to handle such cases
without assuming they are hard errors.
The B<X509_V_FLAG_NO_ALT_CHAINS> flag suppresses checking for alternative
chains. By default, when building a certificate chain, if the first certificate
chain found is not trusted, then OpenSSL will continue to check to see if an
alternative chain can be found that is trusted. With this flag set the behaviour
will match that of OpenSSL versions prior to 1.0.2b.
=head1 NOTES
The above functions should be used to manipulate verification parameters
@@ -162,10 +232,13 @@ connections associated with an B<SSL_CTX> structure B<ctx>:
=head1 SEE ALSO
L<X509_verify_cert(3)|X509_verify_cert(3)>
L<X509_verify_cert(3)|X509_verify_cert(3)>,
L<X509_check_host(3)|X509_check_host(3)>,
L<X509_check_email(3)|X509_check_email(3)>,
L<X509_check_ip(3)|X509_check_ip(3)>
=head1 HISTORY
TBA
The B<X509_V_FLAG_NO_ALT_CHAINS> flag was added in OpenSSL 1.0.2b
=cut

140
doc/crypto/X509_check_host.pod Normal file
View File

@@ -0,0 +1,140 @@
=pod
=head1 NAME
X509_check_host, X509_check_email, X509_check_ip, X509_check_ip_asc - X.509 certificate matching
=head1 SYNOPSIS
#include <openssl/x509.h>
int X509_check_host(X509 *, const char *name, size_t namelen,
unsigned int flags, char **peername);
int X509_check_email(X509 *, const char *address, size_t addresslen,
unsigned int flags);
int X509_check_ip(X509 *, const unsigned char *address, size_t addresslen,
unsigned int flags);
int X509_check_ip_asc(X509 *, const char *address, unsigned int flags);
=head1 DESCRIPTION
The certificate matching functions are used to check whether a
certificate matches a given host name, email address, or IP address.
The validity of the certificate and its trust level has to be checked by
other means.
X509_check_host() checks if the certificate Subject Alternative
Name (SAN) or Subject CommonName (CN) matches the specified host
name, which must be encoded in the preferred name syntax described
in section 3.5 of RFC 1034. By default, wildcards are supported
and they match only in the left-most label; but they may match
part of that label with an explicit prefix or suffix. For example,
by default, the host B<name> "www.example.com" would match a
certificate with a SAN or CN value of "*.example.com", "w*.example.com"
or "*w.example.com".
Per section 6.4.2 of RFC 6125, B<name> values representing international
domain names must be given in A-label form. The B<namelen> argument
must be the number of characters in the name string or zero in which
case the length is calculated with strlen(B<name>). When B<name> starts
with a dot (e.g ".example.com"), it will be matched by a certificate
valid for any sub-domain of B<name>, (see also
B<X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS> below).
When the certificate is matched, and B<peername> is not NULL, a
pointer to a copy of the matching SAN or CN from the peer certificate
is stored at the address passed in B<peername>. The application
is responsible for freeing the peername via OPENSSL_free() when it
is no longer needed.
X509_check_email() checks if the certificate matches the specified
email B<address>. Only the mailbox syntax of RFC 822 is supported,
comments are not allowed, and no attempt is made to normalize quoted
characters. The B<addresslen> argument must be the number of
characters in the address string or zero in which case the length
is calculated with strlen(B<address>).
X509_check_ip() checks if the certificate matches a specified IPv4 or
IPv6 address. The B<address> array is in binary format, in network
byte order. The length is either 4 (IPv4) or 16 (IPv6). Only
explicitly marked addresses in the certificates are considered; IP
addresses stored in DNS names and Common Names are ignored.
X509_check_ip_asc() is similar, except that the NUL-terminated
string B<address> is first converted to the internal representation.
The B<flags> argument is usually 0. It can be the bitwise OR of the
flags:
=over 4
=item B<X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT>,
=item B<X509_CHECK_FLAG_NO_WILDCARDS>,
=item B<X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS>,
=item B<X509_CHECK_FLAG_MULTI_LABEL_WILDCARDS>.
=item B<X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS>.
=back
The B<X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT> flag causes the function
to consider the subject DN even if the certificate contains at least
one subject alternative name of the right type (DNS name or email
address as appropriate); the default is to ignore the subject DN
when at least one corresponding subject alternative names is present.
If set, B<X509_CHECK_FLAG_NO_WILDCARDS> disables wildcard
expansion; this only applies to B<X509_check_host>.
If set, B<X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS> suppresses support
for "*" as wildcard pattern in labels that have a prefix or suffix,
such as: "www*" or "*www"; this only aplies to B<X509_check_host>.
If set, B<X509_CHECK_FLAG_MULTI_LABEL_WILDCARDS> allows a "*" that
constitutes the complete label of a DNS name (e.g. "*.example.com")
to match more than one label in B<name>; this flag only applies
to B<X509_check_host>.
If set, B<X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS> restricts B<name>
values which start with ".", that would otherwise match any sub-domain
in the peer certificate, to only match direct child sub-domains.
Thus, for instance, with this flag set a B<name> of ".example.com"
would match a peer certificate with a DNS name of "www.example.com",
but would not match a peer certificate with a DNS name of
"www.sub.example.com"; this flag only applies to B<X509_check_host>.
=head1 RETURN VALUES
The functions return 1 for a successful match, 0 for a failed match
and -1 for an internal error: typically a memory allocation failure
or an ASN.1 decoding error.
All functions can also return -2 if the input is malformed. For example,
X509_check_host() returns -2 if the provided B<name> contains embedded
NULs.
=head1 NOTES
Applications are encouraged to use X509_VERIFY_PARAM_set1_host()
rather than explicitly calling L<X509_check_host(3)>. Host name
checks are out of scope with the DANE-EE(3) certificate usage,
and the internal checks will be suppressed as appropriate when
DANE support is added to OpenSSL.
=head1 SEE ALSO
L<SSL_get_verify_result(3)|SSL_get_verify_result(3)>,
L<X509_VERIFY_PARAM_set1_host(3)|X509_VERIFY_PARAM_set1_host(3)>,
L<X509_VERIFY_PARAM_add1_host(3)|X509_VERIFY_PARAM_add1_host(3)>,
L<X509_VERIFY_PARAM_set1_email(3)|X509_VERIFY_PARAM_set1_email(3)>,
L<X509_VERIFY_PARAM_set1_ip(3)|X509_VERIFY_PARAM_set1_ip(3)>,
L<X509_VERIFY_PARAM_set1_ipasc(3)|X509_VERIFY_PARAM_set1_ipasc(3)>
=head1 HISTORY
These functions were added in OpenSSL 1.1.0.
=cut

3
doc/crypto/X509_verify_cert.pod
View File

@@ -32,7 +32,8 @@ OpenSSL internally for certificate validation, in both the S/MIME and
SSL/TLS code.
The negative return value from X509_verify_cert() can only occur if no
certificate is set in B<ctx> (due to a programming error) or if a retry
certificate is set in B<ctx> (due to a programming error); if X509_verify_cert()
twice without reinitialising B<ctx> in between; or if a retry
operation is requested during internal lookups (which never happens with
standard lookup methods). It is however recommended that application check
for <= 0 return value on error.

2
doc/crypto/crypto.pod
View File

@@ -56,7 +56,7 @@ L<pkcs7(3)|pkcs7(3)>, L<pkcs12(3)|pkcs12(3)>
=item INTERNAL FUNCTIONS
L<bn(3)|bn(3)>, L<buffer(3)|buffer(3)>, L<lhash(3)|lhash(3)>,
L<bn(3)|bn(3)>, L<buffer(3)|buffer(3)>, L<ec(3)|ec(3)>, L<lhash(3)|lhash(3)>,
L<objects(3)|objects(3)>, L<stack(3)|stack(3)>,
L<txt_db(3)|txt_db(3)>

29
doc/crypto/d2i_CMS_ContentInfo.pod Normal file
View File

@@ -0,0 +1,29 @@
=pod
=head1 NAME
d2i_CMS_ContentInfo, i2d_CMS_ContentInfo - CMS ContentInfo functions
=head1 SYNOPSIS
#include <openssl/cms.h>
CMS_ContentInfo *d2i_CMS_ContentInfo(CMS_ContentInfo **a, unsigned char **pp, long length);
int i2d_CMS_ContentInfo(CMS_ContentInfo *a, unsigned char **pp);
=head1 DESCRIPTION
These functions decode and encode an CMS ContentInfo structure.
Otherwise they behave in a similar way to d2i_X509() and i2d_X509()
described in the L<d2i_X509(3)|d2i_X509(3)> manual page.
=head1 SEE ALSO
L<d2i_X509(3)|d2i_X509(3)>
=head1 HISTORY
These functions were first added to OpenSSL 0.9.8
=cut

2
doc/crypto/d2i_DSAPublicKey.pod
View File

@@ -3,7 +3,7 @@
=head1 NAME
d2i_DSAPublicKey, i2d_DSAPublicKey, d2i_DSAPrivateKey, i2d_DSAPrivateKey,
d2i_DSA_PUBKEY, i2d_DSA_PUBKEY, d2i_DSA_SIG, i2d_DSA_SIG - DSA key encoding
d2i_DSA_PUBKEY, i2d_DSA_PUBKEY, d2i_DSAparams, i2d_DSAparams, d2i_DSA_SIG, i2d_DSA_SIG - DSA key encoding
and parsing functions.
=head1 SYNOPSIS

84
doc/crypto/d2i_ECPKParameters.pod Normal file
View File

@@ -0,0 +1,84 @@
=pod
=head1 NAME
d2i_ECPKParameters, i2d_ECPKParameters, d2i_ECPKParameters_bio, i2d_ECPKParameters_bio, d2i_ECPKParameters_fp, i2d_ECPKParameters_fp, ECPKParameters_print, ECPKParameters_print_fp - Functions for decoding and encoding ASN1 representations of elliptic curve entities
=head1 SYNOPSIS
#include <openssl/ec.h>
EC_GROUP *d2i_ECPKParameters(EC_GROUP **px, const unsigned char **in, long len);
int i2d_ECPKParameters(const EC_GROUP *x, 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);
=head1 DESCRIPTION
The ECPKParameters encode and decode routines encode and parse the public parameters for an
B<EC_GROUP> structure, which represents a curve.
d2i_ECPKParameters() attempts to decode B<len> bytes at B<*in>. If
successful a pointer to the B<EC_GROUP> structure is returned. If an error
occurred then B<NULL> is returned. If B<px> is not B<NULL> then the
returned structure is written to B<*px>. If B<*px> is not B<NULL>
then it is assumed that B<*px> contains a valid B<EC_GROUP>
structure and an attempt is made to reuse it. If the call is
successful B<*in> is incremented to the byte following the
parsed data.
i2d_ECPKParameters() encodes the structure pointed to by B<x> into DER format.
If B<out> is not B<NULL> is writes the DER encoded data to the buffer
at B<*out>, and increments it to point after the data just written.
If the return value is negative an error occurred, otherwise it
returns the length of the encoded data.
If B<*out> is B<NULL> memory will be allocated for a buffer and the encoded
data written to it. In this case B<*out> is not incremented and it points to
the start of the data just written.
d2i_ECPKParameters_bio() is similar to d2i_ECPKParameters() except it attempts
to parse data from BIO B<bp>.
d2i_ECPKParameters_fp() is similar to d2i_ECPKParameters() except it attempts
to parse data from FILE pointer B<fp>.
i2d_ECPKParameters_bio() is similar to i2d_ECPKParameters() except it writes
the encoding of the structure B<x> to BIO B<bp> and it
returns 1 for success and 0 for failure.
i2d_ECPKParameters_fp() is similar to i2d_ECPKParameters() except it writes
the encoding of the structure B<x> to BIO B<bp> and it
returns 1 for success and 0 for failure.
These functions are very similar to the X509 functions described in L<d2i_X509(3)|d2i_X509(3)>,
where further notes and examples are available.
The ECPKParameters_print and ECPKParameters_print_fp functions print a human-readable output
of the public parameters of the EC_GROUP to B<bp> or B<fp>. The output lines are indented by B<off> spaces.
=head1 RETURN VALUES
d2i_ECPKParameters(), d2i_ECPKParameters_bio() and d2i_ECPKParameters_fp() return a valid B<EC_GROUP> structure
or B<NULL> if an error occurs.
i2d_ECPKParameters() returns the number of bytes successfully encoded or a negative
value if an error occurs.
i2d_ECPKParameters_bio(), i2d_ECPKParameters_fp(), ECPKParameters_print and ECPKParameters_print_fp
return 1 for success and 0 if an error occurs.
=head1 SEE ALSO
L<crypto(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>, L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>,
L<EC_POINT_new(3)|EC_POINT_new(3)>, L<EC_POINT_add(3)|EC_POINT_add(3)>, L<EC_KEY_new(3)|EC_KEY_new(3)>,
L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>, L<d2i_X509(3)|d2i_X509(3)>
=cut

67
doc/crypto/d2i_ECPrivateKey.pod Normal file
View File

@@ -0,0 +1,67 @@
=pod
=head1 NAME
i2d_ECPrivateKey, d2i_ECPrivate_key - Encode and decode functions for saving and
reading EC_KEY structures
=head1 SYNOPSIS
#include <openssl/ec.h>
EC_KEY *d2i_ECPrivateKey(EC_KEY **key, const unsigned char **in, long len);
int i2d_ECPrivateKey(EC_KEY *key, unsigned char **out);
unsigned int EC_KEY_get_enc_flags(const EC_KEY *key);
void EC_KEY_set_enc_flags(EC_KEY *eckey, unsigned int flags);
=head1 DESCRIPTION
The ECPrivateKey encode and decode routines encode and parse an
B<EC_KEY> structure into a binary format (ASN.1 DER) and back again.
These functions are similar to the d2i_X509() functions, and you should refer to
that page for a detailed description (see L<d2i_X509(3)|d2i_X509(3)>).
The format of the external representation of the public key written by
i2d_ECPrivateKey (such as whether it is stored in a compressed form or not) is
described by the point_conversion_form. See L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>
for a description of point_conversion_form.
When reading a private key encoded without an associated public key (e.g. if
EC_PKEY_NO_PUBKEY has been used - see below), then d2i_ECPrivateKey generates
the missing public key automatically. Private keys encoded without parameters
(e.g. if EC_PKEY_NO_PARAMETERS has been used - see below) cannot be loaded using
d2i_ECPrivateKey.
The functions EC_KEY_get_enc_flags and EC_KEY_set_enc_flags get and set the
value of the encoding flags for the B<key>. There are two encoding flags
currently defined - EC_PKEY_NO_PARAMETERS and EC_PKEY_NO_PUBKEY. These flags
define the behaviour of how the B<key> is converted into ASN1 in a call to
i2d_ECPrivateKey. If EC_PKEY_NO_PARAMETERS is set then the public parameters for
the curve are not encoded along with the private key. If EC_PKEY_NO_PUBKEY is
set then the public key is not encoded along with the private key.
=head1 RETURN VALUES
d2i_ECPrivateKey() returns a valid B<EC_KEY> structure or B<NULL> if an error
occurs. The error code that can be obtained by
L<ERR_get_error(3)|ERR_get_error(3)>.
i2d_ECPrivateKey() returns the number of bytes successfully encoded or a
negative value if an error occurs. The error code can be obtained by
L<ERR_get_error(3)|ERR_get_error(3)>.
EC_KEY_get_enc_flags returns the value of the current encoding flags for the
EC_KEY.
=head1 SEE ALSO
L<crypto(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>,
L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>, L<EC_POINT_new(3)|EC_POINT_new(3)>,
L<EC_POINT_add(3)|EC_POINT_add(3)>,
L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>,
L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)>,
L<d2i_ECPrivateKey(3)|d2i_ECPrivateKey(3)>
=cut

39
doc/crypto/d2i_X509.pod
View File

@@ -18,6 +18,8 @@ i2d_X509_fp - X509 encode and decode functions
int i2d_X509_bio(BIO *bp, X509 *x);
int i2d_X509_fp(FILE *fp, X509 *x);
int i2d_re_X509_tbs(X509 *x, unsigned char **out);
=head1 DESCRIPTION
The X509 encode and decode routines encode and parse an
@@ -28,8 +30,11 @@ successful a pointer to the B<X509> structure is returned. If an error
occurred then B<NULL> is returned. If B<px> is not B<NULL> then the
returned structure is written to B<*px>. If B<*px> is not B<NULL>
then it is assumed that B<*px> contains a valid B<X509>
structure and an attempt is made to reuse it. If the call is
successful B<*in> is incremented to the byte following the
structure and an attempt is made to reuse it. This "reuse" capability is present
for historical compatibility but its use is B<strongly discouraged> (see BUGS
below, and the discussion in the RETURN VALUES section).
If the call is successful B<*in> is incremented to the byte following the
parsed data.
i2d_X509() encodes the structure pointed to by B<x> into DER format.
@@ -57,11 +62,17 @@ i2d_X509_fp() is similar to i2d_X509() except it writes
the encoding of the structure B<x> to BIO B<bp> and it
returns 1 for success and 0 for failure.
i2d_re_X509_tbs() is similar to i2d_X509() except it encodes
only the TBSCertificate portion of the certificate.
=head1 NOTES
The letters B<i> and B<d> in for example B<i2d_X509> stand for
"internal" (that is an internal C structure) and "DER". So that
B<i2d_X509> converts from internal to DER.
"internal" (that is an internal C structure) and "DER". So
B<i2d_X509> converts from internal to DER. The "re" in
B<i2d_re_X509_tbs> stands for "re-encode", and ensures that a fresh
encoding is generated in case the object has been modified after
creation (see the BUGS section).
The functions can also understand B<BER> forms.
@@ -206,11 +217,29 @@ fields entirely and will not be parsed by d2i_X509(). This may be
fixed in future so code should not assume that i2d_X509() will
always succeed.
The encoding of the TBSCertificate portion of a certificate is cached
in the B<X509> structure internally to improve encoding performance
and to ensure certificate signatures are verified correctly in some
certificates with broken (non-DER) encodings.
Any function which encodes an X509 structure such as i2d_X509(),
i2d_X509_fp() or i2d_X509_bio() may return a stale encoding if the
B<X509> structure has been modified after deserialization or previous
serialization.
If, after modification, the B<X509> object is re-signed with X509_sign(),
the encoding is automatically renewed. Otherwise, the encoding of the
TBSCertificate portion of the B<X509> can be manually renewed by calling
i2d_re_X509_tbs().
=head1 RETURN VALUES
d2i_X509(), d2i_X509_bio() and d2i_X509_fp() return a valid B<X509> structure
or B<NULL> if an error occurs. The error code that can be obtained by
L<ERR_get_error(3)|ERR_get_error(3)>.
L<ERR_get_error(3)|ERR_get_error(3)>. If the "reuse" capability has been used
with a valid X509 structure being passed in via B<px> then the object is not
freed in the event of error but may be in a potentially invalid or inconsistent
state.
i2d_X509() returns the number of bytes successfully encoded or a negative
value if an error occurs. The error code can be obtained by

2
doc/crypto/d2i_X509_CRL.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
d2i_X509_CRL, i2d_X509_CRL, d2i_X509_CRL_bio, d2i_509_CRL_fp,
d2i_X509_CRL, i2d_X509_CRL, d2i_X509_CRL_bio, d2i_X509_CRL_fp,
i2d_X509_CRL_bio, i2d_X509_CRL_fp - PKCS#10 certificate request functions.
=head1 SYNOPSIS

7
doc/crypto/des.pod
View File

@@ -135,9 +135,8 @@ depend on a global variable.
DES_set_odd_parity() sets the parity of the passed I<key> to odd.
DES_is_weak_key() returns 1 is the passed key is a weak key, 0 if it
is ok. The probability that a randomly generated key is weak is
1/2^52, so it is not really worth checking for them.
DES_is_weak_key() returns 1 if the passed key is a weak key, 0 if it
is ok.
The following routines mostly operate on an input and output stream of
I<DES_cblock>s.
@@ -181,7 +180,7 @@ of 24 bytes. This is much better than CBC DES.
DES_ede3_cbc_encrypt() implements outer triple CBC DES encryption with
three keys. This means that each DES operation inside the CBC mode is
really an C<C=E(ks3,D(ks2,E(ks1,M)))>. This mode is used by SSL.
an C<C=E(ks3,D(ks2,E(ks1,M)))>. This mode is used by SSL.
The DES_ede2_cbc_encrypt() macro implements two-key Triple-DES by
reusing I<ks1> for the final encryption. C<C=E(ks1,D(ks2,E(ks1,M)))>.

201
doc/crypto/ec.pod Normal file
View File

@@ -0,0 +1,201 @@
=pod
=head1 NAME
ec - Elliptic Curve functions
=head1 SYNOPSIS
#include <openssl/ec.h>
#include <openssl/bn.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_get_key_method_data(EC_KEY *key,
void *(*dup_func)(void *), void (*free_func)(void *), void (*clear_free_func)(void *));
void EC_KEY_insert_key_method_data(EC_KEY *key, void *data,
void *(*dup_func)(void *), void (*free_func)(void *), void (*clear_free_func)(void *));
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)
=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)|EC_GROUP_new(3)>. Functions for
manipulating B<EC_GROUP> objects are described in L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>.
Functions for creating, destroying and manipulating B<EC_POINT> objects are explained in L<EC_POINT_new(3)|EC_POINT_new(3)>,
whilst functions for performing mathematical operations and tests on B<EC_POINTs> are coverd in L<EC_POINT_add(3)|EC_POINT_add(3)>.
For working with private and public keys refer to L<EC_KEY_new(3)|EC_KEY_new(3)>. Implementations are covered in
L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>.
For information on encoding and decoding curve parameters to and from ASN1 see L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)>.
=head1 SEE ALSO
L<crypto(3)|crypto(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>, L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>,
L<EC_POINT_new(3)|EC_POINT_new(3)>, L<EC_POINT_add(3)|EC_POINT_add(3)>, L<EC_KEY_new(3)|EC_KEY_new(3)>,
L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)>
=cut

14
doc/crypto/ecdsa.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
ecdsa - Elliptic Curve Digital Signature Algorithm
ECDSA_SIG_new, ECDSA_SIG_free, i2d_ECDSA_SIG, d2i_ECDSA_SIG, ECDSA_size, ECDSA_sign_setup, ECDSA_sign, ECDSA_sign_ex, ECDSA_verify, ECDSA_do_sign, ECDSA_do_sign_ex, ECDSA_do_verify - Elliptic Curve Digital Signature Algorithm
=head1 SYNOPSIS
@@ -95,7 +95,7 @@ is ignored.
ECDSA_verify() verifies that the signature in B<sig> of size
B<siglen> is a valid ECDSA signature of the hash value
value B<dgst> of size B<dgstlen> using the public key B<eckey>.
B<dgst> of size B<dgstlen> using the public key B<eckey>.
The parameter B<type> is ignored.
ECDSA_do_sign() is wrapper function for ECDSA_do_sign_ex with B<kinv>
@@ -114,7 +114,7 @@ using the public key B<eckey>.
ECDSA_size() returns the maximum length signature or 0 on error.
ECDSA_sign_setup() and ECDSA_sign() return 1 if successful or -1
ECDSA_sign_setup() and ECDSA_sign() return 1 if successful or 0
on error.
ECDSA_verify() and ECDSA_do_verify() return 1 for a valid
@@ -131,16 +131,12 @@ specific)
int ret;
ECDSA_SIG *sig;
EC_KEY *eckey = EC_KEY_new();
EC_KEY *eckey;
eckey = EC_KEY_new_by_curve_name(NID_secp192k1);
if (eckey == NULL)
{
/* error */
}
key->group = EC_GROUP_new_by_nid(NID_secp192k1);
if (key->group == NULL)
{
/* error */
}
if (!EC_KEY_generate_key(eckey))
{
/* error */

1
doc/crypto/err.pod
View File

@@ -171,7 +171,6 @@ ERR_get_string_table(void) respectively.
=head1 SEE ALSO
L<CRYPTO_set_id_callback(3)|CRYPTO_set_id_callback(3)>,
L<CRYPTO_set_locking_callback(3)|CRYPTO_set_locking_callback(3)>,
L<ERR_get_error(3)|ERR_get_error(3)>,
L<ERR_GET_LIB(3)|ERR_GET_LIB(3)>,

66
doc/crypto/evp.pod
View File

@@ -13,22 +13,58 @@ evp - high-level cryptographic functions
The EVP library provides a high-level interface to cryptographic
functions.
B<EVP_Seal>I<...> and B<EVP_Open>I<...> provide public key encryption
and decryption to implement digital "envelopes".
L<B<EVP_Seal>I<...>|EVP_SealInit(3)> and L<B<EVP_Open>I<...>|EVP_OpenInit(3)>
provide public key encryption and decryption to implement digital "envelopes".
The B<EVP_Sign>I<...> and B<EVP_Verify>I<...> functions implement
digital signatures.
The L<B<EVP_DigestSign>I<...>|EVP_DigestSignInit(3)> and
L<B<EVP_DigestVerify>I<...>|EVP_DigestVerifyInit(3)> functions implement
digital signatures and Message Authentication Codes (MACs). Also see the older
L<B<EVP_Sign>I<...>|EVP_SignInit(3)> and L<B<EVP_Verify>I<...>|EVP_VerifyInit(3)>
functions.
Symmetric encryption is available with the B<EVP_Encrypt>I<...>
functions. The B<EVP_Digest>I<...> functions provide message digests.
Symmetric encryption is available with the L<B<EVP_Encrypt>I<...>|EVP_EncryptInit(3)>
functions. The L<B<EVP_Digest>I<...>|EVP_DigestInit(3)> functions provide message digests.
The B<EVP_PKEY>I<...> functions provide a high level interface to
asymmetric algorithms.
asymmetric algorithms. To create a new EVP_PKEY see
L<EVP_PKEY_new(3)|EVP_PKEY_new(3)>. EVP_PKEYs can be associated
with a private key of a particular algorithm by using the functions
described on the L<EVP_PKEY_set1_RSA(3)|EVP_PKEY_set1_RSA(3)> page, or
new keys can be generated using L<EVP_PKEY_keygen(3)|EVP_PKEY_keygen(3)>.
EVP_PKEYs can be compared using L<EVP_PKEY_cmp(3)|EVP_PKEY_cmp(3)>, or printed using
L<EVP_PKEY_print_private(3)|EVP_PKEY_print_private(3)>.
Algorithms are loaded with OpenSSL_add_all_algorithms(3).
The EVP_PKEY functions support the full range of asymmetric algorithm operations:
=over
=item For key agreement see L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)>
=item For signing and verifying see L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>,
L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)> and L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>.
However, note that
these functions do not perform a digest of the data to be signed. Therefore
normally you would use the L<B<EVP_DigestSign>I<...>|EVP_DigestSignInit(3)>
functions for this purpose.
=item For encryption and decryption see L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>
and L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)> respectively. However, note that
these functions perform encryption and decryption only. As public key
encryption is an expensive operation, normally you would wrap
an encrypted message in a "digital envelope" using the L<B<EVP_Seal>I<...>|EVP_SealInit(3)> and
L<B<EVP_Open>I<...>|EVP_OpenInit(3)> functions.
=back
The L<EVP_BytesToKey(3)|EVP_BytesToKey(3)> function provides some limited support for password
based encryption. Careful selection of the parameters will provide a PKCS#5 PBKDF1 compatible
implementation. However, new applications should not typically use this (preferring, for example,
PBKDF2 from PCKS#5).
Algorithms are loaded with L<OpenSSL_add_all_algorithms(3)|OpenSSL_add_all_algorithms(3)>.
All the symmetric algorithms (ciphers), digests and asymmetric algorithms
(public key algorithms) can be replaced by ENGINE modules providing alternative
(public key algorithms) can be replaced by L<ENGINE|engine(3)> modules providing alternative
implementations. If ENGINE implementations of ciphers or digests are registered
as defaults, then the various EVP functions will automatically use those
implementations automatically in preference to built in software
@@ -47,8 +83,20 @@ L<EVP_DigestInit(3)|EVP_DigestInit(3)>,
L<EVP_EncryptInit(3)|EVP_EncryptInit(3)>,
L<EVP_OpenInit(3)|EVP_OpenInit(3)>,
L<EVP_SealInit(3)|EVP_SealInit(3)>,
L<EVP_DigestSignInit(3)|EVP_DigestSignInit(3)>,
L<EVP_SignInit(3)|EVP_SignInit(3)>,
L<EVP_VerifyInit(3)|EVP_VerifyInit(3)>,
L<EVP_PKEY_new(3)|EVP_PKEY_new(3)>,
L<EVP_PKEY_set1_RSA(3)|EVP_PKEY_set1_RSA(3)>,
L<EVP_PKEY_keygen(3)|EVP_PKEY_keygen(3)>,
L<EVP_PKEY_print_private(3)|EVP_PKEY_print_private(3)>,
L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>,
L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>,
L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>,
L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>,
L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>,
L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)>,
L<EVP_BytesToKey(3)|EVP_BytesToKey(3)>,
L<OpenSSL_add_all_algorithms(3)|OpenSSL_add_all_algorithms(3)>,
L<engine(3)|engine(3)>

4
doc/crypto/hmac.pod
View File

@@ -2,8 +2,8 @@
=head1 NAME
HMAC, HMAC_Init, HMAC_Update, HMAC_Final, HMAC_cleanup - HMAC message
authentication code
HMAC, HMAC_CTX_init, HMAC_Init, HMAC_Init_ex, HMAC_Update, HMAC_Final, HMAC_CTX_cleanup,
HMAC_cleanup - HMAC message authentication code
=head1 SYNOPSIS

2
doc/crypto/i2d_PKCS7_bio_stream.pod
View File

@@ -23,7 +23,7 @@ streaming.
=head1 BUGS
The prefix "d2i" is arguably wrong because the function outputs BER format.
The prefix "i2d" is arguably wrong because the function outputs BER format.
=head1 RETURN VALUES

37
doc/crypto/pem.pod
View File

@@ -2,7 +2,29 @@
=head1 NAME
PEM, PEM_read_bio_PrivateKey, PEM_read_PrivateKey, PEM_write_bio_PrivateKey, PEM_write_PrivateKey, PEM_write_bio_PKCS8PrivateKey, PEM_write_PKCS8PrivateKey, PEM_write_bio_PKCS8PrivateKey_nid, PEM_write_PKCS8PrivateKey_nid, PEM_read_bio_PUBKEY, PEM_read_PUBKEY, PEM_write_bio_PUBKEY, PEM_write_PUBKEY, PEM_read_bio_RSAPrivateKey, PEM_read_RSAPrivateKey, PEM_write_bio_RSAPrivateKey, PEM_write_RSAPrivateKey, PEM_read_bio_RSAPublicKey, PEM_read_RSAPublicKey, PEM_write_bio_RSAPublicKey, PEM_write_RSAPublicKey, PEM_read_bio_RSA_PUBKEY, PEM_read_RSA_PUBKEY, PEM_write_bio_RSA_PUBKEY, PEM_write_RSA_PUBKEY, PEM_read_bio_DSAPrivateKey, PEM_read_DSAPrivateKey, PEM_write_bio_DSAPrivateKey, PEM_write_DSAPrivateKey, PEM_read_bio_DSA_PUBKEY, PEM_read_DSA_PUBKEY, PEM_write_bio_DSA_PUBKEY, PEM_write_DSA_PUBKEY, PEM_read_bio_DSAparams, PEM_read_DSAparams, PEM_write_bio_DSAparams, PEM_write_DSAparams, PEM_read_bio_DHparams, PEM_read_DHparams, PEM_write_bio_DHparams, PEM_write_DHparams, PEM_read_bio_X509, PEM_read_X509, PEM_write_bio_X509, PEM_write_X509, PEM_read_bio_X509_AUX, PEM_read_X509_AUX, PEM_write_bio_X509_AUX, PEM_write_X509_AUX, PEM_read_bio_X509_REQ, PEM_read_X509_REQ, PEM_write_bio_X509_REQ, PEM_write_X509_REQ, PEM_write_bio_X509_REQ_NEW, PEM_write_X509_REQ_NEW, PEM_read_bio_X509_CRL, PEM_read_X509_CRL, PEM_write_bio_X509_CRL, PEM_write_X509_CRL, PEM_read_bio_PKCS7, PEM_read_PKCS7, PEM_write_bio_PKCS7, PEM_write_PKCS7, PEM_read_bio_NETSCAPE_CERT_SEQUENCE, PEM_read_NETSCAPE_CERT_SEQUENCE, PEM_write_bio_NETSCAPE_CERT_SEQUENCE, PEM_write_NETSCAPE_CERT_SEQUENCE - PEM routines
PEM, PEM_read_bio_PrivateKey, PEM_read_PrivateKey, PEM_write_bio_PrivateKey,
PEM_write_PrivateKey, PEM_write_bio_PKCS8PrivateKey, PEM_write_PKCS8PrivateKey,
PEM_write_bio_PKCS8PrivateKey_nid, PEM_write_PKCS8PrivateKey_nid,
PEM_read_bio_PUBKEY, PEM_read_PUBKEY, PEM_write_bio_PUBKEY, PEM_write_PUBKEY,
PEM_read_bio_RSAPrivateKey, PEM_read_RSAPrivateKey,
PEM_write_bio_RSAPrivateKey, PEM_write_RSAPrivateKey,
PEM_read_bio_RSAPublicKey, PEM_read_RSAPublicKey, PEM_write_bio_RSAPublicKey,
PEM_write_RSAPublicKey, PEM_read_bio_RSA_PUBKEY, PEM_read_RSA_PUBKEY,
PEM_write_bio_RSA_PUBKEY, PEM_write_RSA_PUBKEY, PEM_read_bio_DSAPrivateKey,
PEM_read_DSAPrivateKey, PEM_write_bio_DSAPrivateKey, PEM_write_DSAPrivateKey,
PEM_read_bio_DSA_PUBKEY, PEM_read_DSA_PUBKEY, PEM_write_bio_DSA_PUBKEY,
PEM_write_DSA_PUBKEY, PEM_read_bio_DSAparams, PEM_read_DSAparams,
PEM_write_bio_DSAparams, PEM_write_DSAparams, PEM_read_bio_DHparams,
PEM_read_DHparams, PEM_write_bio_DHparams, PEM_write_DHparams,
PEM_read_bio_X509, PEM_read_X509, PEM_write_bio_X509, PEM_write_X509,
PEM_read_bio_X509_AUX, PEM_read_X509_AUX, PEM_write_bio_X509_AUX,
PEM_write_X509_AUX, PEM_read_bio_X509_REQ, PEM_read_X509_REQ,
PEM_write_bio_X509_REQ, PEM_write_X509_REQ, PEM_write_bio_X509_REQ_NEW,
PEM_write_X509_REQ_NEW, PEM_read_bio_X509_CRL, PEM_read_X509_CRL,
PEM_write_bio_X509_CRL, PEM_write_X509_CRL, PEM_read_bio_PKCS7, PEM_read_PKCS7,
PEM_write_bio_PKCS7, PEM_write_PKCS7, PEM_read_bio_NETSCAPE_CERT_SEQUENCE,
PEM_read_NETSCAPE_CERT_SEQUENCE, PEM_write_bio_NETSCAPE_CERT_SEQUENCE,
PEM_write_NETSCAPE_CERT_SEQUENCE - PEM routines
=head1 SYNOPSIS
@@ -201,7 +223,7 @@ handle PKCS#8 format encrypted and unencrypted keys too.
PEM_write_bio_PKCS8PrivateKey() and PEM_write_PKCS8PrivateKey()
write a private key in an EVP_PKEY structure in PKCS#8
EncryptedPrivateKeyInfo format using PKCS#5 v2.0 password based encryption
algorithms. The B<cipher> argument specifies the encryption algoritm to
algorithms. The B<cipher> argument specifies the encryption algorithm to
use: unlike all other PEM routines the encryption is applied at the
PKCS#8 level and not in the PEM headers. If B<cipher> is NULL then no
encryption is used and a PKCS#8 PrivateKeyInfo structure is used instead.
@@ -239,7 +261,8 @@ SubjectPublicKeyInfo structure and an error occurs if the public
key is not DSA.
The B<DSAparams> functions process DSA parameters using a DSA
structure. The parameters are encoded using a foobar structure.
structure. The parameters are encoded using a Dss-Parms structure
as defined in RFC2459.
The B<DHparams> functions process DH parameters using a DH
structure. The parameters are encoded using a PKCS#3 DHparameter
@@ -450,9 +473,9 @@ byte B<salt> encoded as a set of hexadecimal digits.
After this is the base64 encoded encrypted data.
The encryption key is determined using EVP_bytestokey(), using B<salt> and an
The encryption key is determined using EVP_BytesToKey(), using B<salt> and an
iteration count of 1. The IV used is the value of B<salt> and *not* the IV
returned by EVP_bytestokey().
returned by EVP_BytesToKey().
=head1 BUGS
@@ -474,3 +497,7 @@ The read routines return either a pointer to the structure read or NULL
if an error occurred.
The write routines return 1 for success or 0 for failure.
=head1 SEE ALSO
L<EVP_get_cipherbyname(3)|EVP_get_cipherbyname>, L<EVP_BytesToKey(3)|EVP_BytesToKey(3)>

2
doc/crypto/rand.pod
View File

@@ -39,7 +39,7 @@ 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 recommened
"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

64
doc/crypto/sha.pod
View File

@@ -2,29 +2,58 @@
=head1 NAME
SHA1, SHA1_Init, SHA1_Update, SHA1_Final - Secure Hash Algorithm
SHA1, SHA1_Init, SHA1_Update, SHA1_Final, SHA224, SHA224_Init, SHA224_Update,
SHA224_Final, SHA256, SHA256_Init, SHA256_Update, SHA256_Final, SHA384,
SHA384_Init, SHA384_Update, SHA384_Final, SHA512, SHA512_Init, SHA512_Update,
SHA512_Final - Secure Hash Algorithm
=head1 SYNOPSIS
#include <openssl/sha.h>
unsigned char *SHA1(const unsigned char *d, unsigned long n,
unsigned char *md);
int SHA1_Init(SHA_CTX *c);
int SHA1_Update(SHA_CTX *c, const void *data,
unsigned long len);
int SHA1_Update(SHA_CTX *c, const void *data, size_t len);
int SHA1_Final(unsigned char *md, SHA_CTX *c);
unsigned char *SHA1(const unsigned char *d, size_t n,
unsigned char *md);
int SHA224_Init(SHA256_CTX *c);
int SHA224_Update(SHA256_CTX *c, const void *data, size_t len);
int SHA224_Final(unsigned char *md, SHA256_CTX *c);
unsigned char *SHA224(const unsigned char *d, size_t n,
unsigned char *md);
int SHA256_Init(SHA256_CTX *c);
int SHA256_Update(SHA256_CTX *c, const void *data, size_t len);
int SHA256_Final(unsigned char *md, SHA256_CTX *c);
unsigned char *SHA256(const unsigned char *d, size_t n,
unsigned char *md);
int SHA384_Init(SHA512_CTX *c);
int SHA384_Update(SHA512_CTX *c, const void *data, size_t len);
int SHA384_Final(unsigned char *md, SHA512_CTX *c);
unsigned char *SHA384(const unsigned char *d, size_t n,
unsigned char *md);
int SHA512_Init(SHA512_CTX *c);
int SHA512_Update(SHA512_CTX *c, const void *data, size_t len);
int SHA512_Final(unsigned char *md, SHA512_CTX *c);
unsigned char *SHA512(const unsigned char *d, size_t n,
unsigned char *md);
=head1 DESCRIPTION
Applications should use the higher level functions
L<EVP_DigestInit(3)|EVP_DigestInit(3)> etc. instead of calling the hash
functions directly.
SHA-1 (Secure Hash Algorithm) is a cryptographic hash function with a
160 bit output.
SHA1() computes the SHA-1 message digest of the B<n>
bytes at B<d> and places it in B<md> (which must have space for
SHA_DIGEST_LENGTH == 20 bytes of output). If B<md> is NULL, the digest
is placed in a static array.
is placed in a static array. Note: setting B<md> to NULL is B<not thread safe>.
The following functions may be used if the message is not completely
stored in memory:
@@ -37,24 +66,29 @@ be hashed (B<len> bytes at B<data>).
SHA1_Final() places the message digest in B<md>, which must have space
for SHA_DIGEST_LENGTH == 20 bytes of output, and erases the B<SHA_CTX>.
Applications should use the higher level functions
L<EVP_DigestInit(3)|EVP_DigestInit(3)>
etc. instead of calling the hash functions directly.
The SHA224, SHA256, SHA384 and SHA512 families of functions operate in the
same way as for the SHA1 functions. Note that SHA224 and SHA256 use a
B<SHA256_CTX> object instead of B<SHA_CTX>. SHA384 and SHA512 use B<SHA512_CTX>.
The buffer B<md> must have space for the output from the SHA variant being used
(defined by SHA224_DIGEST_LENGTH, SHA256_DIGEST_LENGTH, SHA384_DIGEST_LENGTH and
SHA512_DIGEST_LENGTH). Also note that, as for the SHA1() function above, the
SHA224(), SHA256(), SHA384() and SHA512() functions are not thread safe if
B<md> is NULL.
The predecessor of SHA-1, SHA, is also implemented, but it should be
used only when backward compatibility is required.
=head1 RETURN VALUES
SHA1() returns a pointer to the hash value.
SHA1(), SHA224(), SHA256(), SHA384() and SHA512() return a pointer to the hash
value.
SHA1_Init(), SHA1_Update() and SHA1_Final() return 1 for success, 0 otherwise.
SHA1_Init(), SHA1_Update() and SHA1_Final() and equivalent SHA224, SHA256,
SHA384 and SHA512 functions return 1 for success, 0 otherwise.
=head1 CONFORMING TO
SHA: US Federal Information Processing Standard FIPS PUB 180 (Secure Hash
Standard),
SHA-1: US Federal Information Processing Standard FIPS PUB 180-1 (Secure Hash
US Federal Information Processing Standard FIPS PUB 180-4 (Secure Hash
Standard),
ANSI X9.30

2
doc/crypto/ui.pod
View File

@@ -119,7 +119,7 @@ verification will fail.
UI_add_input_boolean() adds a prompt to the UI that's supposed to be answered
in a boolean way, with a single character for yes and a different character
for no. A set of characters that can be used to cancel the prompt is given
as well. The prompt itself is really divided in two, one part being the
as well. The prompt itself is divided in two, one part being the
descriptive text (given through the I<prompt> argument) and one describing
the possible answers (given through the I<action_desc> argument).