fthielen/nginx-custom
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Initial Commit

Browse Source
This commit is contained in:
root
2017-02-25 23:55:24 +01:00
commit 1fe2e8ab62
4868 changed files with 1487355 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

45
openssl-1.0.2f/doc/crypto/ASN1_OBJECT_new.pod Normal file
View File

@@ -0,0 +1,45 @@
=pod
=head1 NAME
ASN1_OBJECT_new, ASN1_OBJECT_free, - object allocation functions
=head1 SYNOPSIS
#include <openssl/asn1.h>
ASN1_OBJECT *ASN1_OBJECT_new(void);
void ASN1_OBJECT_free(ASN1_OBJECT *a);
=head1 DESCRIPTION
The ASN1_OBJECT allocation routines, allocate and free an
ASN1_OBJECT structure, which represents an ASN1 OBJECT IDENTIFIER.
ASN1_OBJECT_new() allocates and initializes a ASN1_OBJECT structure.
ASN1_OBJECT_free() frees up the B<ASN1_OBJECT> structure B<a>.
=head1 NOTES
Although ASN1_OBJECT_new() allocates a new ASN1_OBJECT structure it
is almost never used in applications. The ASN1 object utility functions
such as OBJ_nid2obj() are used instead.
=head1 RETURN VALUES
If the allocation fails, ASN1_OBJECT_new() returns B<NULL> and sets an error
code that can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
Otherwise it returns a pointer to the newly allocated structure.
ASN1_OBJECT_free() returns no value.
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>, L<d2i_ASN1_OBJECT(3)|d2i_ASN1_OBJECT(3)>
=head1 HISTORY
ASN1_OBJECT_new() and ASN1_OBJECT_free() are available in all versions of SSLeay and OpenSSL.
=cut

83
openssl-1.0.2f/doc/crypto/ASN1_STRING_length.pod Normal file
View File

@@ -0,0 +1,83 @@
=pod
=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_to_UTF8 -
ASN1_STRING utility functions
=head1 SYNOPSIS
#include <openssl/asn1.h>
int ASN1_STRING_length(ASN1_STRING *x);
unsigned char * ASN1_STRING_data(ASN1_STRING *x);
ASN1_STRING * ASN1_STRING_dup(ASN1_STRING *a);
int ASN1_STRING_cmp(ASN1_STRING *a, ASN1_STRING *b);
int ASN1_STRING_set(ASN1_STRING *str, const void *data, int len);
int ASN1_STRING_type(ASN1_STRING *x);
int ASN1_STRING_to_UTF8(unsigned char **out, ASN1_STRING *in);
=head1 DESCRIPTION
These functions allow an B<ASN1_STRING> structure to be manipulated.
ASN1_STRING_length() returns the length of the content of B<x>.
ASN1_STRING_data() returns an internal pointer to the data of B<x>.
Since this is an internal pointer it should B<not> be freed or
modified in any way.
ASN1_STRING_dup() returns a copy of the structure B<a>.
ASN1_STRING_cmp() compares B<a> and B<b> returning 0 if the two
are identical. The string types and content are compared.
ASN1_STRING_set() sets the data of string B<str> to the buffer
B<data> or length B<len>. The supplied data is copied. If B<len>
is -1 then the length is determined by strlen(data).
ASN1_STRING_type() returns the type of B<x>, using standard constants
such as B<V_ASN1_OCTET_STRING>.
ASN1_STRING_to_UTF8() converts the string B<in> to UTF8 format, the
converted data is allocated in a buffer in B<*out>. The length of
B<out> is returned or a negative error code. The buffer B<*out>
should be free using OPENSSL_free().
=head1 NOTES
Almost all ASN1 types in OpenSSL are represented as an B<ASN1_STRING>
structure. Other types such as B<ASN1_OCTET_STRING> are simply typedefed
to B<ASN1_STRING> and the functions call the B<ASN1_STRING> equivalents.
B<ASN1_STRING> is also used for some B<CHOICE> types which consist
entirely of primitive string types such as B<DirectoryString> and
B<Time>.
These functions should B<not> be used to examine or modify B<ASN1_INTEGER>
or B<ASN1_ENUMERATED> types: the relevant B<INTEGER> or B<ENUMERATED>
utility functions should be used instead.
In general it cannot be assumed that the data returned by ASN1_STRING_data()
is null terminated or does not contain embedded nulls. The actual format
of the data will depend on the actual string type itself: for example
for and IA5String the data will be ASCII, for a BMPString two bytes per
character in big endian format, UTF8String will be in UTF8 format.
Similar care should be take to ensure the data is in the correct format
when calling ASN1_STRING_set().
=head1 RETURN VALUES
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>
=head1 HISTORY
=cut

46
openssl-1.0.2f/doc/crypto/ASN1_STRING_new.pod Normal file
View File

@@ -0,0 +1,46 @@
=pod
=head1 NAME
ASN1_STRING_new, ASN1_STRING_type_new, ASN1_STRING_free -
ASN1_STRING allocation functions
=head1 SYNOPSIS
#include <openssl/asn1.h>
ASN1_STRING * ASN1_STRING_new(void);
ASN1_STRING * ASN1_STRING_type_new(int type);
void ASN1_STRING_free(ASN1_STRING *a);
=head1 DESCRIPTION
ASN1_STRING_new() returns an allocated B<ASN1_STRING> structure. Its type
is undefined.
ASN1_STRING_type_new() returns an allocated B<ASN1_STRING> structure of
type B<type>.
ASN1_STRING_free() frees up B<a>.
=head1 NOTES
Other string types call the B<ASN1_STRING> functions. For example
ASN1_OCTET_STRING_new() calls ASN1_STRING_type(V_ASN1_OCTET_STRING).
=head1 RETURN VALUES
ASN1_STRING_new() and ASN1_STRING_type_new() return a valid
ASN1_STRING structure or B<NULL> if an error occurred.
ASN1_STRING_free() does not return a value.
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>
=head1 HISTORY
TBA
=cut

96
openssl-1.0.2f/doc/crypto/ASN1_STRING_print_ex.pod Normal file
View File

@@ -0,0 +1,96 @@
=pod
=head1 NAME
ASN1_STRING_print_ex, ASN1_STRING_print_ex_fp, ASN1_STRING_print - ASN1_STRING output routines.
=head1 SYNOPSIS
#include <openssl/asn1.h>
int ASN1_STRING_print_ex(BIO *out, ASN1_STRING *str, unsigned long flags);
int ASN1_STRING_print_ex_fp(FILE *fp, ASN1_STRING *str, unsigned long flags);
int ASN1_STRING_print(BIO *out, ASN1_STRING *str);
=head1 DESCRIPTION
These functions output an B<ASN1_STRING> structure. B<ASN1_STRING> is used to
represent all the ASN1 string types.
ASN1_STRING_print_ex() outputs B<str> to B<out>, the format is determined by
the options B<flags>. ASN1_STRING_print_ex_fp() is identical except it outputs
to B<fp> instead.
ASN1_STRING_print() prints B<str> to B<out> but using a different format to
ASN1_STRING_print_ex(). It replaces unprintable characters (other than CR, LF)
with '.'.
=head1 NOTES
ASN1_STRING_print() is a legacy function which should be avoided in new applications.
Although there are a large number of options frequently B<ASN1_STRFLGS_RFC2253> is
suitable, or on UTF8 terminals B<ASN1_STRFLGS_RFC2253 & ~ASN1_STRFLGS_ESC_MSB>.
The complete set of supported options for B<flags> is listed below.
Various characters can be escaped. If B<ASN1_STRFLGS_ESC_2253> is set the characters
determined by RFC2253 are escaped. If B<ASN1_STRFLGS_ESC_CTRL> is set control
characters are escaped. If B<ASN1_STRFLGS_ESC_MSB> is set characters with the
MSB set are escaped: this option should B<not> be used if the terminal correctly
interprets UTF8 sequences.
Escaping takes several forms.
If the character being escaped is a 16 bit character then the form "\UXXXX" is used
using exactly four characters for the hex representation. If it is 32 bits then
"\WXXXXXXXX" is used using eight characters of its hex representation. These forms
will only be used if UTF8 conversion is not set (see below).
Printable characters are normally escaped using the backslash '\' character. If
B<ASN1_STRFLGS_ESC_QUOTE> is set then the whole string is instead surrounded by
double quote characters: this is arguably more readable than the backslash
notation. Other characters use the "\XX" using exactly two characters of the hex
representation.
If B<ASN1_STRFLGS_UTF8_CONVERT> is set then characters are converted to UTF8
format first. If the terminal supports the display of UTF8 sequences then this
option will correctly display multi byte characters.
If B<ASN1_STRFLGS_IGNORE_TYPE> is set then the string type is not interpreted at
all: everything is assumed to be one byte per character. This is primarily for
debugging purposes and can result in confusing output in multi character strings.
If B<ASN1_STRFLGS_SHOW_TYPE> is set then the string type itself is printed out
before its value (for example "BMPSTRING"), this actually uses ASN1_tag2str().
The content of a string instead of being interpreted can be "dumped": this just
outputs the value of the string using the form #XXXX using hex format for each
octet.
If B<ASN1_STRFLGS_DUMP_ALL> is set then any type is dumped.
Normally non character string types (such as OCTET STRING) are assumed to be
one byte per character, if B<ASN1_STRFLGS_DUMP_UNKNOWN> is set then they will
be dumped instead.
When a type is dumped normally just the content octets are printed, if
B<ASN1_STRFLGS_DUMP_DER> is set then the complete encoding is dumped
instead (including tag and length octets).
B<ASN1_STRFLGS_RFC2253> includes all the flags required by RFC2253. It is
equivalent to:
ASN1_STRFLGS_ESC_2253 | ASN1_STRFLGS_ESC_CTRL | ASN1_STRFLGS_ESC_MSB |
ASN1_STRFLGS_UTF8_CONVERT | ASN1_STRFLGS_DUMP_UNKNOWN ASN1_STRFLGS_DUMP_DER
=head1 SEE ALSO
L<X509_NAME_print_ex(3)|X509_NAME_print_ex(3)>,
L<ASN1_tag2str(3)|ASN1_tag2str(3)>
=head1 HISTORY
TBA
=cut

129
openssl-1.0.2f/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

265
openssl-1.0.2f/doc/crypto/ASN1_generate_nconf.pod Normal file
View File

@@ -0,0 +1,265 @@
=pod
=head1 NAME
ASN1_generate_nconf, ASN1_generate_v3 - ASN1 generation functions
=head1 SYNOPSIS
#include <openssl/asn1.h>
ASN1_TYPE *ASN1_generate_nconf(char *str, CONF *nconf);
ASN1_TYPE *ASN1_generate_v3(char *str, X509V3_CTX *cnf);
=head1 DESCRIPTION
These functions generate the ASN1 encoding of a string
in an B<ASN1_TYPE> structure.
B<str> contains the string to encode B<nconf> or B<cnf> contains
the optional configuration information where additional strings
will be read from. B<nconf> will typically come from a config
file wherease B<cnf> is obtained from an B<X509V3_CTX> structure
which will typically be used by X509 v3 certificate extension
functions. B<cnf> or B<nconf> can be set to B<NULL> if no additional
configuration will be used.
=head1 GENERATION STRING FORMAT
The actual data encoded is determined by the string B<str> and
the configuration information. The general format of the string
is:
=over 2
=item B<[modifier,]type[:value]>
=back
That is zero or more comma separated modifiers followed by a type
followed by an optional colon and a value. The formats of B<type>,
B<value> and B<modifier> are explained below.
=head2 SUPPORTED TYPES
The supported types are listed below. Unless otherwise specified
only the B<ASCII> format is permissible.
=over 2
=item B<BOOLEAN>, B<BOOL>
This encodes a boolean type. The B<value> string is mandatory and
should be B<TRUE> or B<FALSE>. Additionally B<TRUE>, B<true>, B<Y>,
B<y>, B<YES>, B<yes>, B<FALSE>, B<false>, B<N>, B<n>, B<NO> and B<no>
are acceptable.
=item B<NULL>
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 prefaced by a minus sign and
is normally interpreted as a decimal value unless the prefix B<0x>
is included.
=item B<ENUMERATED>, B<ENUM>
Encodes the ASN1 B<ENUMERATED> type, it is otherwise identical to
B<INTEGER>.
=item B<OBJECT>, B<OID>
Encodes an ASN1 B<OBJECT IDENTIFIER>, the B<value> string can be
a short name, a long name or numerical format.
=item B<UTCTIME>, B<UTC>
Encodes an ASN1 B<UTCTime> structure, the value should be in
the format B<YYMMDDHHMMSSZ>.
=item B<GENERALIZEDTIME>, B<GENTIME>
Encodes an ASN1 B<GeneralizedTime> structure, the value should be in
the format B<YYYYMMDDHHMMSSZ>.
=item B<OCTETSTRING>, B<OCT>
Encodes an ASN1 B<OCTET STRING>. B<value> represents the contents
of this structure, the format strings B<ASCII> and B<HEX> can be
used to specify the format of B<value>.
=item B<BITSTRING>, B<BITSTR>
Encodes an ASN1 B<BIT STRING>. B<value> represents the contents
of this structure, the format strings B<ASCII>, B<HEX> and B<BITLIST>
can be used to specify the format of B<value>.
If the format is anything other than B<BITLIST> the number of unused
bits is set to zero.
=item B<UNIVERSALSTRING>, B<UNIV>, B<IA5>, B<IA5STRING>, B<UTF8>,
B<UTF8String>, B<BMP>, B<BMPSTRING>, B<VISIBLESTRING>,
B<VISIBLE>, B<PRINTABLESTRING>, B<PRINTABLE>, B<T61>,
B<T61STRING>, B<TELETEXSTRING>, B<GeneralString>, B<NUMERICSTRING>,
B<NUMERIC>
These encode the corresponding string types. B<value> represents the
contents of this structure. The format can be B<ASCII> or B<UTF8>.
=item B<SEQUENCE>, B<SEQ>, B<SET>
Formats the result as an ASN1 B<SEQUENCE> or B<SET> type. B<value>
should be a section name which will contain the contents. The
field names in the section are ignored and the values are in the
generated string format. If B<value> is absent then an empty SEQUENCE
will be encoded.
=back
=head2 MODIFIERS
Modifiers affect the following structure, they can be used to
add EXPLICIT or IMPLICIT tagging, add wrappers or to change
the string format of the final type and value. The supported
formats are documented below.
=over 2
=item B<EXPLICIT>, B<EXP>
Add an explicit tag to the following structure. This string
should be followed by a colon and the tag value to use as a
decimal value.
By following the number with B<U>, B<A>, B<P> or B<C> UNIVERSAL,
APPLICATION, PRIVATE or CONTEXT SPECIFIC tagging can be used,
the default is CONTEXT SPECIFIC.
=item B<IMPLICIT>, B<IMP>
This is the same as B<EXPLICIT> except IMPLICIT tagging is used
instead.
=item B<OCTWRAP>, B<SEQWRAP>, B<SETWRAP>, B<BITWRAP>
The following structure is surrounded by an OCTET STRING, a SEQUENCE,
a SET or a BIT STRING respectively. For a BIT STRING the number of unused
bits is set to zero.
=item B<FORMAT>
This specifies the format of the ultimate value. It should be followed
by a colon and one of the strings B<ASCII>, B<UTF8>, B<HEX> or B<BITLIST>.
If no format specifier is included then B<ASCII> is used. If B<UTF8> is
specified then the value string must be a valid B<UTF8> string. For B<HEX> the
output must be a set of hex digits. B<BITLIST> (which is only valid for a BIT
STRING) is a comma separated list of the indices of the set bits, all other
bits are zero.
=back
=head1 EXAMPLES
A simple IA5String:
IA5STRING:Hello World
An IA5String explicitly tagged:
EXPLICIT:0,IA5STRING:Hello World
An IA5String explicitly tagged using APPLICATION tagging:
EXPLICIT:0A,IA5STRING:Hello World
A BITSTRING with bits 1 and 5 set and all others zero:
FORMAT:BITLIST,BITSTRING:1,5
A more complex example using a config file to produce a
SEQUENCE consiting of a BOOL an OID and a UTF8String:
asn1 = SEQUENCE:seq_section
[seq_section]
field1 = BOOLEAN:TRUE
field2 = OID:commonName
field3 = UTF8:Third field
This example produces an RSAPrivateKey structure, this is the
key contained in the file client.pem in all OpenSSL distributions
(note: the field names such as 'coeff' are ignored and are present just
for clarity):
asn1=SEQUENCE:private_key
[private_key]
version=INTEGER:0
n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\
D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
e=INTEGER:0x010001
d=INTEGER:0x6F05EAD2F27FFAEC84BEC360C4B928FD5F3A9865D0FCAAD291E2A52F4A\
F810DC6373278C006A0ABBA27DC8C63BF97F7E666E27C5284D7D3B1FFFE16B7A87B51D
p=INTEGER:0xF3929B9435608F8A22C208D86795271D54EBDFB09DDEF539AB083DA912\
D4BD57
q=INTEGER:0xC50016F89DFF2561347ED1186A46E150E28BF2D0F539A1594BBD7FE467\
46EC4F
exp1=INTEGER:0x9E7D4326C924AFC1DEA40B45650134966D6F9DFA3A7F9D698CD4ABEA\
9C0A39B9
exp2=INTEGER:0xBA84003BB95355AFB7C50DF140C60513D0BA51D637272E355E397779\
E7B2458F
coeff=INTEGER:0x30B9E4F2AFA5AC679F920FC83F1F2DF1BAF1779CF989447FABC2F5\
628657053A
This example is the corresponding public key in a SubjectPublicKeyInfo
structure:
# Start with a SEQUENCE
asn1=SEQUENCE:pubkeyinfo
# pubkeyinfo contains an algorithm identifier and the public key wrapped
# in a BIT STRING
[pubkeyinfo]
algorithm=SEQUENCE:rsa_alg
pubkey=BITWRAP,SEQUENCE:rsapubkey
# algorithm ID for RSA is just an OID and a NULL
[rsa_alg]
algorithm=OID:rsaEncryption
parameter=NULL
# Actual public key: modulus and exponent
[rsapubkey]
n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\
D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
e=INTEGER:0x010001
=head1 RETURN VALUES
ASN1_generate_nconf() and ASN1_generate_v3() return the encoded
data as an B<ASN1_TYPE> structure or B<NULL> if an error occurred.
The error codes that can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>
=head1 HISTORY
ASN1_generate_nconf() and ASN1_generate_v3() were added to OpenSSL 0.9.8
=cut

128
openssl-1.0.2f/doc/crypto/BIO_ctrl.pod Normal file
View File

@@ -0,0 +1,128 @@
=pod
=head1 NAME
BIO_ctrl, BIO_callback_ctrl, BIO_ptr_ctrl, BIO_int_ctrl, BIO_reset,
BIO_seek, BIO_tell, BIO_flush, BIO_eof, BIO_set_close, BIO_get_close,
BIO_pending, BIO_wpending, BIO_ctrl_pending, BIO_ctrl_wpending,
BIO_get_info_callback, BIO_set_info_callback - BIO control operations
=head1 SYNOPSIS
#include <openssl/bio.h>
long BIO_ctrl(BIO *bp,int cmd,long larg,void *parg);
long BIO_callback_ctrl(BIO *b, int cmd, void (*fp)(struct bio_st *, int, const char *, int, long, long));
char * BIO_ptr_ctrl(BIO *bp,int cmd,long larg);
long BIO_int_ctrl(BIO *bp,int cmd,long larg,int iarg);
int BIO_reset(BIO *b);
int BIO_seek(BIO *b, int ofs);
int BIO_tell(BIO *b);
int BIO_flush(BIO *b);
int BIO_eof(BIO *b);
int BIO_set_close(BIO *b,long flag);
int BIO_get_close(BIO *b);
int BIO_pending(BIO *b);
int BIO_wpending(BIO *b);
size_t BIO_ctrl_pending(BIO *b);
size_t BIO_ctrl_wpending(BIO *b);
int BIO_get_info_callback(BIO *b,bio_info_cb **cbp);
int BIO_set_info_callback(BIO *b,bio_info_cb *cb);
typedef void bio_info_cb(BIO *b, int oper, const char *ptr, int arg1, long arg2, long arg3);
=head1 DESCRIPTION
BIO_ctrl(), BIO_callback_ctrl(), BIO_ptr_ctrl() and BIO_int_ctrl()
are BIO "control" operations taking arguments of various types.
These functions are not normally called directly, various macros
are used instead. The standard macros are described below, macros
specific to a particular type of BIO are described in the specific
BIOs manual page as well as any special features of the standard
calls.
BIO_reset() typically resets a BIO to some initial state, in the case
of file related BIOs for example it rewinds the file pointer to the
start of the file.
BIO_seek() resets a file related BIO's (that is file descriptor and
FILE BIOs) file position pointer to B<ofs> bytes from start of file.
BIO_tell() returns the current file position of a file related BIO.
BIO_flush() normally writes out any internally buffered data, in some
cases it is used to signal EOF and that no more data will be written.
BIO_eof() returns 1 if the BIO has read EOF, the precise meaning of
"EOF" varies according to the BIO type.
BIO_set_close() sets the BIO B<b> close flag to B<flag>. B<flag> can
take the value BIO_CLOSE or BIO_NOCLOSE. Typically BIO_CLOSE is used
in a source/sink BIO to indicate that the underlying I/O stream should
be closed when the BIO is freed.
BIO_get_close() returns the BIOs close flag.
BIO_pending(), BIO_ctrl_pending(), BIO_wpending() and BIO_ctrl_wpending()
return the number of pending characters in the BIOs read and write buffers.
Not all BIOs support these calls. BIO_ctrl_pending() and BIO_ctrl_wpending()
return a size_t type and are functions, BIO_pending() and BIO_wpending() are
macros which call BIO_ctrl().
=head1 RETURN VALUES
BIO_reset() normally returns 1 for success and 0 or -1 for failure. File
BIOs are an exception, they return 0 for success and -1 for failure.
BIO_seek() and BIO_tell() both return the current file position on success
and -1 for failure, except file BIOs which for BIO_seek() always return 0
for success and -1 for failure.
BIO_flush() returns 1 for success and 0 or -1 for failure.
BIO_eof() returns 1 if EOF has been reached 0 otherwise.
BIO_set_close() always returns 1.
BIO_get_close() returns the close flag value: BIO_CLOSE or BIO_NOCLOSE.
BIO_pending(), BIO_ctrl_pending(), BIO_wpending() and BIO_ctrl_wpending()
return the amount of pending data.
=head1 NOTES
BIO_flush(), because it can write data may return 0 or -1 indicating
that the call should be retried later in a similar manner to BIO_write().
The BIO_should_retry() call should be used and appropriate action taken
is the call fails.
The return values of BIO_pending() and BIO_wpending() may not reliably
determine the amount of pending data in all cases. For example in the
case of a file BIO some data may be available in the FILE structures
internal buffers but it is not possible to determine this in a
portably way. For other types of BIO they may not be supported.
Filter BIOs if they do not internally handle a particular BIO_ctrl()
operation usually pass the operation to the next BIO in the chain.
This often means there is no need to locate the required BIO for
a particular operation, it can be called on a chain and it will
be automatically passed to the relevant BIO. However this can cause
unexpected results: for example no current filter BIOs implement
BIO_seek(), but this may still succeed if the chain ends in a FILE
or file descriptor BIO.
Source/sink BIOs return an 0 if they do not recognize the BIO_ctrl()
operation.
=head1 BUGS
Some of the return values are ambiguous and care should be taken. In
particular a return value of 0 can be returned if an operation is not
supported, if an error occurred, if EOF has not been reached and in
the case of BIO_seek() on a file BIO for a successful operation.
=head1 SEE ALSO
TBA

82
openssl-1.0.2f/doc/crypto/BIO_f_base64.pod Normal file
View File

@@ -0,0 +1,82 @@
=pod
=head1 NAME
BIO_f_base64 - base64 BIO filter
=head1 SYNOPSIS
#include <openssl/bio.h>
#include <openssl/evp.h>
BIO_METHOD * BIO_f_base64(void);
=head1 DESCRIPTION
BIO_f_base64() returns the base64 BIO method. This is a filter
BIO that base64 encodes any data written through it and decodes
any data read through it.
Base64 BIOs do not support BIO_gets() or BIO_puts().
BIO_flush() on a base64 BIO that is being written through is
used to signal that no more data is to be encoded: this is used
to flush the final block through the BIO.
The flag BIO_FLAGS_BASE64_NO_NL can be set with BIO_set_flags()
to encode the data all on one line or expect the data to be all
on one line.
=head1 NOTES
Because of the format of base64 encoding the end of the encoded
block cannot always be reliably determined.
=head1 RETURN VALUES
BIO_f_base64() returns the base64 BIO method.
=head1 EXAMPLES
Base64 encode the string "Hello World\n" and write the result
to standard output:
BIO *bio, *b64;
char message[] = "Hello World \n";
b64 = BIO_new(BIO_f_base64());
bio = BIO_new_fp(stdout, BIO_NOCLOSE);
BIO_push(b64, bio);
BIO_write(b64, message, strlen(message));
BIO_flush(b64);
BIO_free_all(b64);
Read Base64 encoded data from standard input and write the decoded
data to standard output:
BIO *bio, *b64, *bio_out;
char inbuf[512];
int inlen;
b64 = BIO_new(BIO_f_base64());
bio = BIO_new_fp(stdin, BIO_NOCLOSE);
bio_out = BIO_new_fp(stdout, BIO_NOCLOSE);
BIO_push(b64, bio);
while((inlen = BIO_read(b64, inbuf, 512)) > 0)
BIO_write(bio_out, inbuf, inlen);
BIO_flush(bio_out);
BIO_free_all(b64);
=head1 BUGS
The ambiguity of EOF in base64 encoded data can cause additional
data following the base64 encoded block to be misinterpreted.
There should be some way of specifying a test that the BIO can perform
to reliably determine EOF (for example a MIME boundary).
=head1 SEE ALSO
TBA

74
openssl-1.0.2f/doc/crypto/BIO_f_buffer.pod Normal file
View File

@@ -0,0 +1,74 @@
=pod
=head1 NAME
BIO_f_buffer - buffering BIO
=head1 SYNOPSIS
#include <openssl/bio.h>
BIO_METHOD * BIO_f_buffer(void);
#define BIO_get_buffer_num_lines(b) BIO_ctrl(b,BIO_C_GET_BUFF_NUM_LINES,0,NULL)
#define BIO_set_read_buffer_size(b,size) BIO_int_ctrl(b,BIO_C_SET_BUFF_SIZE,size,0)
#define BIO_set_write_buffer_size(b,size) BIO_int_ctrl(b,BIO_C_SET_BUFF_SIZE,size,1)
#define BIO_set_buffer_size(b,size) BIO_ctrl(b,BIO_C_SET_BUFF_SIZE,size,NULL)
#define BIO_set_buffer_read_data(b,buf,num) BIO_ctrl(b,BIO_C_SET_BUFF_READ_DATA,num,buf)
=head1 DESCRIPTION
BIO_f_buffer() returns the buffering BIO method.
Data written to a buffering BIO is buffered and periodically written
to the next BIO in the chain. Data read from a buffering BIO comes from
an internal buffer which is filled from the next BIO in the chain.
Both BIO_gets() and BIO_puts() are supported.
Calling BIO_reset() on a buffering BIO clears any buffered data.
BIO_get_buffer_num_lines() returns the number of lines currently buffered.
BIO_set_read_buffer_size(), BIO_set_write_buffer_size() and BIO_set_buffer_size()
set the read, write or both read and write buffer sizes to B<size>. The initial
buffer size is DEFAULT_BUFFER_SIZE, currently 4096. Any attempt to reduce the
buffer size below DEFAULT_BUFFER_SIZE is ignored. Any buffered data is cleared
when the buffer is resized.
BIO_set_buffer_read_data() clears the read buffer and fills it with B<num>
bytes of B<buf>. If B<num> is larger than the current buffer size the buffer
is expanded.
=head1 NOTES
Buffering BIOs implement BIO_gets() by using BIO_read() operations on the
next BIO in the chain. By prepending a buffering BIO to a chain it is therefore
possible to provide BIO_gets() functionality if the following BIOs do not
support it (for example SSL BIOs).
Data is only written to the next BIO in the chain when the write buffer fills
or when BIO_flush() is called. It is therefore important to call BIO_flush()
whenever any pending data should be written such as when removing a buffering
BIO using BIO_pop(). BIO_flush() may need to be retried if the ultimate
source/sink BIO is non blocking.
=head1 RETURN VALUES
BIO_f_buffer() returns the buffering BIO method.
BIO_get_buffer_num_lines() returns the number of lines buffered (may be 0).
BIO_set_read_buffer_size(), BIO_set_write_buffer_size() and BIO_set_buffer_size()
return 1 if the buffer was successfully resized or 0 for failure.
BIO_set_buffer_read_data() returns 1 if the data was set correctly or 0 if
there was an error.
=head1 SEE ALSO
L<BIO(3)|BIO(3)>,
L<BIO_reset(3)|BIO_reset(3)>,
L<BIO_flush(3)|BIO_flush(3)>,
L<BIO_pop(3)|BIO_pop(3)>,
L<BIO_ctrl(3)|BIO_ctrl(3)>,
L<BIO_int_ctrl(3)|BIO_ctrl(3)>

76
openssl-1.0.2f/doc/crypto/BIO_f_cipher.pod Normal file
View File

@@ -0,0 +1,76 @@
=pod
=head1 NAME
BIO_f_cipher, BIO_set_cipher, BIO_get_cipher_status, BIO_get_cipher_ctx - cipher BIO filter
=head1 SYNOPSIS
#include <openssl/bio.h>
#include <openssl/evp.h>
BIO_METHOD * BIO_f_cipher(void);
void BIO_set_cipher(BIO *b,const EVP_CIPHER *cipher,
unsigned char *key, unsigned char *iv, int enc);
int BIO_get_cipher_status(BIO *b)
int BIO_get_cipher_ctx(BIO *b, EVP_CIPHER_CTX **pctx)
=head1 DESCRIPTION
BIO_f_cipher() returns the cipher BIO method. This is a filter
BIO that encrypts any data written through it, and decrypts any data
read from it. It is a BIO wrapper for the cipher routines
EVP_CipherInit(), EVP_CipherUpdate() and EVP_CipherFinal().
Cipher BIOs do not support BIO_gets() or BIO_puts().
BIO_flush() on an encryption BIO that is being written through is
used to signal that no more data is to be encrypted: this is used
to flush and possibly pad the final block through the BIO.
BIO_set_cipher() sets the cipher of BIO B<b> to B<cipher> using key B<key>
and IV B<iv>. B<enc> should be set to 1 for encryption and zero for
decryption.
When reading from an encryption BIO the final block is automatically
decrypted and checked when EOF is detected. BIO_get_cipher_status()
is a BIO_ctrl() macro which can be called to determine whether the
decryption operation was successful.
BIO_get_cipher_ctx() is a BIO_ctrl() macro which retrieves the internal
BIO cipher context. The retrieved context can be used in conjunction
with the standard cipher routines to set it up. This is useful when
BIO_set_cipher() is not flexible enough for the applications needs.
=head1 NOTES
When encrypting BIO_flush() B<must> be called to flush the final block
through the BIO. If it is not then the final block will fail a subsequent
decrypt.
When decrypting an error on the final block is signalled by a zero
return value from the read operation. A successful decrypt followed
by EOF will also return zero for the final read. BIO_get_cipher_status()
should be called to determine if the decrypt was successful.
As always, if BIO_gets() or BIO_puts() support is needed then it can
be achieved by preceding the cipher BIO with a buffering BIO.
=head1 RETURN VALUES
BIO_f_cipher() returns the cipher BIO method.
BIO_set_cipher() does not return a value.
BIO_get_cipher_status() returns 1 for a successful decrypt and 0
for failure.
BIO_get_cipher_ctx() currently always returns 1.
=head1 EXAMPLES
TBA
=head1 SEE ALSO
TBA

144
openssl-1.0.2f/doc/crypto/BIO_f_md.pod Normal file
View File

@@ -0,0 +1,144 @@
=pod
=head1 NAME
BIO_f_md, BIO_set_md, BIO_get_md, BIO_get_md_ctx - message digest BIO filter
=head1 SYNOPSIS
#include <openssl/bio.h>
#include <openssl/evp.h>
BIO_METHOD * BIO_f_md(void);
int BIO_set_md(BIO *b,EVP_MD *md);
int BIO_get_md(BIO *b,EVP_MD **mdp);
int BIO_get_md_ctx(BIO *b,EVP_MD_CTX **mdcp);
=head1 DESCRIPTION
BIO_f_md() returns the message digest BIO method. This is a filter
BIO that digests any data passed through it, it is a BIO wrapper
for the digest routines EVP_DigestInit(), EVP_DigestUpdate()
and EVP_DigestFinal().
Any data written or read through a digest BIO using BIO_read() and
BIO_write() is digested.
BIO_gets(), if its B<size> parameter is large enough finishes the
digest calculation and returns the digest value. BIO_puts() is
not supported.
BIO_reset() reinitialises a digest BIO.
BIO_set_md() sets the message digest of BIO B<b> to B<md>: this
must be called to initialize a digest BIO before any data is
passed through it. It is a BIO_ctrl() macro.
BIO_get_md() places the a pointer to the digest BIOs digest method
in B<mdp>, it is a BIO_ctrl() macro.
BIO_get_md_ctx() returns the digest BIOs context into B<mdcp>.
=head1 NOTES
The context returned by BIO_get_md_ctx() can be used in calls
to EVP_DigestFinal() and also the signature routines EVP_SignFinal()
and EVP_VerifyFinal().
The context returned by BIO_get_md_ctx() is an internal context
structure. Changes made to this context will affect the digest
BIO itself and the context pointer will become invalid when the digest
BIO is freed.
After the digest has been retrieved from a digest BIO it must be
reinitialized by calling BIO_reset(), or BIO_set_md() before any more
data is passed through it.
If an application needs to call BIO_gets() or BIO_puts() through
a chain containing digest BIOs then this can be done by prepending
a buffering BIO.
Before OpenSSL 1.0.0 the call to BIO_get_md_ctx() would only work if the BIO
had been initialized for example by calling BIO_set_md() ). In OpenSSL
1.0.0 and later the context is always returned and the BIO is state is set
to initialized. This allows applications to initialize the context externally
if the standard calls such as BIO_set_md() are not sufficiently flexible.
=head1 RETURN VALUES
BIO_f_md() returns the digest BIO method.
BIO_set_md(), BIO_get_md() and BIO_md_ctx() return 1 for success and
0 for failure.
=head1 EXAMPLES
The following example creates a BIO chain containing an SHA1 and MD5
digest BIO and passes the string "Hello World" through it. Error
checking has been omitted for clarity.
BIO *bio, *mdtmp;
char message[] = "Hello World";
bio = BIO_new(BIO_s_null());
mdtmp = BIO_new(BIO_f_md());
BIO_set_md(mdtmp, EVP_sha1());
/* For BIO_push() we want to append the sink BIO and keep a note of
* the start of the chain.
*/
bio = BIO_push(mdtmp, bio);
mdtmp = BIO_new(BIO_f_md());
BIO_set_md(mdtmp, EVP_md5());
bio = BIO_push(mdtmp, bio);
/* Note: mdtmp can now be discarded */
BIO_write(bio, message, strlen(message));
The next example digests data by reading through a chain instead:
BIO *bio, *mdtmp;
char buf[1024];
int rdlen;
bio = BIO_new_file(file, "rb");
mdtmp = BIO_new(BIO_f_md());
BIO_set_md(mdtmp, EVP_sha1());
bio = BIO_push(mdtmp, bio);
mdtmp = BIO_new(BIO_f_md());
BIO_set_md(mdtmp, EVP_md5());
bio = BIO_push(mdtmp, bio);
do {
rdlen = BIO_read(bio, buf, sizeof(buf));
/* Might want to do something with the data here */
} while(rdlen > 0);
This next example retrieves the message digests from a BIO chain and
outputs them. This could be used with the examples above.
BIO *mdtmp;
unsigned char mdbuf[EVP_MAX_MD_SIZE];
int mdlen;
int i;
mdtmp = bio; /* Assume bio has previously been set up */
do {
EVP_MD *md;
mdtmp = BIO_find_type(mdtmp, BIO_TYPE_MD);
if(!mdtmp) break;
BIO_get_md(mdtmp, &md);
printf("%s digest", OBJ_nid2sn(EVP_MD_type(md)));
mdlen = BIO_gets(mdtmp, mdbuf, EVP_MAX_MD_SIZE);
for(i = 0; i < mdlen; i++) printf(":%02X", mdbuf[i]);
printf("\n");
mdtmp = BIO_next(mdtmp);
} while(mdtmp);
BIO_free_all(bio);
=head1 BUGS
The lack of support for BIO_puts() and the non standard behaviour of
BIO_gets() could be regarded as anomalous. It could be argued that BIO_gets()
and BIO_puts() should be passed to the next BIO in the chain and digest
the data passed through and that digests should be retrieved using a
separate BIO_ctrl() call.
=head1 SEE ALSO
TBA

32
openssl-1.0.2f/doc/crypto/BIO_f_null.pod Normal file
View File

@@ -0,0 +1,32 @@
=pod
=head1 NAME
BIO_f_null - null filter
=head1 SYNOPSIS
#include <openssl/bio.h>
BIO_METHOD * BIO_f_null(void);
=head1 DESCRIPTION
BIO_f_null() returns the null filter BIO method. This is a filter BIO
that does nothing.
All requests to a null filter BIO are passed through to the next BIO in
the chain: this means that a BIO chain containing a null filter BIO
behaves just as though the BIO was not there.
=head1 NOTES
As may be apparent a null filter BIO is not particularly useful.
=head1 RETURN VALUES
BIO_f_null() returns the null filter BIO method.
=head1 SEE ALSO
TBA

322
openssl-1.0.2f/doc/crypto/BIO_f_ssl.pod Normal file
View File

@@ -0,0 +1,322 @@
=pod
=head1 NAME
BIO_f_ssl, BIO_set_ssl, BIO_get_ssl, BIO_set_ssl_mode, BIO_set_ssl_renegotiate_bytes,
BIO_get_num_renegotiates, BIO_set_ssl_renegotiate_timeout, BIO_new_ssl,
BIO_new_ssl_connect, BIO_new_buffer_ssl_connect, BIO_ssl_copy_session_id,
BIO_ssl_shutdown - SSL BIO
=head1 SYNOPSIS
#include <openssl/bio.h>
#include <openssl/ssl.h>
BIO_METHOD *BIO_f_ssl(void);
#define BIO_set_ssl(b,ssl,c) BIO_ctrl(b,BIO_C_SET_SSL,c,(char *)ssl)
#define BIO_get_ssl(b,sslp) BIO_ctrl(b,BIO_C_GET_SSL,0,(char *)sslp)
#define BIO_set_ssl_mode(b,client) BIO_ctrl(b,BIO_C_SSL_MODE,client,NULL)
#define BIO_set_ssl_renegotiate_bytes(b,num) \
BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_BYTES,num,NULL);
#define BIO_set_ssl_renegotiate_timeout(b,seconds) \
BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_TIMEOUT,seconds,NULL);
#define BIO_get_num_renegotiates(b) \
BIO_ctrl(b,BIO_C_SET_SSL_NUM_RENEGOTIATES,0,NULL);
BIO *BIO_new_ssl(SSL_CTX *ctx,int client);
BIO *BIO_new_ssl_connect(SSL_CTX *ctx);
BIO *BIO_new_buffer_ssl_connect(SSL_CTX *ctx);
int BIO_ssl_copy_session_id(BIO *to,BIO *from);
void BIO_ssl_shutdown(BIO *bio);
#define BIO_do_handshake(b) BIO_ctrl(b,BIO_C_DO_STATE_MACHINE,0,NULL)
=head1 DESCRIPTION
BIO_f_ssl() returns the SSL BIO method. This is a filter BIO which
is a wrapper round the OpenSSL SSL routines adding a BIO "flavour" to
SSL I/O.
I/O performed on an SSL BIO communicates using the SSL protocol with
the SSLs read and write BIOs. If an SSL connection is not established
then an attempt is made to establish one on the first I/O call.
If a BIO is appended to an SSL BIO using BIO_push() it is automatically
used as the SSL BIOs read and write BIOs.
Calling BIO_reset() on an SSL BIO closes down any current SSL connection
by calling SSL_shutdown(). BIO_reset() is then sent to the next BIO in
the chain: this will typically disconnect the underlying transport.
The SSL BIO is then reset to the initial accept or connect state.
If the close flag is set when an SSL BIO is freed then the internal
SSL structure is also freed using SSL_free().
BIO_set_ssl() sets the internal SSL pointer of BIO B<b> to B<ssl> using
the close flag B<c>.
BIO_get_ssl() retrieves the SSL pointer of BIO B<b>, it can then be
manipulated using the standard SSL library functions.
BIO_set_ssl_mode() sets the SSL BIO mode to B<client>. If B<client>
is 1 client mode is set. If B<client> is 0 server mode is set.
BIO_set_ssl_renegotiate_bytes() sets the renegotiate byte count
to B<num>. When set after every B<num> bytes of I/O (read and write)
the SSL session is automatically renegotiated. B<num> must be at
least 512 bytes.
BIO_set_ssl_renegotiate_timeout() sets the renegotiate timeout to
B<seconds>. When the renegotiate timeout elapses the session is
automatically renegotiated.
BIO_get_num_renegotiates() returns the total number of session
renegotiations due to I/O or timeout.
BIO_new_ssl() allocates an SSL BIO using SSL_CTX B<ctx> and using
client mode if B<client> is non zero.
BIO_new_ssl_connect() creates a new BIO chain consisting of an
SSL BIO (using B<ctx>) followed by a connect BIO.
BIO_new_buffer_ssl_connect() creates a new BIO chain consisting
of a buffering BIO, an SSL BIO (using B<ctx>) and a connect
BIO.
BIO_ssl_copy_session_id() copies an SSL session id between
BIO chains B<from> and B<to>. It does this by locating the
SSL BIOs in each chain and calling SSL_copy_session_id() on
the internal SSL pointer.
BIO_ssl_shutdown() closes down an SSL connection on BIO
chain B<bio>. It does this by locating the SSL BIO in the
chain and calling SSL_shutdown() on its internal SSL
pointer.
BIO_do_handshake() attempts to complete an SSL handshake on the
supplied BIO and establish the SSL connection. It returns 1
if the connection was established successfully. A zero or negative
value is returned if the connection could not be established, the
call BIO_should_retry() should be used for non blocking connect BIOs
to determine if the call should be retried. If an SSL connection has
already been established this call has no effect.
=head1 NOTES
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 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
an SSL BIO using a blocking transport will never request a
retry.
Since unknown BIO_ctrl() operations are sent through filter
BIOs the servers name and port can be set using BIO_set_host()
on the BIO returned by BIO_new_ssl_connect() without having
to locate the connect BIO first.
Applications do not have to call BIO_do_handshake() but may wish
to do so to separate the handshake process from other I/O
processing.
=head1 RETURN VALUES
TBA
=head1 EXAMPLE
This SSL/TLS client example, attempts to retrieve a page from an
SSL/TLS web server. The I/O routines are identical to those of the
unencrypted example in L<BIO_s_connect(3)|BIO_s_connect(3)>.
BIO *sbio, *out;
int len;
char tmpbuf[1024];
SSL_CTX *ctx;
SSL *ssl;
ERR_load_crypto_strings();
ERR_load_SSL_strings();
OpenSSL_add_all_algorithms();
/* We would seed the PRNG here if the platform didn't
* do it automatically
*/
ctx = SSL_CTX_new(SSLv23_client_method());
/* We'd normally set some stuff like the verify paths and
* mode here because as things stand this will connect to
* any server whose certificate is signed by any CA.
*/
sbio = BIO_new_ssl_connect(ctx);
BIO_get_ssl(sbio, &ssl);
if(!ssl) {
fprintf(stderr, "Can't locate SSL pointer\n");
/* whatever ... */
}
/* Don't want any retries */
SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY);
/* We might want to do other things with ssl here */
BIO_set_conn_hostname(sbio, "localhost:https");
out = BIO_new_fp(stdout, BIO_NOCLOSE);
if(BIO_do_connect(sbio) <= 0) {
fprintf(stderr, "Error connecting to server\n");
ERR_print_errors_fp(stderr);
/* whatever ... */
}
if(BIO_do_handshake(sbio) <= 0) {
fprintf(stderr, "Error establishing SSL connection\n");
ERR_print_errors_fp(stderr);
/* whatever ... */
}
/* Could examine ssl here to get connection info */
BIO_puts(sbio, "GET / HTTP/1.0\n\n");
for(;;) {
len = BIO_read(sbio, tmpbuf, 1024);
if(len <= 0) break;
BIO_write(out, tmpbuf, len);
}
BIO_free_all(sbio);
BIO_free(out);
Here is a simple server example. It makes use of a buffering
BIO to allow lines to be read from the SSL BIO using BIO_gets.
It creates a pseudo web page containing the actual request from
a client and also echoes the request to standard output.
BIO *sbio, *bbio, *acpt, *out;
int len;
char tmpbuf[1024];
SSL_CTX *ctx;
SSL *ssl;
ERR_load_crypto_strings();
ERR_load_SSL_strings();
OpenSSL_add_all_algorithms();
/* Might seed PRNG here */
ctx = SSL_CTX_new(SSLv23_server_method());
if (!SSL_CTX_use_certificate_file(ctx,"server.pem",SSL_FILETYPE_PEM)
|| !SSL_CTX_use_PrivateKey_file(ctx,"server.pem",SSL_FILETYPE_PEM)
|| !SSL_CTX_check_private_key(ctx)) {
fprintf(stderr, "Error setting up SSL_CTX\n");
ERR_print_errors_fp(stderr);
return 0;
}
/* Might do other things here like setting verify locations and
* DH and/or RSA temporary key callbacks
*/
/* New SSL BIO setup as server */
sbio=BIO_new_ssl(ctx,0);
BIO_get_ssl(sbio, &ssl);
if(!ssl) {
fprintf(stderr, "Can't locate SSL pointer\n");
/* whatever ... */
}
/* Don't want any retries */
SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY);
/* Create the buffering BIO */
bbio = BIO_new(BIO_f_buffer());
/* Add to chain */
sbio = BIO_push(bbio, sbio);
acpt=BIO_new_accept("4433");
/* By doing this when a new connection is established
* we automatically have sbio inserted into it. The
* BIO chain is now 'swallowed' by the accept BIO and
* will be freed when the accept BIO is freed.
*/
BIO_set_accept_bios(acpt,sbio);
out = BIO_new_fp(stdout, BIO_NOCLOSE);
/* Setup accept BIO */
if(BIO_do_accept(acpt) <= 0) {
fprintf(stderr, "Error setting up accept BIO\n");
ERR_print_errors_fp(stderr);
return 0;
}
/* Now wait for incoming connection */
if(BIO_do_accept(acpt) <= 0) {
fprintf(stderr, "Error in connection\n");
ERR_print_errors_fp(stderr);
return 0;
}
/* We only want one connection so remove and free
* accept BIO
*/
sbio = BIO_pop(acpt);
BIO_free_all(acpt);
if(BIO_do_handshake(sbio) <= 0) {
fprintf(stderr, "Error in SSL handshake\n");
ERR_print_errors_fp(stderr);
return 0;
}
BIO_puts(sbio, "HTTP/1.0 200 OK\r\nContent-type: text/plain\r\n\r\n");
BIO_puts(sbio, "\r\nConnection Established\r\nRequest headers:\r\n");
BIO_puts(sbio, "--------------------------------------------------\r\n");
for(;;) {
len = BIO_gets(sbio, tmpbuf, 1024);
if(len <= 0) break;
BIO_write(sbio, tmpbuf, len);
BIO_write(out, tmpbuf, len);
/* Look for blank line signifying end of headers*/
if((tmpbuf[0] == '\r') || (tmpbuf[0] == '\n')) break;
}
BIO_puts(sbio, "--------------------------------------------------\r\n");
BIO_puts(sbio, "\r\n");
/* Since there is a buffering BIO present we had better flush it */
BIO_flush(sbio);
BIO_free_all(sbio);
=head1 BUGS
In OpenSSL versions before 1.0.0 the BIO_pop() call was handled incorrectly,
the I/O BIO reference count was incorrectly incremented (instead of
decremented) and dissociated with the SSL BIO even if the SSL BIO was not
explicitly being popped (e.g. a pop higher up the chain). Applications which
included workarounds for this bug (e.g. freeing BIOs more than once) should
be modified to handle this fix or they may free up an already freed BIO.
=head1 SEE ALSO
TBA

98
openssl-1.0.2f/doc/crypto/BIO_find_type.pod Normal file
View File

@@ -0,0 +1,98 @@
=pod
=head1 NAME
BIO_find_type, BIO_next, BIO_method_type - BIO chain traversal
=head1 SYNOPSIS
#include <openssl/bio.h>
BIO * BIO_find_type(BIO *b,int bio_type);
BIO * BIO_next(BIO *b);
#define BIO_method_type(b) ((b)->method->type)
#define BIO_TYPE_NONE 0
#define BIO_TYPE_MEM (1|0x0400)
#define BIO_TYPE_FILE (2|0x0400)
#define BIO_TYPE_FD (4|0x0400|0x0100)
#define BIO_TYPE_SOCKET (5|0x0400|0x0100)
#define BIO_TYPE_NULL (6|0x0400)
#define BIO_TYPE_SSL (7|0x0200)
#define BIO_TYPE_MD (8|0x0200)
#define BIO_TYPE_BUFFER (9|0x0200)
#define BIO_TYPE_CIPHER (10|0x0200)
#define BIO_TYPE_BASE64 (11|0x0200)
#define BIO_TYPE_CONNECT (12|0x0400|0x0100)
#define BIO_TYPE_ACCEPT (13|0x0400|0x0100)
#define BIO_TYPE_PROXY_CLIENT (14|0x0200)
#define BIO_TYPE_PROXY_SERVER (15|0x0200)
#define BIO_TYPE_NBIO_TEST (16|0x0200)
#define BIO_TYPE_NULL_FILTER (17|0x0200)
#define BIO_TYPE_BER (18|0x0200)
#define BIO_TYPE_BIO (19|0x0400)
#define BIO_TYPE_DESCRIPTOR 0x0100
#define BIO_TYPE_FILTER 0x0200
#define BIO_TYPE_SOURCE_SINK 0x0400
=head1 DESCRIPTION
The BIO_find_type() searches for a BIO of a given type in a chain, starting
at BIO B<b>. If B<type> is a specific type (such as BIO_TYPE_MEM) then a search
is made for a BIO of that type. If B<type> is a general type (such as
B<BIO_TYPE_SOURCE_SINK>) then the next matching BIO of the given general type is
searched for. BIO_find_type() returns the next matching BIO or NULL if none is
found.
Note: not all the B<BIO_TYPE_*> types above have corresponding BIO implementations.
BIO_next() returns the next BIO in a chain. It can be used to traverse all BIOs
in a chain or used in conjunction with BIO_find_type() to find all BIOs of a
certain type.
BIO_method_type() returns the type of a BIO.
=head1 RETURN VALUES
BIO_find_type() returns a matching BIO or NULL for no match.
BIO_next() returns the next BIO in a chain.
BIO_method_type() returns the type of the BIO B<b>.
=head1 NOTES
BIO_next() was added to OpenSSL 0.9.6 to provide a 'clean' way to traverse a BIO
chain or find multiple matches using BIO_find_type(). Previous versions had to
use:
next = bio->next_bio;
=head1 BUGS
BIO_find_type() in OpenSSL 0.9.5a and earlier could not be safely passed a
NULL pointer for the B<b> argument.
=head1 EXAMPLE
Traverse a chain looking for digest BIOs:
BIO *btmp;
btmp = in_bio; /* in_bio is chain to search through */
do {
btmp = BIO_find_type(btmp, BIO_TYPE_MD);
if(btmp == NULL) break; /* Not found */
/* btmp is a digest BIO, do something with it ...*/
...
btmp = BIO_next(btmp);
} while(btmp);
=head1 SEE ALSO
TBA

65
openssl-1.0.2f/doc/crypto/BIO_new.pod Normal file
View File

@@ -0,0 +1,65 @@
=pod
=head1 NAME
BIO_new, BIO_set, BIO_free, BIO_vfree, BIO_free_all - BIO allocation and freeing functions
=head1 SYNOPSIS
#include <openssl/bio.h>
BIO * BIO_new(BIO_METHOD *type);
int BIO_set(BIO *a,BIO_METHOD *type);
int BIO_free(BIO *a);
void BIO_vfree(BIO *a);
void BIO_free_all(BIO *a);
=head1 DESCRIPTION
The BIO_new() function returns a new BIO using method B<type>.
BIO_set() sets the method of an already existing BIO.
BIO_free() frees up a single BIO, BIO_vfree() also frees up a single BIO
but it does not return a value. Calling BIO_free() may also have some effect
on the underlying I/O structure, for example it may close the file being
referred to under certain circumstances. For more details see the individual
BIO_METHOD descriptions.
BIO_free_all() frees up an entire BIO chain, it does not halt if an error
occurs freeing up an individual BIO in the chain.
=head1 RETURN VALUES
BIO_new() returns a newly created BIO or NULL if the call fails.
BIO_set(), BIO_free() return 1 for success and 0 for failure.
BIO_free_all() and BIO_vfree() do not return values.
=head1 NOTES
Some BIOs (such as memory BIOs) can be used immediately after calling
BIO_new(). Others (such as file BIOs) need some additional initialization,
and frequently a utility function exists to create and initialize such BIOs.
If BIO_free() is called on a BIO chain it will only free one BIO resulting
in a memory leak.
Calling BIO_free_all() a single BIO has the same effect as calling BIO_free()
on it other than the discarded return value.
Normally the B<type> argument is supplied by a function which returns a
pointer to a BIO_METHOD. There is a naming convention for such functions:
a source/sink BIO is normally called BIO_s_*() and a filter BIO
BIO_f_*();
=head1 EXAMPLE
Create a memory BIO:
BIO *mem = BIO_new(BIO_s_mem());
=head1 SEE ALSO
TBA

66
openssl-1.0.2f/doc/crypto/BIO_new_CMS.pod Normal file
View File

@@ -0,0 +1,66 @@
=pod
=head1 NAME
BIO_new_CMS - CMS streaming filter BIO
=head1 SYNOPSIS
#include <openssl/cms.h>
BIO *BIO_new_CMS(BIO *out, CMS_ContentInfo *cms);
=head1 DESCRIPTION
BIO_new_CMS() returns a streaming filter BIO chain based on B<cms>. The output
of the filter is written to B<out>. Any data written to the chain is
automatically translated to a BER format CMS structure of the appropriate type.
=head1 NOTES
The chain returned by this function behaves like a standard filter BIO. It
supports non blocking I/O. Content is processed and streamed on the fly and not
all held in memory at once: so it is possible to encode very large structures.
After all content has been written through the chain BIO_flush() must be called
to finalise the structure.
The B<CMS_STREAM> flag must be included in the corresponding B<flags>
parameter of the B<cms> creation function.
If an application wishes to write additional data to B<out> BIOs should be
removed from the chain using BIO_pop() and freed with BIO_free() until B<out>
is reached. If no additional data needs to be written BIO_free_all() can be
called to free up the whole chain.
Any content written through the filter is used verbatim: no canonical
translation is performed.
It is possible to chain multiple BIOs to, for example, create a triple wrapped
signed, enveloped, signed structure. In this case it is the applications
responsibility to set the inner content type of any outer CMS_ContentInfo
structures.
Large numbers of small writes through the chain should be avoided as this will
produce an output consisting of lots of OCTET STRING structures. Prepending
a BIO_f_buffer() buffering BIO will prevent this.
=head1 BUGS
There is currently no corresponding inverse BIO: i.e. one which can decode
a CMS structure on the fly.
=head1 RETURN VALUES
BIO_new_CMS() returns a BIO chain when successful or NULL if an error
occurred. The error can be obtained from ERR_get_error(3).
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>,
L<CMS_encrypt(3)|CMS_encrypt(3)>
=head1 HISTORY
BIO_new_CMS() was added to OpenSSL 1.0.0
=cut

69
openssl-1.0.2f/doc/crypto/BIO_push.pod Normal file
View File

@@ -0,0 +1,69 @@
=pod
=head1 NAME
BIO_push, BIO_pop - add and remove BIOs from a chain.
=head1 SYNOPSIS
#include <openssl/bio.h>
BIO * BIO_push(BIO *b,BIO *append);
BIO * BIO_pop(BIO *b);
=head1 DESCRIPTION
The BIO_push() function appends the BIO B<append> to B<b>, it returns
B<b>.
BIO_pop() removes the BIO B<b> from a chain and returns the next BIO
in the chain, or NULL if there is no next BIO. The removed BIO then
becomes a single BIO with no association with the original chain,
it can thus be freed or attached to a different chain.
=head1 NOTES
The names of these functions are perhaps a little misleading. BIO_push()
joins two BIO chains whereas BIO_pop() deletes a single BIO from a chain,
the deleted BIO does not need to be at the end of a chain.
The process of calling BIO_push() and BIO_pop() on a BIO may have additional
consequences (a control call is made to the affected BIOs) any effects will
be noted in the descriptions of individual BIOs.
=head1 EXAMPLES
For these examples suppose B<md1> and B<md2> are digest BIOs, B<b64> is
a base64 BIO and B<f> is a file BIO.
If the call:
BIO_push(b64, f);
is made then the new chain will be B<b64-f>. After making the calls
BIO_push(md2, b64);
BIO_push(md1, md2);
the new chain is B<md1-md2-b64-f>. Data written to B<md1> will be digested
by B<md1> and B<md2>, B<base64> encoded and written to B<f>.
It should be noted that reading causes data to pass in the reverse
direction, that is data is read from B<f>, base64 B<decoded> and digested
by B<md1> and B<md2>. If the call:
BIO_pop(md2);
The call will return B<b64> and the new chain will be B<md1-b64-f> data can
be written to B<md1> as before.
=head1 RETURN VALUES
BIO_push() returns the end of the chain, B<b>.
BIO_pop() returns the next BIO in the chain, or NULL if there is no next
BIO.
=head1 SEE ALSO
TBA

66
openssl-1.0.2f/doc/crypto/BIO_read.pod Normal file
View File

@@ -0,0 +1,66 @@
=pod
=head1 NAME
BIO_read, BIO_write, BIO_gets, BIO_puts - BIO I/O functions
=head1 SYNOPSIS
#include <openssl/bio.h>
int BIO_read(BIO *b, void *buf, int len);
int BIO_gets(BIO *b, char *buf, int size);
int BIO_write(BIO *b, const void *buf, int len);
int BIO_puts(BIO *b, const char *buf);
=head1 DESCRIPTION
BIO_read() attempts to read B<len> bytes from BIO B<b> and places
the data in B<buf>.
BIO_gets() performs the BIOs "gets" operation and places the data
in B<buf>. Usually this operation will attempt to read a line of data
from the BIO of maximum length B<len>. There are exceptions to this
however, for example BIO_gets() on a digest BIO will calculate and
return the digest and other BIOs may not support BIO_gets() at all.
BIO_write() attempts to write B<len> bytes from B<buf> to BIO B<b>.
BIO_puts() attempts to write a null terminated string B<buf> to BIO B<b>.
=head1 RETURN VALUES
All these functions return either the amount of data successfully read or
written (if the return value is positive) or that no data was successfully
read or written if the result is 0 or -1. If the return value is -2 then
the operation is not implemented in the specific BIO type.
=head1 NOTES
A 0 or -1 return is not necessarily an indication of an error. In
particular when the source/sink is non-blocking or of a certain type
it may merely be an indication that no data is currently available and that
the application should retry the operation later.
One technique sometimes used with blocking sockets is to use a system call
(such as select(), poll() or equivalent) to determine when data is available
and then call read() to read the data. The equivalent with BIOs (that is call
select() on the underlying I/O structure and then call BIO_read() to
read the data) should B<not> be used because a single call to BIO_read()
can cause several reads (and writes in the case of SSL BIOs) on the underlying
I/O structure and may block as a result. Instead select() (or equivalent)
should be combined with non blocking I/O so successive reads will request
a retry instead of blocking.
See L<BIO_should_retry(3)|BIO_should_retry(3)> for details of how to
determine the cause of a retry and other I/O issues.
If the BIO_gets() function is not supported by a BIO then it possible to
work around this by adding a buffering BIO L<BIO_f_buffer(3)|BIO_f_buffer(3)>
to the chain.
=head1 SEE ALSO
L<BIO_should_retry(3)|BIO_should_retry(3)>
TBA

195
openssl-1.0.2f/doc/crypto/BIO_s_accept.pod Normal file
View File

@@ -0,0 +1,195 @@
=pod
=head1 NAME
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
=head1 SYNOPSIS
#include <openssl/bio.h>
BIO_METHOD *BIO_s_accept(void);
long BIO_set_accept_port(BIO *b, char *name);
char *BIO_get_accept_port(BIO *b);
BIO *BIO_new_accept(char *host_port);
long BIO_set_nbio_accept(BIO *b, int n);
long BIO_set_accept_bios(BIO *b, char *bio);
long BIO_set_bind_mode(BIO *b, long mode);
long BIO_get_bind_mode(BIO *b, long dummy);
#define BIO_BIND_NORMAL 0
#define BIO_BIND_REUSEADDR_IF_UNUSED 1
#define BIO_BIND_REUSEADDR 2
int BIO_do_accept(BIO *b);
=head1 DESCRIPTION
BIO_s_accept() returns the accept BIO method. This is a wrapper
round the platform's TCP/IP socket accept routines.
Using accept BIOs, TCP/IP connections can be accepted and data
transferred using only BIO routines. In this way any platform
specific operations are hidden by the BIO abstraction.
Read and write operations on an accept BIO will perform I/O
on the underlying connection. If no connection is established
and the port (see below) is set up properly then the BIO
waits for an incoming connection.
Accept BIOs support BIO_puts() but not BIO_gets().
If the close flag is set on an accept BIO then any active
connection on that chain is shutdown and the socket closed when
the BIO is freed.
Calling BIO_reset() on a accept BIO will close any active
connection and reset the BIO into a state where it awaits another
incoming connection.
BIO_get_fd() and BIO_set_fd() can be called to retrieve or set
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.
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.
BIO_new_accept() combines BIO_new() and BIO_set_accept_port() into
a single call: that is it creates a new accept BIO with port
B<host_port>.
BIO_set_nbio_accept() sets the accept socket to blocking mode
(the default) if B<n> is 0 or non blocking mode if B<n> is 1.
BIO_set_accept_bios() can be used to set a chain of BIOs which
will be duplicated and prepended to the chain when an incoming
connection is received. This is useful if, for example, a
buffering or SSL BIO is required for each connection. The
chain of BIOs must not be freed after this call, they will
be automatically freed when the accept BIO is freed.
BIO_set_bind_mode() and BIO_get_bind_mode() set and retrieve
the current bind mode. If BIO_BIND_NORMAL (the default) is set
then another socket cannot be bound to the same port. If
BIO_BIND_REUSEADDR is set then other sockets can bind to the
same port. If BIO_BIND_REUSEADDR_IF_UNUSED is set then and
attempt is first made to use BIO_BIN_NORMAL, if this fails
and the port is not in use then a second attempt is made
using BIO_BIND_REUSEADDR.
BIO_do_accept() serves two functions. When it is first
called, after the accept BIO has been setup, it will attempt
to create the accept socket and bind an address to it. Second
and subsequent calls to BIO_do_accept() will await an incoming
connection, or request a retry in non blocking mode.
=head1 NOTES
When an accept BIO is at the end of a chain it will await an
incoming connection before processing I/O calls. When an accept
BIO is not at then end of a chain it passes I/O calls to the next
BIO in the chain.
When a connection is established a new socket BIO is created for
the connection and appended to the chain. That is the chain is now
accept->socket. This effectively means that attempting I/O on
an initial accept socket will await an incoming connection then
perform I/O on it.
If any additional BIOs have been set using BIO_set_accept_bios()
then they are placed between the socket and the accept BIO,
that is the chain will be accept->otherbios->socket.
If a server wishes to process multiple connections (as is normally
the case) then the accept BIO must be made available for further
incoming connections. This can be done by waiting for a connection and
then calling:
connection = BIO_pop(accept);
After this call B<connection> will contain a BIO for the recently
established connection and B<accept> will now be a single BIO
again which can be used to await further incoming connections.
If no further connections will be accepted the B<accept> can
be freed using BIO_free().
If only a single connection will be processed it is possible to
perform I/O using the accept BIO itself. This is often undesirable
however because the accept BIO will still accept additional incoming
connections. This can be resolved by using BIO_pop() (see above)
and freeing up the accept BIO after the initial connection.
If the underlying accept socket is non-blocking and BIO_do_accept() is
called to await an incoming connection it is possible for
BIO_should_io_special() with the reason BIO_RR_ACCEPT. If this happens
then it is an indication that an accept attempt would block: the application
should take appropriate action to wait until the underlying socket has
accepted a connection and retry the call.
BIO_set_accept_port(), BIO_get_accept_port(), BIO_set_nbio_accept(),
BIO_set_accept_bios(), BIO_set_bind_mode(), BIO_get_bind_mode() and
BIO_do_accept() are macros.
=head1 RETURN VALUES
TBA
=head1 EXAMPLE
This example accepts two connections on port 4444, sends messages
down each and finally closes both down.
BIO *abio, *cbio, *cbio2;
ERR_load_crypto_strings();
abio = BIO_new_accept("4444");
/* First call to BIO_accept() sets up accept BIO */
if(BIO_do_accept(abio) <= 0) {
fprintf(stderr, "Error setting up accept\n");
ERR_print_errors_fp(stderr);
exit(0);
}
/* Wait for incoming connection */
if(BIO_do_accept(abio) <= 0) {
fprintf(stderr, "Error accepting connection\n");
ERR_print_errors_fp(stderr);
exit(0);
}
fprintf(stderr, "Connection 1 established\n");
/* Retrieve BIO for connection */
cbio = BIO_pop(abio);
BIO_puts(cbio, "Connection 1: Sending out Data on initial connection\n");
fprintf(stderr, "Sent out data on connection 1\n");
/* Wait for another connection */
if(BIO_do_accept(abio) <= 0) {
fprintf(stderr, "Error accepting connection\n");
ERR_print_errors_fp(stderr);
exit(0);
}
fprintf(stderr, "Connection 2 established\n");
/* Close accept BIO to refuse further connections */
cbio2 = BIO_pop(abio);
BIO_free(abio);
BIO_puts(cbio2, "Connection 2: Sending out Data on second\n");
fprintf(stderr, "Sent out data on connection 2\n");
BIO_puts(cbio, "Connection 1: Second connection established\n");
/* Close the two established connections */
BIO_free(cbio);
BIO_free(cbio2);
=head1 SEE ALSO
TBA

182
openssl-1.0.2f/doc/crypto/BIO_s_bio.pod Normal file
View File

@@ -0,0 +1,182 @@
=pod
=head1 NAME
BIO_s_bio, BIO_make_bio_pair, BIO_destroy_bio_pair, BIO_shutdown_wr,
BIO_set_write_buf_size, BIO_get_write_buf_size, BIO_new_bio_pair,
BIO_get_write_guarantee, BIO_ctrl_get_write_guarantee, BIO_get_read_request,
BIO_ctrl_get_read_request, BIO_ctrl_reset_read_request - BIO pair BIO
=head1 SYNOPSIS
#include <openssl/bio.h>
BIO_METHOD *BIO_s_bio(void);
#define BIO_make_bio_pair(b1,b2) (int)BIO_ctrl(b1,BIO_C_MAKE_BIO_PAIR,0,b2)
#define BIO_destroy_bio_pair(b) (int)BIO_ctrl(b,BIO_C_DESTROY_BIO_PAIR,0,NULL)
#define BIO_shutdown_wr(b) (int)BIO_ctrl(b, BIO_C_SHUTDOWN_WR, 0, NULL)
#define BIO_set_write_buf_size(b,size) (int)BIO_ctrl(b,BIO_C_SET_WRITE_BUF_SIZE,size,NULL)
#define BIO_get_write_buf_size(b,size) (size_t)BIO_ctrl(b,BIO_C_GET_WRITE_BUF_SIZE,size,NULL)
int BIO_new_bio_pair(BIO **bio1, size_t writebuf1, BIO **bio2, size_t writebuf2);
#define BIO_get_write_guarantee(b) (int)BIO_ctrl(b,BIO_C_GET_WRITE_GUARANTEE,0,NULL)
size_t BIO_ctrl_get_write_guarantee(BIO *b);
#define BIO_get_read_request(b) (int)BIO_ctrl(b,BIO_C_GET_READ_REQUEST,0,NULL)
size_t BIO_ctrl_get_read_request(BIO *b);
int BIO_ctrl_reset_read_request(BIO *b);
=head1 DESCRIPTION
BIO_s_bio() returns the method for a BIO pair. A BIO pair is a pair of source/sink
BIOs where data written to either half of the pair is buffered and can be read from
the other half. Both halves must usually by handled by the same application thread
since no locking is done on the internal data structures.
Since BIO chains typically end in a source/sink BIO it is possible to make this
one half of a BIO pair and have all the data processed by the chain under application
control.
One typical use of BIO pairs is to place TLS/SSL I/O under application control, this
can be used when the application wishes to use a non standard transport for
TLS/SSL or the normal socket routines are inappropriate.
Calls to BIO_read() will read data from the buffer or request a retry if no
data is available.
Calls to BIO_write() will place data in the buffer or request a retry if the
buffer is full.
The standard calls BIO_ctrl_pending() and BIO_ctrl_wpending() can be used to
determine the amount of pending data in the read or write buffer.
BIO_reset() clears any data in the write buffer.
BIO_make_bio_pair() joins two separate BIOs into a connected pair.
BIO_destroy_pair() destroys the association between two connected BIOs. Freeing
up any half of the pair will automatically destroy the association.
BIO_shutdown_wr() is used to close down a BIO B<b>. After this call no further
writes on BIO B<b> are allowed (they will return an error). Reads on the other
half of the pair will return any pending data or EOF when all pending data has
been read.
BIO_set_write_buf_size() sets the write buffer size of BIO B<b> to B<size>.
If the size is not initialized a default value is used. This is currently
17K, sufficient for a maximum size TLS record.
BIO_get_write_buf_size() returns the size of the write buffer.
BIO_new_bio_pair() combines the calls to BIO_new(), BIO_make_bio_pair() and
BIO_set_write_buf_size() to create a connected pair of BIOs B<bio1>, B<bio2>
with write buffer sizes B<writebuf1> and B<writebuf2>. If either size is
zero then the default size is used. BIO_new_bio_pair() does not check whether
B<bio1> or B<bio2> do point to some other BIO, the values are overwritten,
BIO_free() is not called.
BIO_get_write_guarantee() and BIO_ctrl_get_write_guarantee() return the maximum
length of data that can be currently written to the BIO. Writes larger than this
value will return a value from BIO_write() less than the amount requested or if the
buffer is full request a retry. BIO_ctrl_get_write_guarantee() is a function
whereas BIO_get_write_guarantee() is a macro.
BIO_get_read_request() and BIO_ctrl_get_read_request() return the
amount of data requested, or the buffer size if it is less, if the
last read attempt at the other half of the BIO pair failed due to an
empty buffer. This can be used to determine how much data should be
written to the BIO so the next read will succeed: this is most useful
in TLS/SSL applications where the amount of data read is usually
meaningful rather than just a buffer size. After a successful read
this call will return zero. It also will return zero once new data
has been written satisfying the read request or part of it.
Note that BIO_get_read_request() never returns an amount larger
than that returned by BIO_get_write_guarantee().
BIO_ctrl_reset_read_request() can also be used to reset the value returned by
BIO_get_read_request() to zero.
=head1 NOTES
Both halves of a BIO pair should be freed. That is even if one half is implicit
freed due to a BIO_free_all() or SSL_free() call the other half needs to be freed.
When used in bidirectional applications (such as TLS/SSL) care should be taken to
flush any data in the write buffer. This can be done by calling BIO_pending()
on the other half of the pair and, if any data is pending, reading it and sending
it to the underlying transport. This must be done before any normal processing
(such as calling select() ) due to a request and BIO_should_read() being true.
To see why this is important consider a case where a request is sent using
BIO_write() and a response read with BIO_read(), this can occur during an
TLS/SSL handshake for example. BIO_write() will succeed and place data in the write
buffer. BIO_read() will initially fail and BIO_should_read() will be true. If
the application then waits for data to be available on the underlying transport
before flushing the write buffer it will never succeed because the request was
never sent!
=head1 RETURN VALUES
BIO_new_bio_pair() returns 1 on success, with the new BIOs available in
B<bio1> and B<bio2>, or 0 on failure, with NULL pointers stored into the
locations for B<bio1> and B<bio2>. Check the error stack for more information.
[XXXXX: More return values need to be added here]
=head1 EXAMPLE
The BIO pair can be used to have full control over the network access of an
application. The application can call select() on the socket as required
without having to go through the SSL-interface.
BIO *internal_bio, *network_bio;
...
BIO_new_bio_pair(internal_bio, 0, network_bio, 0);
SSL_set_bio(ssl, internal_bio, internal_bio);
SSL_operations();
...
application | TLS-engine
| |
+----------> SSL_operations()
| /\ ||
| || \/
| BIO-pair (internal_bio)
+----------< BIO-pair (network_bio)
| |
socket |
...
SSL_free(ssl); /* implicitly frees internal_bio */
BIO_free(network_bio);
...
As the BIO pair will only buffer the data and never directly access the
connection, it behaves non-blocking and will return as soon as the write
buffer is full or the read buffer is drained. Then the application has to
flush the write buffer and/or fill the read buffer.
Use the BIO_ctrl_pending(), to find out whether data is buffered in the BIO
and must be transfered to the network. Use BIO_ctrl_get_read_request() to
find out, how many bytes must be written into the buffer before the
SSL_operation() can successfully be continued.
=head1 WARNING
As the data is buffered, SSL_operation() may return with a ERROR_SSL_WANT_READ
condition, but there is still data in the write buffer. An application must
not rely on the error value of SSL_operation() but must assure that the
write buffer is always flushed first. Otherwise a deadlock may occur as
the peer might be waiting for the data before being able to continue.
=head1 SEE ALSO
L<SSL_set_bio(3)|SSL_set_bio(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>,
L<BIO_should_retry(3)|BIO_should_retry(3)>, L<BIO_read(3)|BIO_read(3)>
=cut

192
openssl-1.0.2f/doc/crypto/BIO_s_connect.pod Normal file
View File

@@ -0,0 +1,192 @@
=pod
=head1 NAME
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
=head1 SYNOPSIS
#include <openssl/bio.h>
BIO_METHOD * BIO_s_connect(void);
BIO *BIO_new_connect(char *name);
long BIO_set_conn_hostname(BIO *b, char *name);
long BIO_set_conn_port(BIO *b, char *port);
long BIO_set_conn_ip(BIO *b, char *ip);
long BIO_set_conn_int_port(BIO *b, char *port);
char *BIO_get_conn_hostname(BIO *b);
char *BIO_get_conn_port(BIO *b);
char *BIO_get_conn_ip(BIO *b);
long BIO_get_conn_int_port(BIO *b);
long BIO_set_nbio(BIO *b, long n);
int BIO_do_connect(BIO *b);
=head1 DESCRIPTION
BIO_s_connect() returns the connect BIO method. This is a wrapper
round the platform's TCP/IP socket connection routines.
Using connect BIOs, TCP/IP connections can be made and data
transferred using only BIO routines. In this way any platform
specific operations are hidden by the BIO abstraction.
Read and write operations on a connect BIO will perform I/O
on the underlying connection. If no connection is established
and the port and hostname (see below) is set up properly then
a connection is established first.
Connect BIOs support BIO_puts() but not BIO_gets().
If the close flag is set on a connect BIO then any active
connection is shutdown and the socket closed when the BIO
is freed.
Calling BIO_reset() on a connect BIO will close any active
connection and reset the BIO into a state where it can connect
to the same host again.
BIO_get_fd() places the underlying socket in B<c> if it is not NULL,
it also returns the socket . If B<c> is not NULL it should be of
type (int *).
BIO_set_conn_hostname() uses the string B<name> to set the hostname.
The hostname can be an IP address. The hostname can also include the
port in the form hostname:port . It is also acceptable to use the
form "hostname/any/other/path" or "hostname:port/any/other/path".
BIO_set_conn_port() sets the port to B<port>. B<port> can be the
numerical form or a string such as "http". A string will be looked
up first using getservbyname() on the host platform but if that
fails a standard table of port names will be used. Currently the
list is http, telnet, socks, https, ssl, ftp, gopher and wais.
BIO_set_conn_ip() sets the IP address to B<ip> using binary form,
that is four bytes specifying the IP address in big-endian form.
BIO_set_conn_int_port() sets the port using B<port>. B<port> should
be of type (int *).
BIO_get_conn_hostname() returns the hostname of the connect BIO or
NULL if the BIO is initialized but no hostname is set.
This return value is an internal pointer which should not be modified.
BIO_get_conn_port() returns the port as a string.
BIO_get_conn_ip() returns the IP address in binary form.
BIO_get_conn_int_port() returns the port as an int.
BIO_set_nbio() sets the non blocking I/O flag to B<n>. If B<n> is
zero then blocking I/O is set. If B<n> is 1 then non blocking I/O
is set. Blocking I/O is the default. The call to BIO_set_nbio()
should be made before the connection is established because
non blocking I/O is set during the connect process.
BIO_new_connect() combines BIO_new() and BIO_set_conn_hostname() into
a single call: that is it creates a new connect BIO with B<name>.
BIO_do_connect() attempts to connect the supplied BIO. It returns 1
if the connection was established successfully. A zero or negative
value is returned if the connection could not be established, the
call BIO_should_retry() should be used for non blocking connect BIOs
to determine if the call should be retried.
=head1 NOTES
If blocking I/O is set then a non positive return value from any
I/O call is caused by an error condition, although a zero return
will normally mean that the connection was closed.
If the port name is supplied as part of the host name then this will
override any value set with BIO_set_conn_port(). This may be undesirable
if the application does not wish to allow connection to arbitrary
ports. This can be avoided by checking for the presence of the ':'
character in the passed hostname and either indicating an error or
truncating the string at that point.
The values returned by BIO_get_conn_hostname(), BIO_get_conn_port(),
BIO_get_conn_ip() and BIO_get_conn_int_port() are updated when a
connection attempt is made. Before any connection attempt the values
returned are those set by the application itself.
Applications do not have to call BIO_do_connect() but may wish to do
so to separate the connection process from other I/O processing.
If non blocking I/O is set then retries will be requested as appropriate.
It addition to BIO_should_read() and BIO_should_write() it is also
possible for BIO_should_io_special() to be true during the initial
connection process with the reason BIO_RR_CONNECT. If this is returned
then this is an indication that a connection attempt would block,
the application should then take appropriate action to wait until
the underlying socket has connected and retry the call.
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() and
BIO_do_connect() are macros.
=head1 RETURN VALUES
BIO_s_connect() returns the connect BIO method.
BIO_get_fd() returns the socket or -1 if the BIO has not
been initialized.
BIO_set_conn_hostname(), BIO_set_conn_port(), BIO_set_conn_ip() and
BIO_set_conn_int_port() always return 1.
BIO_get_conn_hostname() returns the connected hostname or NULL is
none was set.
BIO_get_conn_port() returns a string representing the connected
port or NULL if not set.
BIO_get_conn_ip() returns a pointer to the connected IP address in
binary form or all zeros if not set.
BIO_get_conn_int_port() returns the connected port or 0 if none was
set.
BIO_set_nbio() always returns 1.
BIO_do_connect() returns 1 if the connection was successfully
established and 0 or -1 if the connection failed.
=head1 EXAMPLE
This is example connects to a webserver on the local host and attempts
to retrieve a page and copy the result to standard output.
BIO *cbio, *out;
int len;
char tmpbuf[1024];
ERR_load_crypto_strings();
cbio = BIO_new_connect("localhost:http");
out = BIO_new_fp(stdout, BIO_NOCLOSE);
if(BIO_do_connect(cbio) <= 0) {
fprintf(stderr, "Error connecting to server\n");
ERR_print_errors_fp(stderr);
/* whatever ... */
}
BIO_puts(cbio, "GET / HTTP/1.0\n\n");
for(;;) {
len = BIO_read(cbio, tmpbuf, 1024);
if(len <= 0) break;
BIO_write(out, tmpbuf, len);
}
BIO_free(cbio);
BIO_free(out);
=head1 SEE ALSO
TBA

89
openssl-1.0.2f/doc/crypto/BIO_s_fd.pod Normal file
View File

@@ -0,0 +1,89 @@
=pod
=head1 NAME
BIO_s_fd, BIO_set_fd, BIO_get_fd, BIO_new_fd - file descriptor BIO
=head1 SYNOPSIS
#include <openssl/bio.h>
BIO_METHOD * BIO_s_fd(void);
#define BIO_set_fd(b,fd,c) BIO_int_ctrl(b,BIO_C_SET_FD,c,fd)
#define BIO_get_fd(b,c) BIO_ctrl(b,BIO_C_GET_FD,0,(char *)c)
BIO *BIO_new_fd(int fd, int close_flag);
=head1 DESCRIPTION
BIO_s_fd() returns the file descriptor BIO method. This is a wrapper
round the platforms file descriptor routines such as read() and write().
BIO_read() and BIO_write() read or write the underlying descriptor.
BIO_puts() is supported but BIO_gets() is not.
If the close flag is set then then close() is called on the underlying
file descriptor when the BIO is freed.
BIO_reset() attempts to change the file pointer to the start of file
using lseek(fd, 0, 0).
BIO_seek() sets the file pointer to position B<ofs> from start of file
using lseek(fd, ofs, 0).
BIO_tell() returns the current file position by calling lseek(fd, 0, 1).
BIO_set_fd() sets the file descriptor of BIO B<b> to B<fd> and the close
flag to B<c>.
BIO_get_fd() places the file descriptor in B<c> if it is not NULL, it also
returns the file descriptor. If B<c> is not NULL it should be of type
(int *).
BIO_new_fd() returns a file descriptor BIO using B<fd> and B<close_flag>.
=head1 NOTES
The behaviour of BIO_read() and BIO_write() depends on the behavior of the
platforms read() and write() calls on the descriptor. If the underlying
file descriptor is in a non blocking mode then the BIO will behave in the
manner described in the L<BIO_read(3)|BIO_read(3)> and L<BIO_should_retry(3)|BIO_should_retry(3)>
manual pages.
File descriptor BIOs should not be used for socket I/O. Use socket BIOs
instead.
=head1 RETURN VALUES
BIO_s_fd() returns the file descriptor BIO method.
BIO_reset() returns zero for success and -1 if an error occurred.
BIO_seek() and BIO_tell() return the current file position or -1
is an error occurred. These values reflect the underlying lseek()
behaviour.
BIO_set_fd() always returns 1.
BIO_get_fd() returns the file descriptor or -1 if the BIO has not
been initialized.
BIO_new_fd() returns the newly allocated BIO or NULL is an error
occurred.
=head1 EXAMPLE
This is a file descriptor BIO version of "Hello World":
BIO *out;
out = BIO_new_fd(fileno(stdout), BIO_NOCLOSE);
BIO_printf(out, "Hello World\n");
BIO_free(out);
=head1 SEE ALSO
L<BIO_seek(3)|BIO_seek(3)>, L<BIO_tell(3)|BIO_tell(3)>,
L<BIO_reset(3)|BIO_reset(3)>, L<BIO_read(3)|BIO_read(3)>,
L<BIO_write(3)|BIO_write(3)>, L<BIO_puts(3)|BIO_puts(3)>,
L<BIO_gets(3)|BIO_gets(3)>, L<BIO_printf(3)|BIO_printf(3)>,
L<BIO_set_close(3)|BIO_set_close(3)>, L<BIO_get_close(3)|BIO_get_close(3)>

148
openssl-1.0.2f/doc/crypto/BIO_s_file.pod Normal file
View File

@@ -0,0 +1,148 @@
=pod
=head1 NAME
BIO_s_file, BIO_new_file, BIO_new_fp, BIO_set_fp, BIO_get_fp,
BIO_read_filename, BIO_write_filename, BIO_append_filename,
BIO_rw_filename - FILE bio
=head1 SYNOPSIS
#include <openssl/bio.h>
BIO_METHOD * BIO_s_file(void);
BIO *BIO_new_file(const char *filename, const char *mode);
BIO *BIO_new_fp(FILE *stream, int flags);
BIO_set_fp(BIO *b,FILE *fp, int flags);
BIO_get_fp(BIO *b,FILE **fpp);
int BIO_read_filename(BIO *b, char *name)
int BIO_write_filename(BIO *b, char *name)
int BIO_append_filename(BIO *b, char *name)
int BIO_rw_filename(BIO *b, char *name)
=head1 DESCRIPTION
BIO_s_file() returns the BIO file method. As its name implies it
is a wrapper round the stdio FILE structure and it is a
source/sink BIO.
Calls to BIO_read() and BIO_write() read and write data to the
underlying stream. BIO_gets() and BIO_puts() are supported on file BIOs.
BIO_flush() on a file BIO calls the fflush() function on the wrapped
stream.
BIO_reset() attempts to change the file pointer to the start of file
using fseek(stream, 0, 0).
BIO_seek() sets the file pointer to position B<ofs> from start of file
using fseek(stream, ofs, 0).
BIO_eof() calls feof().
Setting the BIO_CLOSE flag calls fclose() on the stream when the BIO
is freed.
BIO_new_file() creates a new file BIO with mode B<mode> the meaning
of B<mode> is the same as the stdio function fopen(). The BIO_CLOSE
flag is set on the returned BIO.
BIO_new_fp() creates a file BIO wrapping B<stream>. Flags can be:
BIO_CLOSE, BIO_NOCLOSE (the close flag) BIO_FP_TEXT (sets the underlying
stream to text mode, default is binary: this only has any effect under
Win32).
BIO_set_fp() set the fp of a file BIO to B<fp>. B<flags> has the same
meaning as in BIO_new_fp(), it is a macro.
BIO_get_fp() retrieves the fp of a file BIO, it is a macro.
BIO_seek() is a macro that sets the position pointer to B<offset> bytes
from the start of file.
BIO_tell() returns the value of the position pointer.
BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and
BIO_rw_filename() set the file BIO B<b> to use file B<name> for
reading, writing, append or read write respectively.
=head1 NOTES
When wrapping stdout, stdin or stderr the underlying stream should not
normally be closed so the BIO_NOCLOSE flag should be set.
Because the file BIO calls the underlying stdio functions any quirks
in stdio behaviour will be mirrored by the corresponding BIO.
On Windows BIO_new_files reserves for the filename argument to be
UTF-8 encoded. In other words if you have to make it work in multi-
lingual environment, encode file names in UTF-8.
=head1 EXAMPLES
File BIO "hello world":
BIO *bio_out;
bio_out = BIO_new_fp(stdout, BIO_NOCLOSE);
BIO_printf(bio_out, "Hello World\n");
Alternative technique:
BIO *bio_out;
bio_out = BIO_new(BIO_s_file());
if(bio_out == NULL) /* Error ... */
if(!BIO_set_fp(bio_out, stdout, BIO_NOCLOSE)) /* Error ... */
BIO_printf(bio_out, "Hello World\n");
Write to a file:
BIO *out;
out = BIO_new_file("filename.txt", "w");
if(!out) /* Error occurred */
BIO_printf(out, "Hello World\n");
BIO_free(out);
Alternative technique:
BIO *out;
out = BIO_new(BIO_s_file());
if(out == NULL) /* Error ... */
if(!BIO_write_filename(out, "filename.txt")) /* Error ... */
BIO_printf(out, "Hello World\n");
BIO_free(out);
=head1 RETURN VALUES
BIO_s_file() returns the file BIO method.
BIO_new_file() and BIO_new_fp() return a file BIO or NULL if an error
occurred.
BIO_set_fp() and BIO_get_fp() return 1 for success or 0 for failure
(although the current implementation never return 0).
BIO_seek() returns the same value as the underlying fseek() function:
0 for success or -1 for failure.
BIO_tell() returns the current file position.
BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and
BIO_rw_filename() return 1 for success or 0 for failure.
=head1 BUGS
BIO_reset() and BIO_seek() are implemented using fseek() on the underlying
stream. The return value for fseek() is 0 for success or -1 if an error
occurred this differs from other types of BIO which will typically return
1 for success and a non positive value if an error occurred.
=head1 SEE ALSO
L<BIO_seek(3)|BIO_seek(3)>, L<BIO_tell(3)|BIO_tell(3)>,
L<BIO_reset(3)|BIO_reset(3)>, L<BIO_flush(3)|BIO_flush(3)>,
L<BIO_read(3)|BIO_read(3)>,
L<BIO_write(3)|BIO_write(3)>, L<BIO_puts(3)|BIO_puts(3)>,
L<BIO_gets(3)|BIO_gets(3)>, L<BIO_printf(3)|BIO_printf(3)>,
L<BIO_set_close(3)|BIO_set_close(3)>, L<BIO_get_close(3)|BIO_get_close(3)>

115
openssl-1.0.2f/doc/crypto/BIO_s_mem.pod Normal file
View File

@@ -0,0 +1,115 @@
=pod
=head1 NAME
BIO_s_mem, BIO_set_mem_eof_return, BIO_get_mem_data, BIO_set_mem_buf,
BIO_get_mem_ptr, BIO_new_mem_buf - memory BIO
=head1 SYNOPSIS
#include <openssl/bio.h>
BIO_METHOD * BIO_s_mem(void);
BIO_set_mem_eof_return(BIO *b,int v)
long BIO_get_mem_data(BIO *b, char **pp)
BIO_set_mem_buf(BIO *b,BUF_MEM *bm,int c)
BIO_get_mem_ptr(BIO *b,BUF_MEM **pp)
BIO *BIO_new_mem_buf(void *buf, int len);
=head1 DESCRIPTION
BIO_s_mem() return the memory BIO method function.
A memory BIO is a source/sink BIO which uses memory for its I/O. Data
written to a memory BIO is stored in a BUF_MEM structure which is extended
as appropriate to accommodate the stored data.
Any data written to a memory BIO can be recalled by reading from it.
Unless the memory BIO is read only any data read from it is deleted from
the BIO.
Memory BIOs support BIO_gets() and BIO_puts().
If the BIO_CLOSE flag is set when a memory BIO is freed then the underlying
BUF_MEM structure is also freed.
Calling BIO_reset() on a read write memory BIO clears any data in it. On a
read only BIO it restores the BIO to its original state and the read only
data can be read again.
BIO_eof() is true if no data is in the BIO.
BIO_ctrl_pending() returns the number of bytes currently stored.
BIO_set_mem_eof_return() sets the behaviour of memory BIO B<b> when it is
empty. If the B<v> is zero then an empty memory BIO will return EOF (that is
it will return zero and BIO_should_retry(b) will be false. If B<v> is non
zero then it will return B<v> when it is empty and it will set the read retry
flag (that is BIO_read_retry(b) is true). To avoid ambiguity with a normal
positive return value B<v> should be set to a negative value, typically -1.
BIO_get_mem_data() sets B<pp> to a pointer to the start of the memory BIOs data
and returns the total amount of data available. It is implemented as a macro.
BIO_set_mem_buf() sets the internal BUF_MEM structure to B<bm> and sets the
close flag to B<c>, that is B<c> should be either BIO_CLOSE or BIO_NOCLOSE.
It is a macro.
BIO_get_mem_ptr() places the underlying BUF_MEM structure in B<pp>. It is
a macro.
BIO_new_mem_buf() creates a memory BIO using B<len> bytes of data at B<buf>,
if B<len> is -1 then the B<buf> is assumed to be null terminated and its
length is determined by B<strlen>. The BIO is set to a read only state and
as a result cannot be written to. This is useful when some data needs to be
made available from a static area of memory in the form of a BIO. The
supplied data is read directly from the supplied buffer: it is B<not> copied
first, so the supplied area of memory must be unchanged until the BIO is freed.
=head1 NOTES
Writes to memory BIOs will always succeed if memory is available: that is
their size can grow indefinitely.
Every read from a read write memory BIO will remove the data just read with
an internal copy operation, if a BIO contains a lot of data and it is
read in small chunks the operation can be very slow. The use of a read only
memory BIO avoids this problem. If the BIO must be read write then adding
a buffering BIO to the chain will speed up the process.
=head1 BUGS
There should be an option to set the maximum size of a memory BIO.
There should be a way to "rewind" a read write BIO without destroying
its contents.
The copying operation should not occur after every small read of a large BIO
to improve efficiency.
=head1 EXAMPLE
Create a memory BIO and write some data to it:
BIO *mem = BIO_new(BIO_s_mem());
BIO_puts(mem, "Hello World\n");
Create a read only memory BIO:
char data[] = "Hello World";
BIO *mem;
mem = BIO_new_mem_buf(data, -1);
Extract the BUF_MEM structure from a memory BIO and then free up the BIO:
BUF_MEM *bptr;
BIO_get_mem_ptr(mem, &bptr);
BIO_set_close(mem, BIO_NOCLOSE); /* So BIO_free() leaves BUF_MEM alone */
BIO_free(mem);
=head1 SEE ALSO
TBA

37
openssl-1.0.2f/doc/crypto/BIO_s_null.pod Normal file
View File

@@ -0,0 +1,37 @@
=pod
=head1 NAME
BIO_s_null - null data sink
=head1 SYNOPSIS
#include <openssl/bio.h>
BIO_METHOD * BIO_s_null(void);
=head1 DESCRIPTION
BIO_s_null() returns the null sink BIO method. Data written to
the null sink is discarded, reads return EOF.
=head1 NOTES
A null sink BIO behaves in a similar manner to the Unix /dev/null
device.
A null bio can be placed on the end of a chain to discard any data
passed through it.
A null sink is useful if, for example, an application wishes to digest some
data by writing through a digest bio but not send the digested data anywhere.
Since a BIO chain must normally include a source/sink BIO this can be achieved
by adding a null sink BIO to the end of the chain
=head1 RETURN VALUES
BIO_s_null() returns the null sink BIO method.
=head1 SEE ALSO
TBA

63
openssl-1.0.2f/doc/crypto/BIO_s_socket.pod Normal file
View File

@@ -0,0 +1,63 @@
=pod
=head1 NAME
BIO_s_socket, BIO_new_socket - socket BIO
=head1 SYNOPSIS
#include <openssl/bio.h>
BIO_METHOD *BIO_s_socket(void);
long BIO_set_fd(BIO *b, int fd, long close_flag);
long BIO_get_fd(BIO *b, int *c);
BIO *BIO_new_socket(int sock, int close_flag);
=head1 DESCRIPTION
BIO_s_socket() returns the socket BIO method. This is a wrapper
round the platform's socket routines.
BIO_read() and BIO_write() read or write the underlying socket.
BIO_puts() is supported but BIO_gets() is not.
If the close flag is set then the socket is shut down and closed
when the BIO is freed.
BIO_set_fd() sets the socket of BIO B<b> to B<fd> and the close
flag to B<close_flag>.
BIO_get_fd() places the socket in B<c> if it is not NULL, it also
returns the socket. If B<c> is not NULL it should be of type (int *).
BIO_new_socket() returns a socket BIO using B<sock> and B<close_flag>.
=head1 NOTES
Socket BIOs also support any relevant functionality of file descriptor
BIOs.
The reason for having separate file descriptor and socket BIOs is that on some
platforms sockets are not file descriptors and use distinct I/O routines,
Windows is one such platform. Any code mixing the two will not work on
all platforms.
BIO_set_fd() and BIO_get_fd() are macros.
=head1 RETURN VALUES
BIO_s_socket() returns the socket BIO method.
BIO_set_fd() always returns 1.
BIO_get_fd() returns the socket or -1 if the BIO has not been
initialized.
BIO_new_socket() returns the newly allocated BIO or NULL is an error
occurred.
=head1 SEE ALSO
TBA

108
openssl-1.0.2f/doc/crypto/BIO_set_callback.pod Normal file
View File

@@ -0,0 +1,108 @@
=pod
=head1 NAME
BIO_set_callback, BIO_get_callback, BIO_set_callback_arg, BIO_get_callback_arg,
BIO_debug_callback - BIO callback functions
=head1 SYNOPSIS
#include <openssl/bio.h>
#define BIO_set_callback(b,cb) ((b)->callback=(cb))
#define BIO_get_callback(b) ((b)->callback)
#define BIO_set_callback_arg(b,arg) ((b)->cb_arg=(char *)(arg))
#define BIO_get_callback_arg(b) ((b)->cb_arg)
long BIO_debug_callback(BIO *bio,int cmd,const char *argp,int argi,
long argl,long ret);
typedef long (*callback)(BIO *b, int oper, const char *argp,
int argi, long argl, long retvalue);
=head1 DESCRIPTION
BIO_set_callback() and BIO_get_callback() set and retrieve the BIO callback,
they are both macros. The callback is called during most high level BIO
operations. It can be used for debugging purposes to trace operations on
a BIO or to modify its operation.
BIO_set_callback_arg() and BIO_get_callback_arg() are macros which can be
used to set and retrieve an argument for use in the callback.
BIO_debug_callback() is a standard debugging callback which prints
out information relating to each BIO operation. If the callback
argument is set if is interpreted as a BIO to send the information
to, otherwise stderr is used.
callback() is the callback function itself. The meaning of each
argument is described below.
The BIO the callback is attached to is passed in B<b>.
B<oper> is set to the operation being performed. For some operations
the callback is called twice, once before and once after the actual
operation, the latter case has B<oper> or'ed with BIO_CB_RETURN.
The meaning of the arguments B<argp>, B<argi> and B<argl> depends on
the value of B<oper>, that is the operation being performed.
B<retvalue> is the return value that would be returned to the
application if no callback were present. The actual value returned
is the return value of the callback itself. In the case of callbacks
called before the actual BIO operation 1 is placed in retvalue, if
the return value is not positive it will be immediately returned to
the application and the BIO operation will not be performed.
The callback should normally simply return B<retvalue> when it has
finished processing, unless if specifically wishes to modify the
value returned to the application.
=head1 CALLBACK OPERATIONS
=over 4
=item B<BIO_free(b)>
callback(b, BIO_CB_FREE, NULL, 0L, 0L, 1L) is called before the
free operation.
=item B<BIO_read(b, out, outl)>
callback(b, BIO_CB_READ, out, outl, 0L, 1L) is called before
the read and callback(b, BIO_CB_READ|BIO_CB_RETURN, out, outl, 0L, retvalue)
after.
=item B<BIO_write(b, in, inl)>
callback(b, BIO_CB_WRITE, in, inl, 0L, 1L) is called before
the write and callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, inl, 0L, retvalue)
after.
=item B<BIO_gets(b, out, outl)>
callback(b, BIO_CB_GETS, out, outl, 0L, 1L) is called before
the operation and callback(b, BIO_CB_GETS|BIO_CB_RETURN, out, outl, 0L, retvalue)
after.
=item B<BIO_puts(b, in)>
callback(b, BIO_CB_WRITE, in, 0, 0L, 1L) is called before
the operation and callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, 0, 0L, retvalue)
after.
=item B<BIO_ctrl(BIO *b, int cmd, long larg, void *parg)>
callback(b,BIO_CB_CTRL,parg,cmd,larg,1L) is called before the call and
callback(b,BIO_CB_CTRL|BIO_CB_RETURN,parg,cmd, larg,ret) after.
=back
=head1 EXAMPLE
The BIO_debug_callback() function is a good example, its source is
in crypto/bio/bio_cb.c
=head1 SEE ALSO
TBA

114
openssl-1.0.2f/doc/crypto/BIO_should_retry.pod Normal file
View File

@@ -0,0 +1,114 @@
=pod
=head1 NAME
BIO_should_retry, BIO_should_read, BIO_should_write,
BIO_should_io_special, BIO_retry_type, BIO_should_retry,
BIO_get_retry_BIO, BIO_get_retry_reason - BIO retry functions
=head1 SYNOPSIS
#include <openssl/bio.h>
#define BIO_should_read(a) ((a)->flags & BIO_FLAGS_READ)
#define BIO_should_write(a) ((a)->flags & BIO_FLAGS_WRITE)
#define BIO_should_io_special(a) ((a)->flags & BIO_FLAGS_IO_SPECIAL)
#define BIO_retry_type(a) ((a)->flags & BIO_FLAGS_RWS)
#define BIO_should_retry(a) ((a)->flags & BIO_FLAGS_SHOULD_RETRY)
#define BIO_FLAGS_READ 0x01
#define BIO_FLAGS_WRITE 0x02
#define BIO_FLAGS_IO_SPECIAL 0x04
#define BIO_FLAGS_RWS (BIO_FLAGS_READ|BIO_FLAGS_WRITE|BIO_FLAGS_IO_SPECIAL)
#define BIO_FLAGS_SHOULD_RETRY 0x08
BIO * BIO_get_retry_BIO(BIO *bio, int *reason);
int BIO_get_retry_reason(BIO *bio);
=head1 DESCRIPTION
These functions determine why a BIO is not able to read or write data.
They will typically be called after a failed BIO_read() or BIO_write()
call.
BIO_should_retry() is true if the call that produced this condition
should then be retried at a later time.
If BIO_should_retry() is false then the cause is an error condition.
BIO_should_read() is true if the cause of the condition is that a BIO
needs to read data.
BIO_should_write() is true if the cause of the condition is that a BIO
needs to read data.
BIO_should_io_special() is true if some "special" condition, that is a
reason other than reading or writing is the cause of the condition.
BIO_retry_type() returns a mask of the cause of a retry condition
consisting of the values B<BIO_FLAGS_READ>, B<BIO_FLAGS_WRITE>,
B<BIO_FLAGS_IO_SPECIAL> though current BIO types will only set one of
these.
BIO_get_retry_BIO() determines the precise reason for the special
condition, it returns the BIO that caused this condition and if
B<reason> is not NULL it contains the reason code. The meaning of
the reason code and the action that should be taken depends on
the type of BIO that resulted in this condition.
BIO_get_retry_reason() returns the reason for a special condition if
passed the relevant BIO, for example as returned by BIO_get_retry_BIO().
=head1 NOTES
If BIO_should_retry() returns false then the precise "error condition"
depends on the BIO type that caused it and the return code of the BIO
operation. For example if a call to BIO_read() on a socket BIO returns
0 and BIO_should_retry() is false then the cause will be that the
connection closed. A similar condition on a file BIO will mean that it
has reached EOF. Some BIO types may place additional information on
the error queue. For more details see the individual BIO type manual
pages.
If the underlying I/O structure is in a blocking mode almost all current
BIO types will not request a retry, because the underlying I/O
calls will not. If the application knows that the BIO type will never
signal a retry then it need not call BIO_should_retry() after a failed
BIO I/O call. This is typically done with file BIOs.
SSL BIOs are the only current exception to this rule: they can request a
retry even if the underlying I/O structure is blocking, if a handshake
occurs during a call to BIO_read(). An application can retry the failed
call immediately or avoid this situation by setting SSL_MODE_AUTO_RETRY
on the underlying SSL structure.
While an application may retry a failed non blocking call immediately
this is likely to be very inefficient because the call will fail
repeatedly until data can be processed or is available. An application
will normally wait until the necessary condition is satisfied. How
this is done depends on the underlying I/O structure.
For example if the cause is ultimately a socket and BIO_should_read()
is true then a call to select() may be made to wait until data is
available and then retry the BIO operation. By combining the retry
conditions of several non blocking BIOs in a single select() call
it is possible to service several BIOs in a single thread, though
the performance may be poor if SSL BIOs are present because long delays
can occur during the initial handshake process.
It is possible for a BIO to block indefinitely if the underlying I/O
structure cannot process or return any data. This depends on the behaviour of
the platforms I/O functions. This is often not desirable: one solution
is to use non blocking I/O and use a timeout on the select() (or
equivalent) call.
=head1 BUGS
The OpenSSL ASN1 functions cannot gracefully deal with non blocking I/O:
that is they cannot retry after a partial read or write. This is usually
worked around by only passing the relevant data to ASN1 functions when
the entire structure can be read or written.
=head1 SEE ALSO
TBA

115
openssl-1.0.2f/doc/crypto/BN_BLINDING_new.pod Normal file
View File

@@ -0,0 +1,115 @@
=pod
=head1 NAME
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_thread_id, BN_BLINDING_get_flags,
BN_BLINDING_set_flags, BN_BLINDING_create_param - blinding related BIGNUM
functions.
=head1 SYNOPSIS
#include <openssl/bn.h>
BN_BLINDING *BN_BLINDING_new(const BIGNUM *A, const BIGNUM *Ai,
BIGNUM *mod);
void BN_BLINDING_free(BN_BLINDING *b);
int BN_BLINDING_update(BN_BLINDING *b,BN_CTX *ctx);
int BN_BLINDING_convert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx);
int BN_BLINDING_invert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx);
int BN_BLINDING_convert_ex(BIGNUM *n, BIGNUM *r, BN_BLINDING *b,
BN_CTX *ctx);
int BN_BLINDING_invert_ex(BIGNUM *n, const BIGNUM *r, BN_BLINDING *b,
BN_CTX *ctx);
#ifndef OPENSSL_NO_DEPRECATED
unsigned long BN_BLINDING_get_thread_id(const BN_BLINDING *);
void BN_BLINDING_set_thread_id(BN_BLINDING *, unsigned long);
#endif
CRYPTO_THREADID *BN_BLINDING_thread_id(BN_BLINDING *);
unsigned long BN_BLINDING_get_flags(const BN_BLINDING *);
void BN_BLINDING_set_flags(BN_BLINDING *, unsigned long);
BN_BLINDING *BN_BLINDING_create_param(BN_BLINDING *b,
const BIGNUM *e, BIGNUM *m, BN_CTX *ctx,
int (*bn_mod_exp)(BIGNUM *r, const BIGNUM *a, const BIGNUM *p,
const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx),
BN_MONT_CTX *m_ctx);
=head1 DESCRIPTION
BN_BLINDING_new() allocates a new B<BN_BLINDING> structure and copies
the B<A> and B<Ai> values into the newly created B<BN_BLINDING> object.
BN_BLINDING_free() frees the B<BN_BLINDING> structure.
BN_BLINDING_update() updates the B<BN_BLINDING> parameters by squaring
the B<A> and B<Ai> or, after specific number of uses and if the
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 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.
BN_BLINDING_convert() and BN_BLINDING_invert() are wrapper
functions for BN_BLINDING_convert_ex() and BN_BLINDING_invert_ex()
with B<r> set to NULL.
BN_BLINDING_thread_id() provides access to the B<CRYPTO_THREADID>
object within the B<BN_BLINDING> structure. This is to help users
provide proper locking if needed for multi-threaded use. The "thread
id" object of a newly allocated B<BN_BLINDING> structure is
initialised to the thread id in which BN_BLINDING_new() was called.
BN_BLINDING_get_flags() returns the BN_BLINDING flags. Currently
there are two supported flags: B<BN_BLINDING_NO_UPDATE> and
B<BN_BLINDING_NO_RECREATE>. B<BN_BLINDING_NO_UPDATE> inhibits the
automatic update of the B<BN_BLINDING> parameters after each use
and B<BN_BLINDING_NO_RECREATE> inhibits the automatic re-creation
of the B<BN_BLINDING> parameters after a fixed number of uses (currently
32). In newly allocated B<BN_BLINDING> objects no flags are set.
BN_BLINDING_set_flags() sets the B<BN_BLINDING> parameters flags.
BN_BLINDING_create_param() creates new B<BN_BLINDING> parameters
using the exponent B<e> and the modulus B<m>. B<bn_mod_exp> and
B<m_ctx> can be used to pass special functions for exponentiation
(normally BN_mod_exp_mont() and B<BN_MONT_CTX>).
=head1 RETURN VALUES
BN_BLINDING_new() returns the newly allocated B<BN_BLINDING> structure
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 occurred.
BN_BLINDING_thread_id() returns a pointer to the thread id object
within a B<BN_BLINDING> object.
BN_BLINDING_get_flags() returns the currently set B<BN_BLINDING> flags
(a B<unsigned long> value).
BN_BLINDING_create_param() returns the newly created B<BN_BLINDING>
parameters or NULL on error.
=head1 SEE ALSO
L<bn(3)|bn(3)>
=head1 HISTORY
BN_BLINDING_thread_id was first introduced in OpenSSL 1.0.0, and it
deprecates BN_BLINDING_set_thread_id and BN_BLINDING_get_thread_id.
BN_BLINDING_convert_ex, BN_BLINDIND_invert_ex, BN_BLINDING_get_thread_id,
BN_BLINDING_set_thread_id, BN_BLINDING_set_flags, BN_BLINDING_get_flags
and BN_BLINDING_create_param were first introduced in OpenSSL 0.9.8
=head1 AUTHOR
Nils Larsch for the OpenSSL project (http://www.openssl.org).
=cut

57
openssl-1.0.2f/doc/crypto/BN_CTX_new.pod Normal file
View File

@@ -0,0 +1,57 @@
=pod
=head1 NAME
BN_CTX_new, BN_CTX_init, BN_CTX_free - allocate and free BN_CTX structures
=head1 SYNOPSIS
#include <openssl/bn.h>
BN_CTX *BN_CTX_new(void);
void BN_CTX_free(BN_CTX *c);
Deprecated:
void BN_CTX_init(BN_CTX *c);
=head1 DESCRIPTION
A B<BN_CTX> is a structure that holds B<BIGNUM> temporary variables used by
library functions. Since dynamic memory allocation to create B<BIGNUM>s
is rather expensive when used in conjunction with repeated subroutine
calls, the B<BN_CTX> structure is used.
BN_CTX_new() allocates and initializes a 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.
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
BN_CTX_new() returns a pointer to the B<BN_CTX>. If the allocation fails,
it returns B<NULL> and sets an error code that can be obtained by
L<ERR_get_error(3)|ERR_get_error(3)>.
BN_CTX_init() and BN_CTX_free() have no return values.
=head1 SEE ALSO
L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_add(3)|BN_add(3)>,
L<BN_CTX_start(3)|BN_CTX_start(3)>
=head1 HISTORY
BN_CTX_new() and BN_CTX_free() are available in all versions on SSLeay
and OpenSSL. BN_CTX_init() was added in SSLeay 0.9.1b.
=cut

52
openssl-1.0.2f/doc/crypto/BN_CTX_start.pod Normal file
View File

@@ -0,0 +1,52 @@
=pod
=head1 NAME
BN_CTX_start, BN_CTX_get, BN_CTX_end - use temporary BIGNUM variables
=head1 SYNOPSIS
#include <openssl/bn.h>
void BN_CTX_start(BN_CTX *ctx);
BIGNUM *BN_CTX_get(BN_CTX *ctx);
void BN_CTX_end(BN_CTX *ctx);
=head1 DESCRIPTION
These functions are used to obtain temporary B<BIGNUM> variables from
a B<BN_CTX> (which can been created by using L<BN_CTX_new(3)|BN_CTX_new(3)>)
in order to save the overhead of repeatedly creating and
freeing B<BIGNUM>s in functions that are called from inside a loop.
A function must call BN_CTX_start() first. Then, BN_CTX_get() may be
called repeatedly to obtain temporary B<BIGNUM>s. All BN_CTX_get()
calls must be made before calling any other functions that use the
B<ctx> as an argument.
Finally, BN_CTX_end() must be called before returning from the function.
When BN_CTX_end() is called, the B<BIGNUM> pointers obtained from
BN_CTX_get() become invalid.
=head1 RETURN VALUES
BN_CTX_start() and BN_CTX_end() return no values.
BN_CTX_get() returns a pointer to the B<BIGNUM>, or B<NULL> on error.
Once BN_CTX_get() has failed, the subsequent calls will return B<NULL>
as well, so it is sufficient to check the return value of the last
BN_CTX_get() call. In case of an error, an error code is set, which
can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
=head1 SEE ALSO
L<BN_CTX_new(3)|BN_CTX_new(3)>
=head1 HISTORY
BN_CTX_start(), BN_CTX_get() and BN_CTX_end() were added in OpenSSL 0.9.5.
=cut

126
openssl-1.0.2f/doc/crypto/BN_add.pod Normal file
View File

@@ -0,0 +1,126 @@
=pod
=head1 NAME
BN_add, BN_sub, BN_mul, BN_sqr, BN_div, BN_mod, BN_nnmod, BN_mod_add,
BN_mod_sub, BN_mod_mul, BN_mod_sqr, BN_exp, BN_mod_exp, BN_gcd -
arithmetic operations on BIGNUMs
=head1 SYNOPSIS
#include <openssl/bn.h>
int BN_add(BIGNUM *r, const BIGNUM *a, const BIGNUM *b);
int BN_sub(BIGNUM *r, const BIGNUM *a, const BIGNUM *b);
int BN_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx);
int BN_sqr(BIGNUM *r, BIGNUM *a, BN_CTX *ctx);
int BN_div(BIGNUM *dv, BIGNUM *rem, const BIGNUM *a, const BIGNUM *d,
BN_CTX *ctx);
int BN_mod(BIGNUM *rem, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx);
int BN_nnmod(BIGNUM *r, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx);
int BN_mod_add(BIGNUM *r, BIGNUM *a, BIGNUM *b, const BIGNUM *m,
BN_CTX *ctx);
int BN_mod_sub(BIGNUM *r, BIGNUM *a, BIGNUM *b, const BIGNUM *m,
BN_CTX *ctx);
int BN_mod_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b, const BIGNUM *m,
BN_CTX *ctx);
int BN_mod_sqr(BIGNUM *r, BIGNUM *a, const BIGNUM *m, BN_CTX *ctx);
int BN_exp(BIGNUM *r, BIGNUM *a, BIGNUM *p, BN_CTX *ctx);
int BN_mod_exp(BIGNUM *r, BIGNUM *a, const BIGNUM *p,
const BIGNUM *m, BN_CTX *ctx);
int BN_gcd(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx);
=head1 DESCRIPTION
BN_add() adds I<a> and I<b> and places the result in I<r> (C<r=a+b>).
I<r> may be the same B<BIGNUM> as I<a> or I<b>.
BN_sub() subtracts I<b> from I<a> and places the result in I<r> (C<r=a-b>).
BN_mul() multiplies I<a> and I<b> and places the result in I<r> (C<r=a*b>).
I<r> may be the same B<BIGNUM> as I<a> or I<b>.
For multiplication by powers of 2, use L<BN_lshift(3)|BN_lshift(3)>.
BN_sqr() takes the square of I<a> and places the result in I<r>
(C<r=a^2>). I<r> and I<a> may be the same B<BIGNUM>.
This function is faster than BN_mul(r,a,a).
BN_div() divides I<a> by I<d> and places the result in I<dv> and the
remainder in I<rem> (C<dv=a/d, rem=a%d>). Either of I<dv> and I<rem> may
be B<NULL>, in which case the respective value is not returned.
The result is rounded towards zero; thus if I<a> is negative, the
remainder will be zero or negative.
For division by powers of 2, use BN_rshift(3).
BN_mod() corresponds to BN_div() with I<dv> set to B<NULL>.
BN_nnmod() reduces I<a> modulo I<m> and places the non-negative
remainder in I<r>.
BN_mod_add() adds I<a> to I<b> modulo I<m> and places the non-negative
result in I<r>.
BN_mod_sub() subtracts I<b> from I<a> modulo I<m> and places the
non-negative result in I<r>.
BN_mod_mul() multiplies I<a> by I<b> and finds the non-negative
remainder respective to modulus I<m> (C<r=(a*b) mod m>). I<r> may be
the same B<BIGNUM> as I<a> or I<b>. For more efficient algorithms for
repeated computations using the same modulus, see
L<BN_mod_mul_montgomery(3)|BN_mod_mul_montgomery(3)> and
L<BN_mod_mul_reciprocal(3)|BN_mod_mul_reciprocal(3)>.
BN_mod_sqr() takes the square of I<a> modulo B<m> and places the
result in I<r>.
BN_exp() raises I<a> to the I<p>-th power and places the result in I<r>
(C<r=a^p>). This function is faster than repeated applications of
BN_mul().
BN_mod_exp() computes I<a> to the I<p>-th power modulo I<m> (C<r=a^p %
m>). This function uses less time and space than BN_exp().
BN_gcd() computes the greatest common divisor of I<a> and I<b> and
places the result in I<r>. I<r> may be the same B<BIGNUM> as I<a> or
I<b>.
For all functions, I<ctx> is a previously allocated B<BN_CTX> used for
temporary variables; see L<BN_CTX_new(3)|BN_CTX_new(3)>.
Unless noted otherwise, the result B<BIGNUM> must be different from
the arguments.
=head1 RETURN VALUES
For all functions, 1 is returned for success, 0 on error. The return
value should always be checked (e.g., C<if (!BN_add(r,a,b)) goto err;>).
The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
=head1 SEE ALSO
L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_CTX_new(3)|BN_CTX_new(3)>,
L<BN_add_word(3)|BN_add_word(3)>, L<BN_set_bit(3)|BN_set_bit(3)>
=head1 HISTORY
BN_add(), BN_sub(), BN_sqr(), BN_div(), BN_mod(), BN_mod_mul(),
BN_mod_exp() and BN_gcd() are available in all versions of SSLeay and
OpenSSL. The I<ctx> argument to BN_mul() was added in SSLeay
0.9.1b. BN_exp() appeared in SSLeay 0.9.0.
BN_nnmod(), BN_mod_add(), BN_mod_sub(), and BN_mod_sqr() were added in
OpenSSL 0.9.7.
=cut

61
openssl-1.0.2f/doc/crypto/BN_add_word.pod Normal file
View File

@@ -0,0 +1,61 @@
=pod
=head1 NAME
BN_add_word, BN_sub_word, BN_mul_word, BN_div_word, BN_mod_word - arithmetic
functions on BIGNUMs with integers
=head1 SYNOPSIS
#include <openssl/bn.h>
int BN_add_word(BIGNUM *a, BN_ULONG w);
int BN_sub_word(BIGNUM *a, BN_ULONG w);
int BN_mul_word(BIGNUM *a, BN_ULONG w);
BN_ULONG BN_div_word(BIGNUM *a, BN_ULONG w);
BN_ULONG BN_mod_word(const BIGNUM *a, BN_ULONG w);
=head1 DESCRIPTION
These functions perform arithmetic operations on BIGNUMs with unsigned
integers. They are much more efficient than the normal BIGNUM
arithmetic operations.
BN_add_word() adds B<w> to B<a> (C<a+=w>).
BN_sub_word() subtracts B<w> from B<a> (C<a-=w>).
BN_mul_word() multiplies B<a> and B<w> (C<a*=w>).
BN_div_word() divides B<a> by B<w> (C<a/=w>) and returns the remainder.
BN_mod_word() returns the remainder of B<a> divided by B<w> (C<a%w>).
For BN_div_word() and BN_mod_word(), B<w> must not be 0.
=head1 RETURN VALUES
BN_add_word(), BN_sub_word() and BN_mul_word() return 1 for success, 0
on error. The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
BN_mod_word() and BN_div_word() return B<a>%B<w> on success and
B<(BN_ULONG)-1> if an error occurred.
=head1 SEE ALSO
L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_add(3)|BN_add(3)>
=head1 HISTORY
BN_add_word() and BN_mod_word() are available in all versions of
SSLeay and OpenSSL. BN_div_word() was added in SSLeay 0.8, and
BN_sub_word() and BN_mul_word() in SSLeay 0.9.0.
Before 0.9.8a the return value for BN_div_word() and BN_mod_word()
in case of an error was 0.
=cut

95
openssl-1.0.2f/doc/crypto/BN_bn2bin.pod Normal file
View File

@@ -0,0 +1,95 @@
=pod
=head1 NAME
BN_bn2bin, BN_bin2bn, BN_bn2hex, BN_bn2dec, BN_hex2bn, BN_dec2bn,
BN_print, BN_print_fp, BN_bn2mpi, BN_mpi2bn - format conversions
=head1 SYNOPSIS
#include <openssl/bn.h>
int BN_bn2bin(const BIGNUM *a, unsigned char *to);
BIGNUM *BN_bin2bn(const unsigned char *s, int len, BIGNUM *ret);
char *BN_bn2hex(const BIGNUM *a);
char *BN_bn2dec(const BIGNUM *a);
int BN_hex2bn(BIGNUM **a, const char *str);
int BN_dec2bn(BIGNUM **a, const char *str);
int BN_print(BIO *fp, const BIGNUM *a);
int BN_print_fp(FILE *fp, const BIGNUM *a);
int BN_bn2mpi(const BIGNUM *a, unsigned char *to);
BIGNUM *BN_mpi2bn(unsigned char *s, int len, BIGNUM *ret);
=head1 DESCRIPTION
BN_bn2bin() converts the absolute value of B<a> into big-endian form
and stores it at B<to>. B<to> must point to BN_num_bytes(B<a>) bytes of
memory.
BN_bin2bn() converts the positive integer in big-endian form of length
B<len> at B<s> into a B<BIGNUM> and places it in B<ret>. If B<ret> is
NULL, a new B<BIGNUM> is created.
BN_bn2hex() and BN_bn2dec() return printable strings containing the
hexadecimal and decimal encoding of B<a> respectively. For negative
numbers, the string is prefaced with a leading '-'. The string must be
freed later using OPENSSL_free().
BN_hex2bn() converts the string B<str> containing a hexadecimal number
to a B<BIGNUM> and stores it in **B<bn>. If *B<bn> is NULL, a new
B<BIGNUM> is created. If B<bn> is NULL, it only computes the number's
length in hexadecimal digits. If the string starts with '-', the
number is negative. BN_dec2bn() is the same using the decimal system.
BN_print() and BN_print_fp() write the hexadecimal encoding of B<a>,
with a leading '-' for negative numbers, to the B<BIO> or B<FILE>
B<fp>.
BN_bn2mpi() and BN_mpi2bn() convert B<BIGNUM>s from and to a format
that consists of the number's length in bytes represented as a 4-byte
big-endian number, and the number itself in big-endian format, where
the most significant bit signals a negative number (the representation
of numbers with the MSB set is prefixed with null byte).
BN_bn2mpi() stores the representation of B<a> at B<to>, where B<to>
must be large enough to hold the result. The size can be determined by
calling BN_bn2mpi(B<a>, NULL).
BN_mpi2bn() converts the B<len> bytes long representation at B<s> to
a B<BIGNUM> and stores it at B<ret>, or in a newly allocated B<BIGNUM>
if B<ret> is NULL.
=head1 RETURN VALUES
BN_bn2bin() returns the length of the big-endian number placed at B<to>.
BN_bin2bn() returns the B<BIGNUM>, NULL on error.
BN_bn2hex() and BN_bn2dec() return a null-terminated string, or NULL
on error. BN_hex2bn() and BN_dec2bn() return the number's length in
hexadecimal or decimal digits, and 0 on error.
BN_print_fp() and BN_print() return 1 on success, 0 on write errors.
BN_bn2mpi() returns the length of the representation. BN_mpi2bn()
returns the B<BIGNUM>, and NULL on error.
The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
=head1 SEE ALSO
L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_zero(3)|BN_zero(3)>,
L<ASN1_INTEGER_to_BN(3)|ASN1_INTEGER_to_BN(3)>,
L<BN_num_bytes(3)|BN_num_bytes(3)>
=head1 HISTORY
BN_bn2bin(), BN_bin2bn(), BN_print_fp() and BN_print() are available
in all versions of SSLeay and OpenSSL.
BN_bn2hex(), BN_bn2dec(), BN_hex2bn(), BN_dec2bn(), BN_bn2mpi() and
BN_mpi2bn() were added in SSLeay 0.9.0.
=cut

48
openssl-1.0.2f/doc/crypto/BN_cmp.pod Normal file
View File

@@ -0,0 +1,48 @@
=pod
=head1 NAME
BN_cmp, BN_ucmp, BN_is_zero, BN_is_one, BN_is_word, BN_is_odd - BIGNUM comparison and test functions
=head1 SYNOPSIS
#include <openssl/bn.h>
int BN_cmp(BIGNUM *a, BIGNUM *b);
int BN_ucmp(BIGNUM *a, BIGNUM *b);
int BN_is_zero(BIGNUM *a);
int BN_is_one(BIGNUM *a);
int BN_is_word(BIGNUM *a, BN_ULONG w);
int BN_is_odd(BIGNUM *a);
=head1 DESCRIPTION
BN_cmp() compares the numbers B<a> and B<b>. BN_ucmp() compares their
absolute values.
BN_is_zero(), BN_is_one() and BN_is_word() test if B<a> equals 0, 1,
or B<w> respectively. BN_is_odd() tests if a is odd.
BN_is_zero(), BN_is_one(), BN_is_word() and BN_is_odd() are macros.
=head1 RETURN VALUES
BN_cmp() returns -1 if B<a> E<lt> B<b>, 0 if B<a> == B<b> and 1 if
B<a> E<gt> B<b>. BN_ucmp() is the same using the absolute values
of B<a> and B<b>.
BN_is_zero(), BN_is_one() BN_is_word() and BN_is_odd() return 1 if
the condition is true, 0 otherwise.
=head1 SEE ALSO
L<bn(3)|bn(3)>
=head1 HISTORY
BN_cmp(), BN_ucmp(), BN_is_zero(), BN_is_one() and BN_is_word() are
available in all versions of SSLeay and OpenSSL.
BN_is_odd() was added in SSLeay 0.8.
=cut

34
openssl-1.0.2f/doc/crypto/BN_copy.pod Normal file
View File

@@ -0,0 +1,34 @@
=pod
=head1 NAME
BN_copy, BN_dup - copy BIGNUMs
=head1 SYNOPSIS
#include <openssl/bn.h>
BIGNUM *BN_copy(BIGNUM *to, const BIGNUM *from);
BIGNUM *BN_dup(const BIGNUM *from);
=head1 DESCRIPTION
BN_copy() copies B<from> to B<to>. BN_dup() creates a new B<BIGNUM>
containing the value B<from>.
=head1 RETURN VALUES
BN_copy() returns B<to> on success, NULL on error. BN_dup() returns
the new B<BIGNUM>, and NULL on error. The error codes can be obtained
by L<ERR_get_error(3)|ERR_get_error(3)>.
=head1 SEE ALSO
L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>
=head1 HISTORY
BN_copy() and BN_dup() are available in all versions of SSLeay and OpenSSL.
=cut

150
openssl-1.0.2f/doc/crypto/BN_generate_prime.pod Normal file
View File

@@ -0,0 +1,150 @@
=pod
=head1 NAME
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);
int BN_is_prime(const BIGNUM *a, int checks, void (*callback)(int, int,
void *), BN_CTX *ctx, void *cb_arg);
int BN_is_prime_fasttest(const BIGNUM *a, int checks,
void (*callback)(int, int, void *), BN_CTX *ctx, void *cb_arg,
int do_trial_division);
=head1 DESCRIPTION
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<cb> is not B<NULL>, it is used as follows:
=over 4
=item *
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<BN_GENCB_call(cb, 1, j)> is called as described below.
=item *
When a prime has been found, B<BN_GENCB_call(cb, 2, i)> is called.
=back
The prime may have to fulfill additional requirements for use in
Diffie-Hellman key exchange:
If B<add> is not B<NULL>, the prime will fulfill the condition p % B<add>
== B<rem> (p % B<add> == 1 if B<rem> == B<NULL>) in order to suit a given
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_ex().
The prime number generation has a negligible error probability.
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<p> is composite; if B<p> passes all these tests, it is considered
prime.
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<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_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<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.
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)>.
=head1 SEE ALSO
L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>
=head1 HISTORY
The B<cb_arg> arguments to BN_generate_prime() and to BN_is_prime()
were added in SSLeay 0.9.0. The B<ret> argument to BN_generate_prime()
was added in SSLeay 0.9.1.
BN_is_prime_fasttest() was added in OpenSSL 0.9.5.
=cut

36
openssl-1.0.2f/doc/crypto/BN_mod_inverse.pod Normal file
View File

@@ -0,0 +1,36 @@
=pod
=head1 NAME
BN_mod_inverse - compute inverse modulo n
=head1 SYNOPSIS
#include <openssl/bn.h>
BIGNUM *BN_mod_inverse(BIGNUM *r, BIGNUM *a, const BIGNUM *n,
BN_CTX *ctx);
=head1 DESCRIPTION
BN_mod_inverse() computes the inverse of B<a> modulo B<n>
places the result in B<r> (C<(a*r)%n==1>). If B<r> is NULL,
a new B<BIGNUM> is created.
B<ctx> is a previously allocated B<BN_CTX> used for temporary
variables. B<r> may be the same B<BIGNUM> as B<a> or B<n>.
=head1 RETURN VALUES
BN_mod_inverse() returns the B<BIGNUM> containing the inverse, and
NULL on error. The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
=head1 SEE ALSO
L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_add(3)|BN_add(3)>
=head1 HISTORY
BN_mod_inverse() is available in all versions of SSLeay and OpenSSL.
=cut

101
openssl-1.0.2f/doc/crypto/BN_mod_mul_montgomery.pod Normal file
View File

@@ -0,0 +1,101 @@
=pod
=head1 NAME
BN_mod_mul_montgomery, BN_MONT_CTX_new, BN_MONT_CTX_init,
BN_MONT_CTX_free, BN_MONT_CTX_set, BN_MONT_CTX_copy,
BN_from_montgomery, BN_to_montgomery - Montgomery multiplication
=head1 SYNOPSIS
#include <openssl/bn.h>
BN_MONT_CTX *BN_MONT_CTX_new(void);
void BN_MONT_CTX_init(BN_MONT_CTX *ctx);
void BN_MONT_CTX_free(BN_MONT_CTX *mont);
int BN_MONT_CTX_set(BN_MONT_CTX *mont, const BIGNUM *m, BN_CTX *ctx);
BN_MONT_CTX *BN_MONT_CTX_copy(BN_MONT_CTX *to, BN_MONT_CTX *from);
int BN_mod_mul_montgomery(BIGNUM *r, BIGNUM *a, BIGNUM *b,
BN_MONT_CTX *mont, BN_CTX *ctx);
int BN_from_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont,
BN_CTX *ctx);
int BN_to_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont,
BN_CTX *ctx);
=head1 DESCRIPTION
These functions implement Montgomery multiplication. They are used
automatically when L<BN_mod_exp(3)|BN_mod_exp(3)> is called with suitable input,
but they may be useful when several operations are to be performed
using the same modulus.
BN_MONT_CTX_new() allocates and initializes a B<BN_MONT_CTX> structure.
BN_MONT_CTX_init() initializes an existing uninitialized B<BN_MONT_CTX>.
BN_MONT_CTX_set() sets up the I<mont> structure from the modulus I<m>
by precomputing its inverse and a value R.
BN_MONT_CTX_copy() copies the B<BN_MONT_CTX> I<from> to I<to>.
BN_MONT_CTX_free() frees the components of the B<BN_MONT_CTX>, and, if
it was created by BN_MONT_CTX_new(), also the structure itself.
BN_mod_mul_montgomery() computes Mont(I<a>,I<b>):=I<a>*I<b>*R^-1 and places
the result in I<r>.
BN_from_montgomery() performs the Montgomery reduction I<r> = I<a>*R^-1.
BN_to_montgomery() computes Mont(I<a>,R^2), i.e. I<a>*R.
Note that I<a> must be non-negative and smaller than the modulus.
For all functions, I<ctx> is a previously allocated B<BN_CTX> used for
temporary variables.
The B<BN_MONT_CTX> structure is defined as follows:
typedef struct bn_mont_ctx_st
{
int ri; /* number of bits in R */
BIGNUM RR; /* R^2 (used to convert to Montgomery form) */
BIGNUM N; /* The modulus */
BIGNUM Ni; /* R*(1/R mod N) - N*Ni = 1
* (Ni is only stored for bignum algorithm) */
BN_ULONG n0; /* least significant word of Ni */
int flags;
} BN_MONT_CTX;
BN_to_montgomery() is a macro.
=head1 RETURN VALUES
BN_MONT_CTX_new() returns the newly allocated B<BN_MONT_CTX>, and NULL
on error.
BN_MONT_CTX_init() and BN_MONT_CTX_free() have no return values.
For the other functions, 1 is returned for success, 0 on error.
The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
=head1 WARNING
The inputs must be reduced modulo B<m>, otherwise the result will be
outside the expected range.
=head1 SEE ALSO
L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_add(3)|BN_add(3)>,
L<BN_CTX_new(3)|BN_CTX_new(3)>
=head1 HISTORY
BN_MONT_CTX_new(), BN_MONT_CTX_free(), BN_MONT_CTX_set(),
BN_mod_mul_montgomery(), BN_from_montgomery() and BN_to_montgomery()
are available in all versions of SSLeay and OpenSSL.
BN_MONT_CTX_init() and BN_MONT_CTX_copy() were added in SSLeay 0.9.1b.
=cut

81
openssl-1.0.2f/doc/crypto/BN_mod_mul_reciprocal.pod Normal file
View File

@@ -0,0 +1,81 @@
=pod
=head1 NAME
BN_mod_mul_reciprocal, BN_div_recp, BN_RECP_CTX_new, BN_RECP_CTX_init,
BN_RECP_CTX_free, BN_RECP_CTX_set - modular multiplication using
reciprocal
=head1 SYNOPSIS
#include <openssl/bn.h>
BN_RECP_CTX *BN_RECP_CTX_new(void);
void BN_RECP_CTX_init(BN_RECP_CTX *recp);
void BN_RECP_CTX_free(BN_RECP_CTX *recp);
int BN_RECP_CTX_set(BN_RECP_CTX *recp, const BIGNUM *m, BN_CTX *ctx);
int BN_div_recp(BIGNUM *dv, BIGNUM *rem, BIGNUM *a, BN_RECP_CTX *recp,
BN_CTX *ctx);
int BN_mod_mul_reciprocal(BIGNUM *r, BIGNUM *a, BIGNUM *b,
BN_RECP_CTX *recp, BN_CTX *ctx);
=head1 DESCRIPTION
BN_mod_mul_reciprocal() can be used to perform an efficient
L<BN_mod_mul(3)|BN_mod_mul(3)> operation when the operation will be performed
repeatedly with the same modulus. It computes B<r>=(B<a>*B<b>)%B<m>
using B<recp>=1/B<m>, which is set as described below. B<ctx> is a
previously allocated B<BN_CTX> used for temporary variables.
BN_RECP_CTX_new() allocates and initializes a B<BN_RECP> structure.
BN_RECP_CTX_init() initializes an existing uninitialized B<BN_RECP>.
BN_RECP_CTX_free() frees the components of the B<BN_RECP>, and, if it
was created by BN_RECP_CTX_new(), also the structure itself.
BN_RECP_CTX_set() stores B<m> in B<recp> and sets it up for computing
1/B<m> and shifting it left by BN_num_bits(B<m>)+1 to make it an
integer. The result and the number of bits it was shifted left will
later be stored in B<recp>.
BN_div_recp() divides B<a> by B<m> using B<recp>. It places the quotient
in B<dv> and the remainder in B<rem>.
The B<BN_RECP_CTX> structure is defined as follows:
typedef struct bn_recp_ctx_st
{
BIGNUM N; /* the divisor */
BIGNUM Nr; /* the reciprocal */
int num_bits;
int shift;
int flags;
} BN_RECP_CTX;
It cannot be shared between threads.
=head1 RETURN VALUES
BN_RECP_CTX_new() returns the newly allocated B<BN_RECP_CTX>, and NULL
on error.
BN_RECP_CTX_init() and BN_RECP_CTX_free() have no return values.
For the other functions, 1 is returned for success, 0 on error.
The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
=head1 SEE ALSO
L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_add(3)|BN_add(3)>,
L<BN_CTX_new(3)|BN_CTX_new(3)>
=head1 HISTORY
B<BN_RECP_CTX> was added in SSLeay 0.9.0. Before that, the function
BN_reciprocal() was used instead, and the BN_mod_mul_reciprocal()
arguments were different.
=cut

53
openssl-1.0.2f/doc/crypto/BN_new.pod Normal file
View File

@@ -0,0 +1,53 @@
=pod
=head1 NAME
BN_new, BN_init, BN_clear, BN_free, BN_clear_free - allocate and free BIGNUMs
=head1 SYNOPSIS
#include <openssl/bn.h>
BIGNUM *BN_new(void);
void BN_init(BIGNUM *);
void BN_clear(BIGNUM *a);
void BN_free(BIGNUM *a);
void BN_clear_free(BIGNUM *a);
=head1 DESCRIPTION
BN_new() allocates and initializes a B<BIGNUM> structure. BN_init()
initializes an existing uninitialized B<BIGNUM>.
BN_clear() is used to destroy sensitive data such as keys when they
are no longer needed. It erases the memory used by B<a> and sets it
to the value 0.
BN_free() frees the components of the B<BIGNUM>, and if it was created
by BN_new(), also the structure itself. BN_clear_free() additionally
overwrites the data before the memory is returned to the system.
=head1 RETURN VALUES
BN_new() returns a pointer to the B<BIGNUM>. If the allocation fails,
it returns B<NULL> and sets an error code that can be obtained
by L<ERR_get_error(3)|ERR_get_error(3)>.
BN_init(), BN_clear(), BN_free() and BN_clear_free() have no return
values.
=head1 SEE ALSO
L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>
=head1 HISTORY
BN_new(), BN_clear(), BN_free() and BN_clear_free() are available in
all versions on SSLeay and OpenSSL. BN_init() was added in SSLeay
0.9.1b.
=cut

57
openssl-1.0.2f/doc/crypto/BN_num_bytes.pod Normal file
View File

@@ -0,0 +1,57 @@
=pod
=head1 NAME
BN_num_bits, BN_num_bytes, BN_num_bits_word - get BIGNUM size
=head1 SYNOPSIS
#include <openssl/bn.h>
int BN_num_bytes(const BIGNUM *a);
int BN_num_bits(const BIGNUM *a);
int BN_num_bits_word(BN_ULONG w);
=head1 DESCRIPTION
BN_num_bytes() returns the size of a B<BIGNUM> in bytes.
BN_num_bits_word() returns the number of significant bits in a word.
If we take 0x00000432 as an example, it returns 11, not 16, not 32.
Basically, except for a zero, it returns I<floor(log2(w))+1>.
BN_num_bits() returns the number of significant bits in a B<BIGNUM>,
following the same principle as BN_num_bits_word().
BN_num_bytes() is a macro.
=head1 RETURN VALUES
The size.
=head1 NOTES
Some have tried using BN_num_bits() on individual numbers in RSA keys,
DH keys and DSA keys, and found that they don't always come up with
the number of bits they expected (something like 512, 1024, 2048,
...). This is because generating a number with some specific number
of bits doesn't always set the highest bits, thereby making the number
of I<significant> bits a little lower. If you want to know the "key
size" of such a key, either use functions like RSA_size(), DH_size()
and DSA_size(), or use BN_num_bytes() and multiply with 8 (although
there's no real guarantee that will match the "key size", just a lot
more probability).
=head1 SEE ALSO
L<bn(3)|bn(3)>, L<DH_size(3)|DH_size(3)>, L<DSA_size(3)|DSA_size(3)>,
L<RSA_size(3)|RSA_size(3)>
=head1 HISTORY
BN_num_bytes(), BN_num_bits() and BN_num_bits_word() are available in
all versions of SSLeay and OpenSSL.
=cut

59
openssl-1.0.2f/doc/crypto/BN_rand.pod Normal file
View File

@@ -0,0 +1,59 @@
=pod
=head1 NAME
BN_rand, BN_pseudo_rand, BN_rand_range, BN_pseudo_rand_range - generate pseudo-random number
=head1 SYNOPSIS
#include <openssl/bn.h>
int BN_rand(BIGNUM *rnd, int bits, int top, int bottom);
int BN_pseudo_rand(BIGNUM *rnd, int bits, int top, int bottom);
int BN_rand_range(BIGNUM *rnd, BIGNUM *range);
int BN_pseudo_rand_range(BIGNUM *rnd, BIGNUM *range);
=head1 DESCRIPTION
BN_rand() generates a cryptographically strong pseudo-random number of
B<bits> in length and stores it in B<rnd>. If B<top> is -1, the
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. 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
non-cryptographic purposes and for certain purposes in cryptographic
protocols, but usually not for key generation etc.
BN_rand_range() generates a cryptographically strong pseudo-random
number B<rnd> in the range 0 E<lt>= B<rnd> E<lt> B<range>.
BN_pseudo_rand_range() does the same, but is based on BN_pseudo_rand(),
and hence numbers generated by it are not necessarily unpredictable.
The PRNG must be seeded prior to calling BN_rand() or BN_rand_range().
=head1 RETURN VALUES
The functions return 1 on success, 0 on error.
The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
=head1 SEE ALSO
L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>,
L<RAND_add(3)|RAND_add(3)>, L<RAND_bytes(3)|RAND_bytes(3)>
=head1 HISTORY
BN_rand() is available in all versions of SSLeay and OpenSSL.
BN_pseudo_rand() was added in OpenSSL 0.9.5. The B<top> == -1 case
and the function BN_rand_range() were added in OpenSSL 0.9.6a.
BN_pseudo_rand_range() was added in OpenSSL 0.9.6c.
=cut

66
openssl-1.0.2f/doc/crypto/BN_set_bit.pod Normal file
View File

@@ -0,0 +1,66 @@
=pod
=head1 NAME
BN_set_bit, BN_clear_bit, BN_is_bit_set, BN_mask_bits, BN_lshift,
BN_lshift1, BN_rshift, BN_rshift1 - bit operations on BIGNUMs
=head1 SYNOPSIS
#include <openssl/bn.h>
int BN_set_bit(BIGNUM *a, int n);
int BN_clear_bit(BIGNUM *a, int n);
int BN_is_bit_set(const BIGNUM *a, int n);
int BN_mask_bits(BIGNUM *a, int n);
int BN_lshift(BIGNUM *r, const BIGNUM *a, int n);
int BN_lshift1(BIGNUM *r, BIGNUM *a);
int BN_rshift(BIGNUM *r, BIGNUM *a, int n);
int BN_rshift1(BIGNUM *r, BIGNUM *a);
=head1 DESCRIPTION
BN_set_bit() sets bit B<n> in B<a> to 1 (C<a|=(1E<lt>E<lt>n)>). The
number is expanded if necessary.
BN_clear_bit() sets bit B<n> in B<a> to 0 (C<a&=~(1E<lt>E<lt>n)>). An
error occurs if B<a> is shorter than B<n> bits.
BN_is_bit_set() tests if bit B<n> in B<a> is set.
BN_mask_bits() truncates B<a> to an B<n> bit number
(C<a&=~((~0)E<gt>E<gt>n)>). An error occurs if B<a> already is
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>). 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>). 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.
=head1 RETURN VALUES
BN_is_bit_set() returns 1 if the bit is set, 0 otherwise.
All other functions return 1 for success, 0 on error. The error codes
can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
=head1 SEE ALSO
L<bn(3)|bn(3)>, L<BN_num_bytes(3)|BN_num_bytes(3)>, L<BN_add(3)|BN_add(3)>
=head1 HISTORY
BN_set_bit(), BN_clear_bit(), BN_is_bit_set(), BN_mask_bits(),
BN_lshift(), BN_lshift1(), BN_rshift(), and BN_rshift1() are available
in all versions of SSLeay and OpenSSL.
=cut

23
openssl-1.0.2f/doc/crypto/BN_swap.pod Normal file
View File

@@ -0,0 +1,23 @@
=pod
=head1 NAME
BN_swap - exchange BIGNUMs
=head1 SYNOPSIS
#include <openssl/bn.h>
void BN_swap(BIGNUM *a, BIGNUM *b);
=head1 DESCRIPTION
BN_swap() exchanges the values of I<a> and I<b>.
L<bn(3)|bn(3)>
=head1 HISTORY
BN_swap was added in OpenSSL 0.9.7.
=cut

59
openssl-1.0.2f/doc/crypto/BN_zero.pod Normal file
View File

@@ -0,0 +1,59 @@
=pod
=head1 NAME
BN_zero, BN_one, BN_value_one, BN_set_word, BN_get_word - BIGNUM assignment
operations
=head1 SYNOPSIS
#include <openssl/bn.h>
int BN_zero(BIGNUM *a);
int BN_one(BIGNUM *a);
const BIGNUM *BN_value_one(void);
int BN_set_word(BIGNUM *a, unsigned long w);
unsigned long BN_get_word(BIGNUM *a);
=head1 DESCRIPTION
BN_zero(), BN_one() and BN_set_word() set B<a> to the values 0, 1 and
B<w> respectively. BN_zero() and BN_one() are macros.
BN_value_one() returns a B<BIGNUM> constant of value 1. This constant
is useful for use in comparisons and assignment.
BN_get_word() returns B<a>, if it can be represented as an unsigned
long.
=head1 RETURN VALUES
BN_get_word() returns the value B<a>, and 0xffffffffL if B<a> cannot
be represented as an unsigned long.
BN_zero(), BN_one() and BN_set_word() return 1 on success, 0 otherwise.
BN_value_one() returns the constant.
=head1 BUGS
Someone might change the constant.
If a B<BIGNUM> is equal to 0xffffffffL it can be represented as an
unsigned long but this value is also returned on error.
=head1 SEE ALSO
L<bn(3)|bn(3)>, L<BN_bn2bin(3)|BN_bn2bin(3)>
=head1 HISTORY
BN_zero(), BN_one() and BN_set_word() are available in all versions of
SSLeay and OpenSSL. BN_value_one() and BN_get_word() were added in
SSLeay 0.8.
BN_value_one() was changed to return a true const BIGNUM * in OpenSSL
0.9.7.
=cut

66
openssl-1.0.2f/doc/crypto/CMS_add0_cert.pod Normal file
View File

@@ -0,0 +1,66 @@
=pod
=head1 NAME
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
#include <openssl/cms.h>
int CMS_add0_cert(CMS_ContentInfo *cms, X509 *cert);
int CMS_add1_cert(CMS_ContentInfo *cms, X509 *cert);
STACK_OF(X509) *CMS_get1_certs(CMS_ContentInfo *cms);
int CMS_add0_crl(CMS_ContentInfo *cms, X509_CRL *crl);
int CMS_add1_crl(CMS_ContentInfo *cms, X509_CRL *crl);
STACK_OF(X509_CRL) *CMS_get1_crls(CMS_ContentInfo *cms);
=head1 DESCRIPTION
CMS_add0_cert() and CMS_add1_cert() add certificate B<cert> to B<cms>.
must be of type signed data or enveloped data.
CMS_get1_certs() returns all certificates in B<cms>.
CMS_add0_crl() and CMS_add1_crl() add CRL B<crl> to B<cms>. CMS_get1_crls()
returns any CRLs in B<cms>.
=head1 NOTES
The CMS_ContentInfo structure B<cms> must be of type signed data or enveloped
data or an error will be returned.
For signed data certificates and CRLs are added to the B<certificates> and
B<crls> fields of SignedData structure. For enveloped data they are added to
B<OriginatorInfo>.
As the B<0> implies CMS_add0_cert() adds B<cert> internally to B<cms> and it
must not be freed up after the call as opposed to CMS_add1_cert() where B<cert>
must be freed up.
The same certificate or CRL must not be added to the same cms structure more
than once.
=head1 RETURN VALUES
CMS_add0_cert(), CMS_add1_cert() and CMS_add0_crl() and CMS_add1_crl() return
1 for success and 0 for failure.
CMS_get1_certs() and CMS_get1_crls() return the STACK of certificates or CRLs
or NULL if there are none or an error occurs. The only error which will occur
in practice is if the B<cms> type is invalid.
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>,
L<CMS_sign(3)|CMS_sign(3)>,
L<CMS_encrypt(3)|CMS_encrypt(3)>
=head1 HISTORY
CMS_add0_cert(), CMS_add1_cert(), CMS_get1_certs(), CMS_add0_crl()
and CMS_get1_crls() were all first added to OpenSSL 0.9.8
=cut

62
openssl-1.0.2f/doc/crypto/CMS_add1_recipient_cert.pod Normal file
View File

@@ -0,0 +1,62 @@
=pod
=head1 NAME
CMS_add1_recipient_cert, CMS_add0_recipient_key - add recipients to a CMS enveloped data structure
=head1 SYNOPSIS
#include <openssl/cms.h>
CMS_RecipientInfo *CMS_add1_recipient_cert(CMS_ContentInfo *cms, X509 *recip, unsigned int flags);
CMS_RecipientInfo *CMS_add0_recipient_key(CMS_ContentInfo *cms, int nid, unsigned char *key, size_t keylen, unsigned char *id, size_t idlen, ASN1_GENERALIZEDTIME *date, ASN1_OBJECT *otherTypeId, ASN1_TYPE *otherType);
=head1 DESCRIPTION
CMS_add1_recipient_cert() adds recipient B<recip> to CMS_ContentInfo enveloped
data structure B<cms> as a KeyTransRecipientInfo structure.
CMS_add0_recipient_key() adds symmetric key B<key> of length B<keylen> using
wrapping algorithm B<nid>, identifier B<id> of length B<idlen> and optional
values B<date>, B<otherTypeId> and B<otherType> to CMS_ContentInfo enveloped
data structure B<cms> as a KEKRecipientInfo structure.
The CMS_ContentInfo structure should be obtained from an initial call to
CMS_encrypt() with the flag B<CMS_PARTIAL> set.
=head1 NOTES
The main purpose of this function is to provide finer control over a CMS
enveloped data structure where the simpler CMS_encrypt() function defaults are
not appropriate. For example if one or more KEKRecipientInfo structures
need to be added. New attributes can also be added using the returned
CMS_RecipientInfo structure and the CMS attribute utility functions.
OpenSSL will by default identify recipient 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 all recipient certificates do not
have a subject key identifier extension.
Currently only AES based key wrapping algorithms are supported for B<nid>,
specifically: NID_id_aes128_wrap, NID_id_aes192_wrap and NID_id_aes256_wrap.
If B<nid> is set to B<NID_undef> then an AES wrap algorithm will be used
consistent with B<keylen>.
=head1 RETURN VALUES
CMS_add1_recipient_cert() and CMS_add0_recipient_key() return an internal
pointer to the CMS_RecipientInfo structure just added or NULL if an error
occurs.
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_decrypt(3)|CMS_decrypt(3)>,
L<CMS_final(3)|CMS_final(3)>,
=head1 HISTORY
CMS_add1_recipient_cert() and CMS_add0_recipient_key() were added to OpenSSL
0.9.8
=cut

101
openssl-1.0.2f/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

73
openssl-1.0.2f/doc/crypto/CMS_compress.pod Normal file
View File

@@ -0,0 +1,73 @@
=pod
=head1 NAME
CMS_compress - create a CMS CompressedData structure
=head1 SYNOPSIS
#include <openssl/cms.h>
CMS_ContentInfo *CMS_compress(BIO *in, int comp_nid, unsigned int flags);
=head1 DESCRIPTION
CMS_compress() creates and returns a CMS CompressedData structure. B<comp_nid>
is the compression algorithm to use or B<NID_undef> to use the default
algorithm (zlib compression). B<in> is the content to be compressed.
B<flags> is an optional set of flags.
=head1 NOTES
The only currently supported compression algorithm is zlib using the NID
NID_zlib_compression.
If zlib support is not compiled into OpenSSL then CMS_compress() will return
an error.
If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are
prepended to the data.
Normally the supplied content is translated into MIME canonical format (as
required by the S/MIME specifications) if B<CMS_BINARY> is set no translation
occurs. This option should be used if the supplied data is in binary format
otherwise the translation will corrupt it. If B<CMS_BINARY> is set then
B<CMS_TEXT> is ignored.
If the B<CMS_STREAM> flag is set a partial B<CMS_ContentInfo> structure is
returned suitable for streaming I/O: no data is read from the BIO B<in>.
The compressed data is included in the CMS_ContentInfo structure, unless
B<CMS_DETACHED> is set in which case it is omitted. This is rarely used in
practice and is not supported by SMIME_write_CMS().
=head1 NOTES
If the flag B<CMS_STREAM> is set the returned B<CMS_ContentInfo> structure is
B<not> complete and outputting its contents via a function that does not
properly finalize the B<CMS_ContentInfo> structure will give unpredictable
results.
Several functions including SMIME_write_CMS(), i2d_CMS_bio_stream(),
PEM_write_bio_CMS_stream() finalize the structure. Alternatively finalization
can be performed by obtaining the streaming ASN1 B<BIO> directly using
BIO_new_CMS().
Additional compression parameters such as the zlib compression level cannot
currently be set.
=head1 RETURN VALUES
CMS_compress() returns either a CMS_ContentInfo structure or NULL if an error
occurred. The error can be obtained from ERR_get_error(3).
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_uncompress(3)|CMS_uncompress(3)>
=head1 HISTORY
CMS_compress() was added to OpenSSL 0.9.8
The B<CMS_STREAM> flag was first supported in OpenSSL 1.0.0.
=cut

79
openssl-1.0.2f/doc/crypto/CMS_decrypt.pod Normal file
View File

@@ -0,0 +1,79 @@
=pod
=head1 NAME
CMS_decrypt - decrypt content from a CMS envelopedData structure
=head1 SYNOPSIS
#include <openssl/cms.h>
int CMS_decrypt(CMS_ContentInfo *cms, EVP_PKEY *pkey, X509 *cert, BIO *dcont, BIO *out, unsigned int flags);
=head1 DESCRIPTION
CMS_decrypt() extracts and decrypts the content from a CMS EnvelopedData
structure. B<pkey> is the private key of the recipient, B<cert> is the
recipient's certificate, B<out> is a BIO to write the content to and
B<flags> is an optional set of flags.
The B<dcont> parameter is used in the rare case where the encrypted content
is detached. It will normally be set to NULL.
=head1 NOTES
OpenSSL_add_all_algorithms() (or equivalent) should be called before using this
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. 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
in advance using the CMS utility functions such as CMS_set1_pkey(). In this
case both B<cert> and B<pkey> should be set to NULL.
To process KEKRecipientInfo types CMS_set1_key() or CMS_RecipientInfo_set0_key()
and CMS_ReceipientInfo_decrypt() should be called before CMS_decrypt() and
B<cert> and B<pkey> set to NULL.
The following flags can be passed in the B<flags> parameter.
If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are deleted
from the content. If the content is not of type B<text/plain> then an error is
returned.
=head1 RETURN VALUES
CMS_decrypt() returns either 1 for success or 0 for failure.
The error can be obtained from ERR_get_error(3)
=head1 BUGS
The lack of single pass processing and the need to hold all data in memory as
mentioned in CMS_verify() also applies to CMS_decrypt().
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_encrypt(3)|CMS_encrypt(3)>
=head1 HISTORY
CMS_decrypt() was added to OpenSSL 0.9.8
=cut

96
openssl-1.0.2f/doc/crypto/CMS_encrypt.pod Normal file
View File

@@ -0,0 +1,96 @@
=pod
=head1 NAME
CMS_encrypt - create a CMS envelopedData structure
=head1 SYNOPSIS
#include <openssl/cms.h>
CMS_ContentInfo *CMS_encrypt(STACK_OF(X509) *certs, BIO *in, const EVP_CIPHER *cipher, unsigned int flags);
=head1 DESCRIPTION
CMS_encrypt() creates and returns a CMS EnvelopedData structure. B<certs>
is a list of recipient certificates. B<in> is the content to be encrypted.
B<cipher> is the symmetric cipher to use. B<flags> is an optional set of flags.
=head1 NOTES
Only certificates carrying RSA keys are supported so the recipient certificates
supplied to this function must all contain RSA public keys, though they do not
have to be signed using the RSA algorithm.
EVP_des_ede3_cbc() (triple DES) is the algorithm of choice for S/MIME use
because most clients will support it.
The algorithm passed in the B<cipher> parameter must support ASN1 encoding of
its parameters.
Many browsers implement a "sign and encrypt" option which is simply an S/MIME
envelopedData containing an S/MIME signed message. This can be readily produced
by storing the S/MIME signed message in a memory BIO and passing it to
CMS_encrypt().
The following flags can be passed in the B<flags> parameter.
If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are
prepended to the data.
Normally the supplied content is translated into MIME canonical format (as
required by the S/MIME specifications) if B<CMS_BINARY> is set no translation
occurs. This option should be used if the supplied data is in binary format
otherwise the translation will corrupt it. If B<CMS_BINARY> is set then
B<CMS_TEXT> is ignored.
OpenSSL will by default identify recipient 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 all recipient certificates do not
have a subject key identifier extension.
If the B<CMS_STREAM> flag is set a partial B<CMS_ContentInfo> structure is
returned suitable for streaming I/O: no data is read from the BIO B<in>.
If the B<CMS_PARTIAL> flag is set a partial B<CMS_ContentInfo> structure is
returned to which additional recipients and attributes can be added before
finalization.
The data being encrypted is included in the CMS_ContentInfo structure, unless
B<CMS_DETACHED> is set in which case it is omitted. This is rarely used in
practice and is not supported by SMIME_write_CMS().
=head1 NOTES
If the flag B<CMS_STREAM> is set the returned B<CMS_ContentInfo> structure is
B<not> complete and outputting its contents via a function that does not
properly finalize the B<CMS_ContentInfo> structure will give unpredictable
results.
Several functions including SMIME_write_CMS(), i2d_CMS_bio_stream(),
PEM_write_bio_CMS_stream() finalize the structure. Alternatively finalization
can be performed by obtaining the streaming ASN1 B<BIO> directly using
BIO_new_CMS().
The recipients specified in B<certs> use a CMS KeyTransRecipientInfo info
structure. KEKRecipientInfo is also supported using the flag B<CMS_PARTIAL>
and CMS_add0_recipient_key().
The parameter B<certs> may be NULL if B<CMS_PARTIAL> is set and recipients
added later using CMS_add1_recipient_cert() or CMS_add0_recipient_key().
=head1 RETURN VALUES
CMS_encrypt() returns either a CMS_ContentInfo structure or NULL if an error
occurred. The error can be obtained from ERR_get_error(3).
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_decrypt(3)|CMS_decrypt(3)>
=head1 HISTORY
CMS_decrypt() was added to OpenSSL 0.9.8
The B<CMS_STREAM> flag was first supported in OpenSSL 1.0.0.
=cut

41
openssl-1.0.2f/doc/crypto/CMS_final.pod Normal file
View File

@@ -0,0 +1,41 @@
=pod
=head1 NAME
CMS_final - finalise a CMS_ContentInfo structure
=head1 SYNOPSIS
#include <openssl/cms.h>
int CMS_final(CMS_ContentInfo *cms, BIO *data, BIO *dcont, unsigned int flags);
=head1 DESCRIPTION
CMS_final() finalises the structure B<cms>. It's purpose is to perform any
operations necessary on B<cms> (digest computation for example) and set the
appropriate fields. The parameter B<data> contains the content to be
processed. The B<dcont> parameter contains a BIO to write content to after
processing: this is only used with detached data and will usually be set to
NULL.
=head1 NOTES
This function will normally be called when the B<CMS_PARTIAL> flag is used. It
should only be used when streaming is not performed because the streaming
I/O functions perform finalisation operations internally.
=head1 RETURN VALUES
CMS_final() returns 1 for success or 0 for failure.
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>,
L<CMS_encrypt(3)|CMS_encrypt(3)>
=head1 HISTORY
CMS_final() was added to OpenSSL 0.9.8
=cut

120
openssl-1.0.2f/doc/crypto/CMS_get0_RecipientInfos.pod Normal file
View File

@@ -0,0 +1,120 @@
=pod
=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_RecipientInfo_encrypt - CMS envelopedData RecipientInfo routines
=head1 SYNOPSIS
#include <openssl/cms.h>
STACK_OF(CMS_RecipientInfo) *CMS_get0_RecipientInfos(CMS_ContentInfo *cms);
int CMS_RecipientInfo_type(CMS_RecipientInfo *ri);
int CMS_RecipientInfo_ktri_get0_signer_id(CMS_RecipientInfo *ri, ASN1_OCTET_STRING **keyid, X509_NAME **issuer, ASN1_INTEGER **sno);
int CMS_RecipientInfo_ktri_cert_cmp(CMS_RecipientInfo *ri, X509 *cert);
int CMS_RecipientInfo_set0_pkey(CMS_RecipientInfo *ri, EVP_PKEY *pkey);
int CMS_RecipientInfo_kekri_get0_id(CMS_RecipientInfo *ri, X509_ALGOR **palg, ASN1_OCTET_STRING **pid, ASN1_GENERALIZEDTIME **pdate, ASN1_OBJECT **potherid, ASN1_TYPE **pothertype);
int CMS_RecipientInfo_kekri_id_cmp(CMS_RecipientInfo *ri, const unsigned char *id, size_t idlen);
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
The function CMS_get0_RecipientInfos() returns all the CMS_RecipientInfo
structures associated with a CMS EnvelopedData structure.
CMS_RecipientInfo_type() returns the type of CMS_RecipientInfo structure B<ri>.
It will currently return CMS_RECIPINFO_TRANS, CMS_RECIPINFO_AGREE,
CMS_RECIPINFO_KEK, CMS_RECIPINFO_PASS, or CMS_RECIPINFO_OTHER.
CMS_RecipientInfo_ktri_get0_signer_id() retrieves the certificate recipient
identifier associated with a specific CMS_RecipientInfo structure B<ri>, which
must be of type CMS_RECIPINFO_TRANS. Either the keyidentifier will be set in
B<keyid> or B<both> issuer name and serial number in B<issuer> and B<sno>.
CMS_RecipientInfo_ktri_cert_cmp() compares the certificate B<cert> against the
CMS_RecipientInfo structure B<ri>, which must be of type CMS_RECIPINFO_TRANS.
It returns zero if the comparison is successful and non zero if not.
CMS_RecipientInfo_set0_pkey() associates the private key B<pkey> with
the CMS_RecipientInfo structure B<ri>, which must be of type
CMS_RECIPINFO_TRANS.
CMS_RecipientInfo_kekri_get0_id() retrieves the key information from the
CMS_RecipientInfo structure B<ri> which must be of type CMS_RECIPINFO_KEK. Any
of the remaining parameters can be NULL if the application is not interested in
the value of a field. Where a field is optional and absent NULL will be written
to the corresponding parameter. The keyEncryptionAlgorithm field is written to
B<palg>, the B<keyIdentifier> field is written to B<pid>, the B<date> field if
present is written to B<pdate>, if the B<other> field is present the components
B<keyAttrId> and B<keyAttr> are written to parameters B<potherid> and
B<pothertype>.
CMS_RecipientInfo_kekri_id_cmp() compares the ID in the B<id> and B<idlen>
parameters against the B<keyIdentifier> CMS_RecipientInfo structure B<ri>,
which must be of type CMS_RECIPINFO_KEK. It returns zero if the comparison is
successful and non zero if not.
CMS_RecipientInfo_set0_key() associates the symmetric key B<key> of length
B<keylen> with the CMS_RecipientInfo structure B<ri>, which must be of type
CMS_RECIPINFO_KEK.
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
recipient keys using any appropriate technique when the simpler method
of CMS_decrypt() is not appropriate.
In typical usage and application will retrieve all CMS_RecipientInfo structures
using CMS_get0_RecipientInfos() and check the type of each using
CMS_RecpientInfo_type(). Depending on the type the CMS_RecipientInfo structure
can be ignored or its key identifier data retrieved using an appropriate
function. Then if the corresponding secret or private key can be obtained by
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
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.
Any error can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>.
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_decrypt(3)|CMS_decrypt(3)>
=head1 HISTORY
These functions were first was added to OpenSSL 0.9.8
=cut

81
openssl-1.0.2f/doc/crypto/CMS_get0_SignerInfos.pod Normal file
View File

@@ -0,0 +1,81 @@
=pod
=head1 NAME
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
#include <openssl/cms.h>
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);
=head1 DESCRIPTION
The function CMS_get0_SignerInfos() returns all the CMS_SignerInfo structures
associated with a CMS signedData structure.
CMS_SignerInfo_get0_signer_id() retrieves the certificate signer identifier
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.
CMS_SignerInfo_set1_signer_cert() sets the signers certificate of B<si> to
B<signer>.
=head1 NOTES
The main purpose of these functions is to enable an application to lookup
signers certificates using any appropriate technique when the simpler method
of CMS_verify() is not appropriate.
In typical usage and application will retrieve all CMS_SignerInfo structures
using CMS_get0_SignerInfo() and retrieve the identifier information using
CMS. It will then obtain the signer certificate by some unspecified means
(or return and error if it cannot be found) and set it using
CMS_SignerInfo_set1_signer_cert().
Once all signer certificates have been set CMS_verify() can be used.
Although CMS_get0_SignerInfos() can return NULL is an error occur B<or> if
there are no signers this is not a problem in practice because the only
error which can occur is if the B<cms> structure is not of type signedData
due to application error.
=head1 RETURN VALUES
CMS_get0_SignerInfos() returns all CMS_SignerInfo structures, or NULL there
are no signers or an error occurs.
CMS_SignerInfo_get0_signer_id() returns 1 for success and 0 for failure.
CMS_SignerInfo_cert_cmp() returns 0 for a successful comparison and non
zero otherwise.
CMS_SignerInfo_set1_signer_cert() does not return a value.
Any error can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_verify(3)|CMS_verify(3)>
=head1 HISTORY
These functions were first was added to OpenSSL 0.9.8
=cut

77
openssl-1.0.2f/doc/crypto/CMS_get0_type.pod Normal file
View File

@@ -0,0 +1,77 @@
=pod
=head1 NAME
CMS_get0_type, CMS_set1_eContentType, CMS_get0_eContentType, CMS_get0_content - get and set CMS content types and content
=head1 SYNOPSIS
#include <openssl/cms.h>
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
CMS_get0_type() returns the content type of a CMS_ContentInfo structure as
and ASN1_OBJECT pointer. An application can then decide how to process the
CMS_ContentInfo structure based on this value.
CMS_set1_eContentType() sets the embedded content type of a CMS_ContentInfo
structure. It should be called with CMS functions with the B<CMS_PARTIAL>
flag and B<before> the structure is finalised, otherwise the results are
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(), 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
values are returned:
NID_pkcs7_data
NID_pkcs7_signed
NID_pkcs7_digest
NID_id_smime_ct_compressedData:
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
CMS_get0_type() and CMS_get0_eContentType() return and ASN1_OBJECT structure.
CMS_set1_eContentType() returns 1 for success or 0 if an error occurred. The
error can be obtained from ERR_get_error(3).
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>
=head1 HISTORY
CMS_get0_type(), CMS_set1_eContentType() and CMS_get0_eContentType() were all
first added to OpenSSL 0.9.8
=cut

69
openssl-1.0.2f/doc/crypto/CMS_get1_ReceiptRequest.pod Normal file
View File

@@ -0,0 +1,69 @@
=pod
=head1 NAME
CMS_ReceiptRequest_create0, CMS_add1_ReceiptRequest, CMS_get1_ReceiptRequest, CMS_ReceiptRequest_get0_values - CMS signed receipt request functions.
=head1 SYNOPSIS
#include <openssl/cms.h>
CMS_ReceiptRequest *CMS_ReceiptRequest_create0(unsigned char *id, int idlen, int allorfirst, STACK_OF(GENERAL_NAMES) *receiptList, STACK_OF(GENERAL_NAMES) *receiptsTo);
int CMS_add1_ReceiptRequest(CMS_SignerInfo *si, CMS_ReceiptRequest *rr);
int CMS_get1_ReceiptRequest(CMS_SignerInfo *si, CMS_ReceiptRequest **prr);
void CMS_ReceiptRequest_get0_values(CMS_ReceiptRequest *rr, ASN1_STRING **pcid, int *pallorfirst, STACK_OF(GENERAL_NAMES) **plist, STACK_OF(GENERAL_NAMES) **prto);
=head1 DESCRIPTION
CMS_ReceiptRequest_create0() creates a signed receipt request structure. The
B<signedContentIdentifier> field is set using B<id> and B<idlen>, or it is set
to 32 bytes of pseudo random data if B<id> is NULL. If B<receiptList> is NULL
the allOrFirstTier option in B<receiptsFrom> is used and set to the value of
the B<allorfirst> parameter. If B<receiptList> is not NULL the B<receiptList>
option in B<receiptsFrom> is used. The B<receiptsTo> parameter specifies the
B<receiptsTo> field value.
The CMS_add1_ReceiptRequest() function adds a signed receipt request B<rr>
to SignerInfo structure B<si>.
int CMS_get1_ReceiptRequest() looks for a signed receipt request in B<si>, if
any is found it is decoded and written to B<prr>.
CMS_ReceiptRequest_get0_values() retrieves the values of a receipt request.
The signedContentIdentifier is copied to B<pcid>. If the B<allOrFirstTier>
option of B<receiptsFrom> is used its value is copied to B<pallorfirst>
otherwise the B<receiptList> field is copied to B<plist>. The B<receiptsTo>
parameter is copied to B<prto>.
=head1 NOTES
For more details of the meaning of the fields see RFC2634.
The contents of a signed receipt should only be considered meaningful if the
corresponding CMS_ContentInfo structure can be successfully verified using
CMS_verify().
=head1 RETURN VALUES
CMS_ReceiptRequest_create0() returns a signed receipt request structure or
NULL if an error occurred.
CMS_add1_ReceiptRequest() returns 1 for success or 0 is an error occurred.
CMS_get1_ReceiptRequest() returns 1 is a signed receipt request is found and
decoded. It returns 0 if a signed receipt request is not present and -1 if
it is present but malformed.
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>,
L<CMS_sign_receipt(3)|CMS_sign_receipt(3)>, L<CMS_verify(3)|CMS_verify(3)>
L<CMS_verify_receipt(3)|CMS_verify_receipt(3)>
=head1 HISTORY
CMS_ReceiptRequest_create0(), CMS_add1_ReceiptRequest(),
CMS_get1_ReceiptRequest() and CMS_ReceiptRequest_get0_values() were added to
OpenSSL 0.9.8
=cut

121
openssl-1.0.2f/doc/crypto/CMS_sign.pod Normal file
View File

@@ -0,0 +1,121 @@
=pod
=head1 NAME
CMS_sign - create a CMS SignedData structure
=head1 SYNOPSIS
#include <openssl/cms.h>
CMS_ContentInfo *CMS_sign(X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs, BIO *data, unsigned int flags);
=head1 DESCRIPTION
CMS_sign() creates and returns a CMS SignedData structure. B<signcert> is
the certificate to sign with, B<pkey> is the corresponding private key.
B<certs> is an optional additional set of certificates to include in the CMS
structure (for example any intermediate CAs in the chain). Any or all of
these parameters can be B<NULL>, see B<NOTES> below.
The data to be signed is read from BIO B<data>.
B<flags> is an optional set of flags.
=head1 NOTES
Any of the following flags (ored together) can be passed in the B<flags>
parameter.
Many S/MIME clients expect the signed content to include valid MIME headers. If
the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are prepended
to the data.
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 data being signed is included in the CMS_ContentInfo structure, unless
B<CMS_DETACHED> is set in which case it is omitted. This is used for
CMS_ContentInfo detached signatures which are used in S/MIME plaintext signed
messages for example.
Normally the supplied content is translated into MIME canonical format (as
required by the S/MIME specifications) if B<CMS_BINARY> is set no translation
occurs. This option should be used if the supplied data is in binary format
otherwise the translation will corrupt it.
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.
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.
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 the flags B<CMS_STREAM> is set then the returned B<CMS_ContentInfo>
structure is just initialized ready to perform the signing operation. The
signing is however B<not> performed and the data to be signed is not read from
the B<data> parameter. Signing is deferred until after the data has been
written. In this way data can be signed in a single pass.
If the B<CMS_PARTIAL> flag is set a partial B<CMS_ContentInfo> structure is
output to which additional signers and capabilities can be added before
finalization.
If the flag B<CMS_STREAM> is set the returned B<CMS_ContentInfo> structure is
B<not> complete and outputting its contents via a function that does not
properly finalize the B<CMS_ContentInfo> structure will give unpredictable
results.
Several functions including SMIME_write_CMS(), i2d_CMS_bio_stream(),
PEM_write_bio_CMS_stream() finalize the structure. Alternatively finalization
can be performed by obtaining the streaming ASN1 B<BIO> directly using
BIO_new_CMS().
If a signer is specified it will use the default digest for the signing
algorithm. This is B<SHA1> for both RSA and DSA keys.
If B<signcert> and B<pkey> are NULL then a certificates only CMS structure is
output.
The function CMS_sign() is a basic CMS signing function whose output will be
suitable for many purposes. For finer control of the output format the
B<certs>, B<signcert> and B<pkey> parameters can all be B<NULL> and the
B<CMS_PARTIAL> flag set. Then one or more signers can be added using the
function CMS_sign_add1_signer(), non default digests can be used and custom
attributes added. B<CMS_final()> must then be called to finalize the
structure if streaming is not enabled.
=head1 BUGS
Some attributes such as counter signatures are not supported.
=head1 RETURN VALUES
CMS_sign() returns either a valid CMS_ContentInfo structure or NULL if an error
occurred. The error can be obtained from ERR_get_error(3).
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_verify(3)|CMS_verify(3)>
=head1 HISTORY
CMS_sign() was added to OpenSSL 0.9.8
The B<CMS_STREAM> flag is only supported for detached data in OpenSSL 0.9.8,
it is supported for embedded data in OpenSSL 1.0.0 and later.
=cut

45
openssl-1.0.2f/doc/crypto/CMS_sign_receipt.pod Normal file
View File

@@ -0,0 +1,45 @@
=pod
=head1 NAME
CMS_sign_receipt - create a CMS signed receipt
=head1 SYNOPSIS
#include <openssl/cms.h>
CMS_ContentInfo *CMS_sign_receipt(CMS_SignerInfo *si, X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs, unsigned int flags);
=head1 DESCRIPTION
CMS_sign_receipt() creates and returns a CMS signed receipt structure. B<si> is
the B<CMS_SignerInfo> structure containing the signed receipt request.
B<signcert> is the certificate to sign with, B<pkey> is the corresponding
private key. B<certs> is an optional additional set of certificates to include
in the CMS structure (for example any intermediate CAs in the chain).
B<flags> is an optional set of flags.
=head1 NOTES
This functions behaves in a similar way to CMS_sign() except the flag values
B<CMS_DETACHED>, B<CMS_BINARY>, B<CMS_NOATTR>, B<CMS_TEXT> and B<CMS_STREAM>
are not supported since they do not make sense in the context of signed
receipts.
=head1 RETURN VALUES
CMS_sign_receipt() returns either a valid CMS_ContentInfo structure or NULL if
an error occurred. The error can be obtained from ERR_get_error(3).
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>,
L<CMS_verify_receipt(3)|CMS_verify_receipt(3)>,
L<CMS_sign(3)|CMS_sign(3)>
=head1 HISTORY
CMS_sign_receipt() was added to OpenSSL 0.9.8
=cut

54
openssl-1.0.2f/doc/crypto/CMS_uncompress.pod Normal file
View File

@@ -0,0 +1,54 @@
=pod
=head1 NAME
CMS_uncompress - uncompress a CMS CompressedData structure
=head1 SYNOPSIS
#include <openssl/cms.h>
int CMS_uncompress(CMS_ContentInfo *cms, BIO *dcont, BIO *out, unsigned int flags);
=head1 DESCRIPTION
CMS_uncompress() extracts and uncompresses the content from a CMS
CompressedData structure B<cms>. B<data> is a BIO to write the content to and
B<flags> is an optional set of flags.
The B<dcont> parameter is used in the rare case where the compressed content
is detached. It will normally be set to NULL.
=head1 NOTES
The only currently supported compression algorithm is zlib: if the structure
indicates the use of any other algorithm an error is returned.
If zlib support is not compiled into OpenSSL then CMS_uncompress() will always
return an error.
The following flags can be passed in the B<flags> parameter.
If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are deleted
from the content. If the content is not of type B<text/plain> then an error is
returned.
=head1 RETURN VALUES
CMS_uncompress() returns either 1 for success or 0 for failure. The error can
be obtained from ERR_get_error(3)
=head1 BUGS
The lack of single pass processing and the need to hold all data in memory as
mentioned in CMS_verify() also applies to CMS_decompress().
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_compress(3)|CMS_compress(3)>
=head1 HISTORY
CMS_uncompress() was added to OpenSSL 0.9.8
=cut

126
openssl-1.0.2f/doc/crypto/CMS_verify.pod Normal file
View File

@@ -0,0 +1,126 @@
=pod
=head1 NAME
CMS_verify, CMS_get0_signers - verify a CMS SignedData structure
=head1 SYNOPSIS
#include <openssl/cms.h>
int CMS_verify(CMS_ContentInfo *cms, STACK_OF(X509) *certs, X509_STORE *store, BIO *indata, BIO *out, unsigned int flags);
STACK_OF(X509) *CMS_get0_signers(CMS_ContentInfo *cms);
=head1 DESCRIPTION
CMS_verify() verifies a CMS SignedData structure. B<cms> is the CMS_ContentInfo
structure to verify. B<certs> is a set of certificates in which to search for
the signing certificate(s). B<store> is a trusted certificate store used for
chain verification. B<indata> is the detached content if the content is not
present in B<cms>. The content is written to B<out> if it is not NULL.
B<flags> is an optional set of flags, which can be used to modify the verify
operation.
CMS_get0_signers() retrieves the signing certificate(s) from B<cms>, it must
be called after a successful CMS_verify() operation.
=head1 VERIFY PROCESS
Normally the verify process proceeds as follows.
Initially some sanity checks are performed on B<cms>. The type of B<cms> must
be SignedData. There must be at least one signature on the data and if
the content is detached B<indata> cannot be B<NULL>.
An attempt is made to locate all the signing certificate(s), first looking in
the B<certs> parameter (if it is not NULL) and then looking in any
certificates contained in the B<cms> structure itself. If any signing
certificate cannot be located the operation fails.
Each signing certificate is chain verified using the B<smimesign> purpose and
the supplied trusted certificate store. Any internal certificates in the message
are used as untrusted CAs. If CRL checking is enabled in B<store> any internal
CRLs are used in addition to attempting to look them up in B<store>. If any
chain verify fails an error code is returned.
Finally the signed content is read (and written to B<out> is it is not NULL)
and the signature's checked.
If all signature's verify correctly then the function is successful.
Any of the following flags (ored together) can be passed in the B<flags>
parameter to change the default verify behaviour.
If B<CMS_NOINTERN> is set the certificates in the message itself are not
searched when locating the signing certificate(s). This means that all the
signing certificates must be in the B<certs> parameter.
If B<CMS_NOCRL> is set and CRL checking is enabled in B<store> then any
CRLs in the message itself are ignored.
If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are deleted
from the content. If the content is not of type B<text/plain> then an error is
returned.
If B<CMS_NO_SIGNER_CERT_VERIFY> is set the signing certificates are not
verified.
If B<CMS_NO_ATTR_VERIFY> is set the signed attributes signature is not
verified.
If B<CMS_NO_CONTENT_VERIFY> is set then the content digest is not checked.
=head1 NOTES
One application of B<CMS_NOINTERN> is to only accept messages signed by
a small number of certificates. The acceptable certificates would be passed
in the B<certs> parameter. In this case if the signer is not one of the
certificates supplied in B<certs> then the verify will fail because the
signer cannot be found.
In some cases the standard techniques for looking up and validating
certificates are not appropriate: for example an application may wish to
lookup certificates in a database or perform customised verification. This
can be achieved by setting and verifying the signers certificates manually
using the signed data utility functions.
Care should be taken when modifying the default verify behaviour, for example
setting B<CMS_NO_CONTENT_VERIFY> will totally disable all content verification
and any modified content will be considered valid. This combination is however
useful if one merely wishes to write the content to B<out> and its validity
is not considered important.
Chain verification should arguably be performed using the signing time rather
than the current time. However since the signing time is supplied by the
signer it cannot be trusted without additional evidence (such as a trusted
timestamp).
=head1 RETURN VALUES
CMS_verify() returns 1 for a successful verification and zero if an error
occurred.
CMS_get0_signers() returns all signers or NULL if an error occurred.
The error can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>
=head1 BUGS
The trusted certificate store is not searched for the signing certificate,
this is primarily due to the inadequacies of the current B<X509_STORE>
functionality.
The lack of single pass processing means that the signed content must all
be held in memory if it is not detached.
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>
=head1 HISTORY
CMS_verify() was added to OpenSSL 0.9.8
=cut

47
openssl-1.0.2f/doc/crypto/CMS_verify_receipt.pod Normal file
View File

@@ -0,0 +1,47 @@
=pod
=head1 NAME
CMS_verify_receipt - verify a CMS signed receipt
=head1 SYNOPSIS
#include <openssl/cms.h>
int CMS_verify_receipt(CMS_ContentInfo *rcms, CMS_ContentInfo *ocms, STACK_OF(X509) *certs, X509_STORE *store, unsigned int flags);
=head1 DESCRIPTION
CMS_verify_receipt() verifies a CMS signed receipt. B<rcms> is the signed
receipt to verify. B<ocms> is the original SignedData structure containing the
receipt request. B<certs> is a set of certificates in which to search for the
signing certificate. B<store> is a trusted certificate store (used for chain
verification).
B<flags> is an optional set of flags, which can be used to modify the verify
operation.
=head1 NOTES
This functions behaves in a similar way to CMS_verify() except the flag values
B<CMS_DETACHED>, B<CMS_BINARY>, B<CMS_TEXT> and B<CMS_STREAM> are not
supported since they do not make sense in the context of signed receipts.
=head1 RETURN VALUES
CMS_verify_receipt() returns 1 for a successful verification and zero if an
error occurred.
The error can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>,
L<CMS_sign_receipt(3)|CMS_sign_receipt(3)>,
L<CMS_verify(3)|CMS_verify(3)>,
=head1 HISTORY
CMS_verify_receipt() was added to OpenSSL 0.9.8
=cut

47
openssl-1.0.2f/doc/crypto/CONF_modules_free.pod Normal file
View File

@@ -0,0 +1,47 @@
=pod
=head1 NAME
CONF_modules_free, CONF_modules_finish, CONF_modules_unload -
OpenSSL configuration cleanup functions
=head1 SYNOPSIS
#include <openssl/conf.h>
void CONF_modules_free(void);
void CONF_modules_finish(void);
void CONF_modules_unload(int all);
=head1 DESCRIPTION
CONF_modules_free() closes down and frees up all memory allocated by all
configuration modules.
CONF_modules_finish() calls each configuration modules B<finish> handler
to free up any configuration that module may have performed.
CONF_modules_unload() finishes and unloads configuration modules. If
B<all> is set to B<0> only modules loaded from DSOs will be unloads. If
B<all> is B<1> all modules, including builtin modules will be unloaded.
=head1 NOTES
Normally applications will only call CONF_modules_free() at application to
tidy up any configuration performed.
=head1 RETURN VALUE
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)>
=head1 HISTORY
CONF_modules_free(), CONF_modules_unload(), and CONF_modules_finish()
first appeared in OpenSSL 0.9.7.
=cut

137
openssl-1.0.2f/doc/crypto/CONF_modules_load_file.pod Normal file
View File

@@ -0,0 +1,137 @@
=pod
=head1 NAME
CONF_modules_load_file, CONF_modules_load - OpenSSL configuration functions
=head1 SYNOPSIS
#include <openssl/conf.h>
int CONF_modules_load_file(const char *filename, const char *appname,
unsigned long flags);
int CONF_modules_load(const CONF *cnf, const char *appname,
unsigned long flags);
=head1 DESCRIPTION
The function CONF_modules_load_file() configures OpenSSL using file
B<filename> and application name B<appname>. If B<filename> is NULL
the standard OpenSSL configuration file is used. If B<appname> is
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
reads configuration information from B<cnf>.
=head1 NOTES
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 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.
If B<CONF_MFLAGS_NO_DSO> is set configuration module loading from DSOs is
disabled.
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.
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
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)>
=head1 HISTORY
CONF_modules_load_file and CONF_modules_load first appeared in OpenSSL 0.9.7.
=cut

53
openssl-1.0.2f/doc/crypto/CRYPTO_set_ex_data.pod Normal file
View File

@@ -0,0 +1,53 @@
=pod
=head1 NAME
CRYPTO_set_ex_data, CRYPTO_get_ex_data - internal application specific data functions
=head1 SYNOPSIS
#include <openssl/crypto.h>
int CRYPTO_set_ex_data(CRYPTO_EX_DATA *r, int idx, void *arg);
void *CRYPTO_get_ex_data(CRYPTO_EX_DATA *r, int idx);
=head1 DESCRIPTION
Several OpenSSL structures can have application specific data attached to them.
These functions are used internally by OpenSSL to manipulate application
specific data attached to a specific structure.
These functions should only be used by applications to manipulate
B<CRYPTO_EX_DATA> structures passed to the B<new_func()>, B<free_func()> and
B<dup_func()> callbacks: as passed to B<RSA_get_ex_new_index()> for example.
B<CRYPTO_set_ex_data()> is used to set application specific data, the data is
supplied in the B<arg> parameter and its precise meaning is up to the
application.
B<CRYPTO_get_ex_data()> is used to retrieve application specific data. The data
is returned to the application, this will be the same value as supplied to
a previous B<CRYPTO_set_ex_data()> call.
=head1 RETURN VALUES
B<CRYPTO_set_ex_data()> returns 1 on success or 0 on failure.
B<CRYPTO_get_ex_data()> returns the application data or 0 on failure. 0 may also
be valid application data but currently it can only fail if given an invalid B<idx>
parameter.
On failure an error code can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>.
=head1 SEE ALSO
L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>,
L<DSA_get_ex_new_index(3)|DSA_get_ex_new_index(3)>,
L<DH_get_ex_new_index(3)|DH_get_ex_new_index(3)>
=head1 HISTORY
CRYPTO_set_ex_data() and CRYPTO_get_ex_data() have been available since SSLeay 0.9.0.
=cut

50
openssl-1.0.2f/doc/crypto/DH_generate_key.pod Normal file
View File

@@ -0,0 +1,50 @@
=pod
=head1 NAME
DH_generate_key, DH_compute_key - perform Diffie-Hellman key exchange
=head1 SYNOPSIS
#include <openssl/dh.h>
int DH_generate_key(DH *dh);
int DH_compute_key(unsigned char *key, BIGNUM *pub_key, DH *dh);
=head1 DESCRIPTION
DH_generate_key() performs the first step of a Diffie-Hellman key
exchange by generating private and public DH values. By calling
DH_compute_key(), these are combined with the other party's public
value to compute the shared key.
DH_generate_key() expects B<dh> to contain the shared parameters
B<dh-E<gt>p> and B<dh-E<gt>g>. It generates a random private DH value
unless B<dh-E<gt>priv_key> is already set, and computes the
corresponding public value B<dh-E<gt>pub_key>, which can then be
published.
DH_compute_key() computes the shared secret from the private DH value
in B<dh> and the other party's public value in B<pub_key> and stores
it in B<key>. B<key> must point to B<DH_size(dh)> bytes of memory.
=head1 RETURN VALUES
DH_generate_key() returns 1 on success, 0 otherwise.
DH_compute_key() returns the size of the shared secret on success, -1
on error.
The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
=head1 SEE ALSO
L<dh(3)|dh(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>, L<DH_size(3)|DH_size(3)>
=head1 HISTORY
DH_generate_key() and DH_compute_key() are available in all versions
of SSLeay and OpenSSL.
=cut

82
openssl-1.0.2f/doc/crypto/DH_generate_parameters.pod Normal file
View File

@@ -0,0 +1,82 @@
=pod
=head1 NAME
DH_generate_parameters_ex, DH_generate_parameters,
DH_check - generate and check Diffie-Hellman parameters
=head1 SYNOPSIS
#include <openssl/dh.h>
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_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<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<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
error, the bit flags DH_CHECK_P_NOT_SAFE_PRIME or
DH_NOT_SUITABLE_GENERATOR are set in B<*codes>.
DH_UNABLE_TO_CHECK_GENERATOR is set if the generator cannot be
checked, i.e. it does not equal 2 or 5.
=head1 RETURN VALUES
DH_generate_parameters_ex() and DH_check() return 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_ex() and DH_generate_parameters() may run for several
hours before finding a suitable prime.
The parameters generated by DH_generate_parameters_ex() and DH_generate_parameters()
are not to be used in signature schemes.
=head1 BUGS
If B<generator> is not 2 or 5, B<dh-E<gt>g>=B<generator> is not
a usable generator.
=head1 SEE ALSO
L<dh(3)|dh(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>,
L<DH_free(3)|DH_free(3)>
=head1 HISTORY
DH_check() is available in all versions of SSLeay and OpenSSL.
The B<cb_arg> argument to DH_generate_parameters() was added in SSLeay 0.9.0.
In versions before OpenSSL 0.9.5, DH_CHECK_P_NOT_STRONG_PRIME is used
instead of DH_CHECK_P_NOT_SAFE_PRIME.
=cut

36
openssl-1.0.2f/doc/crypto/DH_get_ex_new_index.pod Normal file
View File

@@ -0,0 +1,36 @@
=pod
=head1 NAME
DH_get_ex_new_index, DH_set_ex_data, DH_get_ex_data - add application specific data to DH structures
=head1 SYNOPSIS
#include <openssl/dh.h>
int DH_get_ex_new_index(long argl, void *argp,
CRYPTO_EX_new *new_func,
CRYPTO_EX_dup *dup_func,
CRYPTO_EX_free *free_func);
int DH_set_ex_data(DH *d, int idx, void *arg);
char *DH_get_ex_data(DH *d, int idx);
=head1 DESCRIPTION
These functions handle application specific data in DH
structures. Their usage is identical to that of
RSA_get_ex_new_index(), RSA_set_ex_data() and RSA_get_ex_data()
as described in L<RSA_get_ex_new_index(3)>.
=head1 SEE ALSO
L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>, L<dh(3)|dh(3)>
=head1 HISTORY
DH_get_ex_new_index(), DH_set_ex_data() and DH_get_ex_data() are
available since OpenSSL 0.9.5.
=cut

40
openssl-1.0.2f/doc/crypto/DH_new.pod Normal file
View File

@@ -0,0 +1,40 @@
=pod
=head1 NAME
DH_new, DH_free - allocate and free DH objects
=head1 SYNOPSIS
#include <openssl/dh.h>
DH* DH_new(void);
void DH_free(DH *dh);
=head1 DESCRIPTION
DH_new() allocates and initializes a B<DH> structure.
DH_free() frees the B<DH> structure and its components. The values are
erased before the memory is returned to the system.
=head1 RETURN VALUES
If the allocation fails, DH_new() returns B<NULL> and sets an error
code that can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. Otherwise it returns
a pointer to the newly allocated structure.
DH_free() returns no value.
=head1 SEE ALSO
L<dh(3)|dh(3)>, L<ERR_get_error(3)|ERR_get_error(3)>,
L<DH_generate_parameters(3)|DH_generate_parameters(3)>,
L<DH_generate_key(3)|DH_generate_key(3)>
=head1 HISTORY
DH_new() and DH_free() are available in all versions of SSLeay and OpenSSL.
=cut

129
openssl-1.0.2f/doc/crypto/DH_set_method.pod Normal file
View File

@@ -0,0 +1,129 @@
=pod
=head1 NAME
DH_set_default_method, DH_get_default_method,
DH_set_method, DH_new_method, DH_OpenSSL - select DH method
=head1 SYNOPSIS
#include <openssl/dh.h>
#include <openssl/engine.h>
void DH_set_default_method(const DH_METHOD *meth);
const DH_METHOD *DH_get_default_method(void);
int DH_set_method(DH *dh, const DH_METHOD *meth);
DH *DH_new_method(ENGINE *engine);
const DH_METHOD *DH_OpenSSL(void);
=head1 DESCRIPTION
A B<DH_METHOD> specifies the functions that OpenSSL uses for Diffie-Hellman
operations. By modifying the method, alternative implementations
such as hardware accelerators may be used. IMPORTANT: See the NOTES section for
important information about how these DH API functions are affected by the use
of B<ENGINE> API calls.
Initially, the default DH_METHOD is the OpenSSL internal implementation, as
returned by DH_OpenSSL().
DH_set_default_method() makes B<meth> the default method for all DH
structures created later. B<NB>: This is true only whilst no ENGINE has been set
as a default for DH, so this function is no longer recommended.
DH_get_default_method() returns a pointer to the current default DH_METHOD.
However, the meaningfulness of this result is dependent on whether the ENGINE
API is being used, so this function is no longer recommended.
DH_set_method() selects B<meth> to perform all operations using the key B<dh>.
This will replace the DH_METHOD used by the DH key and if the previous method
was supplied by an ENGINE, the handle to that ENGINE will be released during the
change. It is possible to have DH keys that only work with certain DH_METHOD
implementations (eg. from an ENGINE module that supports embedded
hardware-protected keys), and in such cases attempting to change the DH_METHOD
for the key can have unexpected results.
DH_new_method() allocates and initializes a DH structure so that B<engine> will
be used for the DH operations. If B<engine> is NULL, the default ENGINE for DH
operations is used, and if no default ENGINE is set, the DH_METHOD controlled by
DH_set_default_method() is used.
=head1 THE DH_METHOD STRUCTURE
typedef struct dh_meth_st
{
/* name of the implementation */
const char *name;
/* generate private and public DH values for key agreement */
int (*generate_key)(DH *dh);
/* compute shared secret */
int (*compute_key)(unsigned char *key, BIGNUM *pub_key, DH *dh);
/* compute r = a ^ p mod m (May be NULL for some implementations) */
int (*bn_mod_exp)(DH *dh, BIGNUM *r, BIGNUM *a, const BIGNUM *p,
const BIGNUM *m, BN_CTX *ctx,
BN_MONT_CTX *m_ctx);
/* called at DH_new */
int (*init)(DH *dh);
/* called at DH_free */
int (*finish)(DH *dh);
int flags;
char *app_data; /* ?? */
} DH_METHOD;
=head1 RETURN VALUES
DH_OpenSSL() and DH_get_default_method() return pointers to the respective
B<DH_METHOD>s.
DH_set_default_method() returns no value.
DH_set_method() returns non-zero if the provided B<meth> was successfully set as
the method for B<dh> (including unloading the ENGINE handle if the previous
method was supplied by an ENGINE).
DH_new_method() returns NULL and sets an error code that can be obtained by
L<ERR_get_error(3)|ERR_get_error(3)> if the allocation fails. Otherwise it
returns a pointer to the newly allocated structure.
=head1 NOTES
As of version 0.9.7, DH_METHOD implementations are grouped together with other
algorithmic APIs (eg. RSA_METHOD, EVP_CIPHER, etc) in B<ENGINE> modules. If a
default ENGINE is specified for DH functionality using an ENGINE API function,
that will override any DH defaults set using the DH API (ie.
DH_set_default_method()). For this reason, the ENGINE API is the recommended way
to control default implementations for use in DH and other cryptographic
algorithms.
=head1 SEE ALSO
L<dh(3)|dh(3)>, L<DH_new(3)|DH_new(3)>
=head1 HISTORY
DH_set_default_method(), DH_get_default_method(), DH_set_method(),
DH_new_method() and DH_OpenSSL() were added in OpenSSL 0.9.4.
DH_set_default_openssl_method() and DH_get_default_openssl_method() replaced
DH_set_default_method() and DH_get_default_method() respectively, and
DH_set_method() and DH_new_method() were altered to use B<ENGINE>s rather than
B<DH_METHOD>s during development of the engine version of OpenSSL 0.9.6. For
0.9.7, the handling of defaults in the ENGINE API was restructured so that this
change was reversed, and behaviour of the other functions resembled more closely
the previous behaviour. The behaviour of defaults in the ENGINE API now
transparently overrides the behaviour of defaults in the DH API without
requiring changing these function prototypes.
=cut

33
openssl-1.0.2f/doc/crypto/DH_size.pod Normal file
View File

@@ -0,0 +1,33 @@
=pod
=head1 NAME
DH_size - get Diffie-Hellman prime size
=head1 SYNOPSIS
#include <openssl/dh.h>
int DH_size(DH *dh);
=head1 DESCRIPTION
This function returns the Diffie-Hellman size in bytes. It can be used
to determine how much memory must be allocated for the shared secret
computed by DH_compute_key().
B<dh-E<gt>p> must not be B<NULL>.
=head1 RETURN VALUE
The size in bytes.
=head1 SEE ALSO
L<dh(3)|dh(3)>, L<DH_generate_key(3)|DH_generate_key(3)>
=head1 HISTORY
DH_size() is available in all versions of SSLeay and OpenSSL.
=cut

40
openssl-1.0.2f/doc/crypto/DSA_SIG_new.pod Normal file
View File

@@ -0,0 +1,40 @@
=pod
=head1 NAME
DSA_SIG_new, DSA_SIG_free - allocate and free DSA signature objects
=head1 SYNOPSIS
#include <openssl/dsa.h>
DSA_SIG *DSA_SIG_new(void);
void DSA_SIG_free(DSA_SIG *a);
=head1 DESCRIPTION
DSA_SIG_new() allocates and initializes a B<DSA_SIG> structure.
DSA_SIG_free() frees the B<DSA_SIG> structure and its components. The
values are erased before the memory is returned to the system.
=head1 RETURN VALUES
If the allocation fails, DSA_SIG_new() returns B<NULL> and sets an
error code that can be obtained by
L<ERR_get_error(3)|ERR_get_error(3)>. Otherwise it returns a pointer
to the newly allocated structure.
DSA_SIG_free() returns no value.
=head1 SEE ALSO
L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>,
L<DSA_do_sign(3)|DSA_do_sign(3)>
=head1 HISTORY
DSA_SIG_new() and DSA_SIG_free() were added in OpenSSL 0.9.3.
=cut

47
openssl-1.0.2f/doc/crypto/DSA_do_sign.pod Normal file
View File

@@ -0,0 +1,47 @@
=pod
=head1 NAME
DSA_do_sign, DSA_do_verify - raw DSA signature operations
=head1 SYNOPSIS
#include <openssl/dsa.h>
DSA_SIG *DSA_do_sign(const unsigned char *dgst, int dlen, DSA *dsa);
int DSA_do_verify(const unsigned char *dgst, int dgst_len,
DSA_SIG *sig, DSA *dsa);
=head1 DESCRIPTION
DSA_do_sign() computes a digital signature on the B<len> byte message
digest B<dgst> using the private key B<dsa> and returns it in a
newly allocated B<DSA_SIG> structure.
L<DSA_sign_setup(3)|DSA_sign_setup(3)> may be used to precompute part
of the signing operation in case signature generation is
time-critical.
DSA_do_verify() verifies that the signature B<sig> matches a given
message digest B<dgst> of size B<len>. B<dsa> is the signer's public
key.
=head1 RETURN VALUES
DSA_do_sign() returns the signature, NULL on error. DSA_do_verify()
returns 1 for a valid signature, 0 for an incorrect signature and -1
on error. The error codes can be obtained by
L<ERR_get_error(3)|ERR_get_error(3)>.
=head1 SEE ALSO
L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>,
L<DSA_SIG_new(3)|DSA_SIG_new(3)>,
L<DSA_sign(3)|DSA_sign(3)>
=head1 HISTORY
DSA_do_sign() and DSA_do_verify() were added in OpenSSL 0.9.3.
=cut

36
openssl-1.0.2f/doc/crypto/DSA_dup_DH.pod Normal file
View File

@@ -0,0 +1,36 @@
=pod
=head1 NAME
DSA_dup_DH - create a DH structure out of DSA structure
=head1 SYNOPSIS
#include <openssl/dsa.h>
DH * DSA_dup_DH(const DSA *r);
=head1 DESCRIPTION
DSA_dup_DH() duplicates DSA parameters/keys as DH parameters/keys. q
is lost during that conversion, but the resulting DH parameters
contain its length.
=head1 RETURN VALUE
DSA_dup_DH() returns the new B<DH> structure, and NULL on error. The
error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
=head1 NOTE
Be careful to avoid small subgroup attacks when using this.
=head1 SEE ALSO
L<dh(3)|dh(3)>, L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>
=head1 HISTORY
DSA_dup_DH() was added in OpenSSL 0.9.4.
=cut

34
openssl-1.0.2f/doc/crypto/DSA_generate_key.pod Normal file
View File

@@ -0,0 +1,34 @@
=pod
=head1 NAME
DSA_generate_key - generate DSA key pair
=head1 SYNOPSIS
#include <openssl/dsa.h>
int DSA_generate_key(DSA *a);
=head1 DESCRIPTION
DSA_generate_key() expects B<a> to contain DSA parameters. It generates
a new key pair and stores it in B<a-E<gt>pub_key> and B<a-E<gt>priv_key>.
The PRNG must be seeded prior to calling DSA_generate_key().
=head1 RETURN VALUE
DSA_generate_key() returns 1 on success, 0 otherwise.
The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
=head1 SEE ALSO
L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>,
L<DSA_generate_parameters(3)|DSA_generate_parameters(3)>
=head1 HISTORY
DSA_generate_key() is available since SSLeay 0.8.
=cut

121
openssl-1.0.2f/doc/crypto/DSA_generate_parameters.pod Normal file
View File

@@ -0,0 +1,121 @@
=pod
=head1 NAME
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_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.
If B<seed> is B<NULL> or B<seed_len> E<lt> 20, the primes will be
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.
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<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<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<BN_GENCB_call(cb, 1, -1)> is called.
While a candidate for q is tested by Miller-Rabin primality tests,
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<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<BN_GENCB_call(cb, 0, counter)> is called.
=item *
When a candidate for p has passed the test by trial division,
B<BN_GENCB_call(cb, 1, -1)> is called.
While it is tested by the Miller-Rabin primality test,
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<BN_GENCB_call(cb, 2, 1)> is called.
=item *
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)>.
=head1 BUGS
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<BN_generate_prime(3)|BN_generate_prime(3)>
=head1 HISTORY
DSA_generate_parameters() appeared in SSLeay 0.8. The B<cb_arg>
argument was added in SSLeay 0.9.0.
In versions up to OpenSSL 0.9.4, B<callback(1, ...)> was called
in the inner loop of the Miller-Rabin test whenever it reached the
squaring step (the parameters to B<callback> did not reveal how many
witnesses had been tested); since OpenSSL 0.9.5, B<callback(1, ...)>
is called as in BN_is_prime(3), i.e. once for each witness.
=cut

36
openssl-1.0.2f/doc/crypto/DSA_get_ex_new_index.pod Normal file
View File

@@ -0,0 +1,36 @@
=pod
=head1 NAME
DSA_get_ex_new_index, DSA_set_ex_data, DSA_get_ex_data - add application specific data to DSA structures
=head1 SYNOPSIS
#include <openssl/dsa.h>
int DSA_get_ex_new_index(long argl, void *argp,
CRYPTO_EX_new *new_func,
CRYPTO_EX_dup *dup_func,
CRYPTO_EX_free *free_func);
int DSA_set_ex_data(DSA *d, int idx, void *arg);
char *DSA_get_ex_data(DSA *d, int idx);
=head1 DESCRIPTION
These functions handle application specific data in DSA
structures. Their usage is identical to that of
RSA_get_ex_new_index(), RSA_set_ex_data() and RSA_get_ex_data()
as described in L<RSA_get_ex_new_index(3)>.
=head1 SEE ALSO
L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>, L<dsa(3)|dsa(3)>
=head1 HISTORY
DSA_get_ex_new_index(), DSA_set_ex_data() and DSA_get_ex_data() are
available since OpenSSL 0.9.5.
=cut

42
openssl-1.0.2f/doc/crypto/DSA_new.pod Normal file
View File

@@ -0,0 +1,42 @@
=pod
=head1 NAME
DSA_new, DSA_free - allocate and free DSA objects
=head1 SYNOPSIS
#include <openssl/dsa.h>
DSA* DSA_new(void);
void DSA_free(DSA *dsa);
=head1 DESCRIPTION
DSA_new() allocates and initializes a B<DSA> structure. It is equivalent to
calling DSA_new_method(NULL).
DSA_free() frees the B<DSA> structure and its components. The values are
erased before the memory is returned to the system.
=head1 RETURN VALUES
If the allocation fails, DSA_new() returns B<NULL> and sets an error
code that can be obtained by
L<ERR_get_error(3)|ERR_get_error(3)>. Otherwise it returns a pointer
to the newly allocated structure.
DSA_free() returns no value.
=head1 SEE ALSO
L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>,
L<DSA_generate_parameters(3)|DSA_generate_parameters(3)>,
L<DSA_generate_key(3)|DSA_generate_key(3)>
=head1 HISTORY
DSA_new() and DSA_free() are available in all versions of SSLeay and OpenSSL.
=cut

143
openssl-1.0.2f/doc/crypto/DSA_set_method.pod Normal file
View File

@@ -0,0 +1,143 @@
=pod
=head1 NAME
DSA_set_default_method, DSA_get_default_method,
DSA_set_method, DSA_new_method, DSA_OpenSSL - select DSA method
=head1 SYNOPSIS
#include <openssl/dsa.h>
#include <openssl/engine.h>
void DSA_set_default_method(const DSA_METHOD *meth);
const DSA_METHOD *DSA_get_default_method(void);
int DSA_set_method(DSA *dsa, const DSA_METHOD *meth);
DSA *DSA_new_method(ENGINE *engine);
DSA_METHOD *DSA_OpenSSL(void);
=head1 DESCRIPTION
A B<DSA_METHOD> specifies the functions that OpenSSL uses for DSA
operations. By modifying the method, alternative implementations
such as hardware accelerators may be used. IMPORTANT: See the NOTES section for
important information about how these DSA API functions are affected by the use
of B<ENGINE> API calls.
Initially, the default DSA_METHOD is the OpenSSL internal implementation,
as returned by DSA_OpenSSL().
DSA_set_default_method() makes B<meth> the default method for all DSA
structures created later. B<NB>: This is true only whilst no ENGINE has
been set as a default for DSA, so this function is no longer recommended.
DSA_get_default_method() returns a pointer to the current default
DSA_METHOD. However, the meaningfulness of this result is dependent on
whether the ENGINE API is being used, so this function is no longer
recommended.
DSA_set_method() selects B<meth> to perform all operations using the key
B<rsa>. This will replace the DSA_METHOD used by the DSA key and if the
previous method was supplied by an ENGINE, the handle to that ENGINE will
be released during the change. It is possible to have DSA keys that only
work with certain DSA_METHOD implementations (eg. from an ENGINE module
that supports embedded hardware-protected keys), and in such cases
attempting to change the DSA_METHOD for the key can have unexpected
results.
DSA_new_method() allocates and initializes a DSA structure so that B<engine>
will be used for the DSA operations. If B<engine> is NULL, the default engine
for DSA operations is used, and if no default ENGINE is set, the DSA_METHOD
controlled by DSA_set_default_method() is used.
=head1 THE DSA_METHOD STRUCTURE
struct
{
/* name of the implementation */
const char *name;
/* sign */
DSA_SIG *(*dsa_do_sign)(const unsigned char *dgst, int dlen,
DSA *dsa);
/* pre-compute k^-1 and r */
int (*dsa_sign_setup)(DSA *dsa, BN_CTX *ctx_in, BIGNUM **kinvp,
BIGNUM **rp);
/* verify */
int (*dsa_do_verify)(const unsigned char *dgst, int dgst_len,
DSA_SIG *sig, DSA *dsa);
/* compute rr = a1^p1 * a2^p2 mod m (May be NULL for some
implementations) */
int (*dsa_mod_exp)(DSA *dsa, BIGNUM *rr, BIGNUM *a1, BIGNUM *p1,
BIGNUM *a2, BIGNUM *p2, BIGNUM *m,
BN_CTX *ctx, BN_MONT_CTX *in_mont);
/* compute r = a ^ p mod m (May be NULL for some implementations) */
int (*bn_mod_exp)(DSA *dsa, BIGNUM *r, BIGNUM *a,
const BIGNUM *p, const BIGNUM *m,
BN_CTX *ctx, BN_MONT_CTX *m_ctx);
/* called at DSA_new */
int (*init)(DSA *DSA);
/* called at DSA_free */
int (*finish)(DSA *DSA);
int flags;
char *app_data; /* ?? */
} DSA_METHOD;
=head1 RETURN VALUES
DSA_OpenSSL() and DSA_get_default_method() return pointers to the respective
B<DSA_METHOD>s.
DSA_set_default_method() returns no value.
DSA_set_method() returns non-zero if the provided B<meth> was successfully set as
the method for B<dsa> (including unloading the ENGINE handle if the previous
method was supplied by an ENGINE).
DSA_new_method() returns NULL and sets an error code that can be
obtained by L<ERR_get_error(3)|ERR_get_error(3)> if the allocation
fails. Otherwise it returns a pointer to the newly allocated structure.
=head1 NOTES
As of version 0.9.7, DSA_METHOD implementations are grouped together with other
algorithmic APIs (eg. RSA_METHOD, EVP_CIPHER, etc) in B<ENGINE> modules. If a
default ENGINE is specified for DSA functionality using an ENGINE API function,
that will override any DSA defaults set using the DSA API (ie.
DSA_set_default_method()). For this reason, the ENGINE API is the recommended way
to control default implementations for use in DSA and other cryptographic
algorithms.
=head1 SEE ALSO
L<dsa(3)|dsa(3)>, L<DSA_new(3)|DSA_new(3)>
=head1 HISTORY
DSA_set_default_method(), DSA_get_default_method(), DSA_set_method(),
DSA_new_method() and DSA_OpenSSL() were added in OpenSSL 0.9.4.
DSA_set_default_openssl_method() and DSA_get_default_openssl_method() replaced
DSA_set_default_method() and DSA_get_default_method() respectively, and
DSA_set_method() and DSA_new_method() were altered to use B<ENGINE>s rather than
B<DSA_METHOD>s during development of the engine version of OpenSSL 0.9.6. For
0.9.7, the handling of defaults in the ENGINE API was restructured so that this
change was reversed, and behaviour of the other functions resembled more closely
the previous behaviour. The behaviour of defaults in the ENGINE API now
transparently overrides the behaviour of defaults in the DSA API without
requiring changing these function prototypes.
=cut

66
openssl-1.0.2f/doc/crypto/DSA_sign.pod Normal file
View File

@@ -0,0 +1,66 @@
=pod
=head1 NAME
DSA_sign, DSA_sign_setup, DSA_verify - DSA signatures
=head1 SYNOPSIS
#include <openssl/dsa.h>
int DSA_sign(int type, const unsigned char *dgst, int len,
unsigned char *sigret, unsigned int *siglen, DSA *dsa);
int DSA_sign_setup(DSA *dsa, BN_CTX *ctx, BIGNUM **kinvp,
BIGNUM **rp);
int DSA_verify(int type, const unsigned char *dgst, int len,
unsigned char *sigbuf, int siglen, DSA *dsa);
=head1 DESCRIPTION
DSA_sign() computes a digital signature on the B<len> byte message
digest B<dgst> using the private key B<dsa> and places its ASN.1 DER
encoding at B<sigret>. The length of the signature is places in
*B<siglen>. B<sigret> must point to DSA_size(B<dsa>) bytes of memory.
DSA_sign_setup() may be used to precompute part of the signing
operation in case signature generation is time-critical. It expects
B<dsa> to contain DSA parameters. It places the precomputed values
in newly allocated B<BIGNUM>s at *B<kinvp> and *B<rp>, after freeing
the old ones unless *B<kinvp> and *B<rp> are NULL. These values may
be passed to DSA_sign() in B<dsa-E<gt>kinv> and B<dsa-E<gt>r>.
B<ctx> is a pre-allocated B<BN_CTX> or NULL.
DSA_verify() verifies that the signature B<sigbuf> of size B<siglen>
matches a given message digest B<dgst> of size B<len>.
B<dsa> is the signer's public key.
The B<type> parameter is ignored.
The PRNG must be seeded before DSA_sign() (or DSA_sign_setup())
is called.
=head1 RETURN VALUES
DSA_sign() and DSA_sign_setup() return 1 on success, 0 on error.
DSA_verify() returns 1 for a valid signature, 0 for an incorrect
signature and -1 on error. The error codes can be obtained by
L<ERR_get_error(3)|ERR_get_error(3)>.
=head1 CONFORMING TO
US Federal Information Processing Standard FIPS 186 (Digital Signature
Standard, DSS), ANSI X9.30
=head1 SEE ALSO
L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>,
L<DSA_do_sign(3)|DSA_do_sign(3)>
=head1 HISTORY
DSA_sign() and DSA_verify() are available in all versions of SSLeay.
DSA_sign_setup() was added in SSLeay 0.8.
=cut

33
openssl-1.0.2f/doc/crypto/DSA_size.pod Normal file
View File

@@ -0,0 +1,33 @@
=pod
=head1 NAME
DSA_size - get DSA signature size
=head1 SYNOPSIS
#include <openssl/dsa.h>
int DSA_size(const DSA *dsa);
=head1 DESCRIPTION
This function returns the size of an ASN.1 encoded DSA signature in
bytes. It can be used to determine how much memory must be allocated
for a DSA signature.
B<dsa-E<gt>q> must not be B<NULL>.
=head1 RETURN VALUE
The size in bytes.
=head1 SEE ALSO
L<dsa(3)|dsa(3)>, L<DSA_sign(3)|DSA_sign(3)>
=head1 HISTORY
DSA_size() is available in all versions of SSLeay and OpenSSL.
=cut

60
openssl-1.0.2f/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
openssl-1.0.2f/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 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
openssl-1.0.2f/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
openssl-1.0.2f/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 arbitrary 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 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
openssl-1.0.2f/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
openssl-1.0.2f/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

51
openssl-1.0.2f/doc/crypto/ERR_GET_LIB.pod Normal file
View File

@@ -0,0 +1,51 @@
=pod
=head1 NAME
ERR_GET_LIB, ERR_GET_FUNC, ERR_GET_REASON - get library, function and
reason code
=head1 SYNOPSIS
#include <openssl/err.h>
int ERR_GET_LIB(unsigned long e);
int ERR_GET_FUNC(unsigned long e);
int ERR_GET_REASON(unsigned long e);
=head1 DESCRIPTION
The error code returned by ERR_get_error() consists of a library
number, function code and reason code. ERR_GET_LIB(), ERR_GET_FUNC()
and ERR_GET_REASON() can be used to extract these.
The library number and function code describe where the error
occurred, the reason code is the information about what went wrong.
Each sub-library of OpenSSL has a unique library number; function and
reason codes are unique within each sub-library. Note that different
libraries may use the same value to signal different functions and
reasons.
B<ERR_R_...> reason codes such as B<ERR_R_MALLOC_FAILURE> are globally
unique. However, when checking for sub-library specific reason codes,
be sure to also compare the library number.
ERR_GET_LIB(), ERR_GET_FUNC() and ERR_GET_REASON() are macros.
=head1 RETURN VALUES
The library number, function code and reason code respectively.
=head1 SEE ALSO
L<err(3)|err(3)>, L<ERR_get_error(3)|ERR_get_error(3)>
=head1 HISTORY
ERR_GET_LIB(), ERR_GET_FUNC() and ERR_GET_REASON() are available in
all versions of SSLeay and OpenSSL.
=cut

29
openssl-1.0.2f/doc/crypto/ERR_clear_error.pod Normal file
View File

@@ -0,0 +1,29 @@
=pod
=head1 NAME
ERR_clear_error - clear the error queue
=head1 SYNOPSIS
#include <openssl/err.h>
void ERR_clear_error(void);
=head1 DESCRIPTION
ERR_clear_error() empties the current thread's error queue.
=head1 RETURN VALUES
ERR_clear_error() has no return value.
=head1 SEE ALSO
L<err(3)|err(3)>, L<ERR_get_error(3)|ERR_get_error(3)>
=head1 HISTORY
ERR_clear_error() is available in all versions of SSLeay and OpenSSL.
=cut

73
openssl-1.0.2f/doc/crypto/ERR_error_string.pod Normal file
View File

@@ -0,0 +1,73 @@
=pod
=head1 NAME
ERR_error_string, ERR_error_string_n, ERR_lib_error_string,
ERR_func_error_string, ERR_reason_error_string - obtain human-readable
error message
=head1 SYNOPSIS
#include <openssl/err.h>
char *ERR_error_string(unsigned long e, char *buf);
void ERR_error_string_n(unsigned long e, char *buf, size_t len);
const char *ERR_lib_error_string(unsigned long e);
const char *ERR_func_error_string(unsigned long e);
const char *ERR_reason_error_string(unsigned long e);
=head1 DESCRIPTION
ERR_error_string() generates a human-readable string representing the
error code I<e>, and places it at I<buf>. I<buf> must be at least 120
bytes long. If I<buf> is B<NULL>, the error string is placed in a
static buffer.
ERR_error_string_n() is a variant of ERR_error_string() that writes
at most I<len> characters (including the terminating 0)
and truncates the string if necessary.
For ERR_error_string_n(), I<buf> may not be B<NULL>.
The string will have the following format:
error:[error code]:[library name]:[function name]:[reason string]
I<error code> is an 8 digit hexadecimal number, I<library name>,
I<function name> and I<reason string> are ASCII text.
ERR_lib_error_string(), ERR_func_error_string() and
ERR_reason_error_string() return the library name, function
name and reason string respectively.
The OpenSSL error strings should be loaded by calling
L<ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3)> or, for SSL
applications, L<SSL_load_error_strings(3)|SSL_load_error_strings(3)>
first.
If there is no text string registered for the given error code,
the error string will contain the numeric code.
L<ERR_print_errors(3)|ERR_print_errors(3)> can be used to print
all error codes currently in the queue.
=head1 RETURN VALUES
ERR_error_string() returns a pointer to a static buffer containing the
string if I<buf> B<== NULL>, I<buf> otherwise.
ERR_lib_error_string(), ERR_func_error_string() and
ERR_reason_error_string() return the strings, and B<NULL> if
none is registered for the error code.
=head1 SEE ALSO
L<err(3)|err(3)>, L<ERR_get_error(3)|ERR_get_error(3)>,
L<ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3)>,
L<SSL_load_error_strings(3)|SSL_load_error_strings(3)>
L<ERR_print_errors(3)|ERR_print_errors(3)>
=head1 HISTORY
ERR_error_string() is available in all versions of SSLeay and OpenSSL.
ERR_error_string_n() was added in OpenSSL 0.9.6.
=cut

79
openssl-1.0.2f/doc/crypto/ERR_get_error.pod Normal file
View File

@@ -0,0 +1,79 @@
=pod
=head1 NAME
ERR_get_error, ERR_peek_error, ERR_peek_last_error,
ERR_get_error_line, ERR_peek_error_line, ERR_peek_last_error_line,
ERR_get_error_line_data, ERR_peek_error_line_data,
ERR_peek_last_error_line_data - obtain error code and data
=head1 SYNOPSIS
#include <openssl/err.h>
unsigned long ERR_get_error(void);
unsigned long ERR_peek_error(void);
unsigned long ERR_peek_last_error(void);
unsigned long ERR_get_error_line(const char **file, int *line);
unsigned long ERR_peek_error_line(const char **file, int *line);
unsigned long ERR_peek_last_error_line(const char **file, int *line);
unsigned long ERR_get_error_line_data(const char **file, int *line,
const char **data, int *flags);
unsigned long ERR_peek_error_line_data(const char **file, int *line,
const char **data, int *flags);
unsigned long ERR_peek_last_error_line_data(const char **file, int *line,
const char **data, int *flags);
=head1 DESCRIPTION
ERR_get_error() returns the earliest error code from the thread's error
queue and removes the entry. This function can be called repeatedly
until there are no more error codes to return.
ERR_peek_error() returns the earliest error code from the thread's
error queue without modifying it.
ERR_peek_last_error() returns the latest error code from the thread's
error queue without modifying it.
See L<ERR_GET_LIB(3)|ERR_GET_LIB(3)> for obtaining information about
location and reason of the error, and
L<ERR_error_string(3)|ERR_error_string(3)> for human-readable error
messages.
ERR_get_error_line(), ERR_peek_error_line() and
ERR_peek_last_error_line() are the same as the above, but they
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_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> 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
The error code, or 0 if there is no error in the queue.
=head1 SEE ALSO
L<err(3)|err(3)>, L<ERR_error_string(3)|ERR_error_string(3)>,
L<ERR_GET_LIB(3)|ERR_GET_LIB(3)>
=head1 HISTORY
ERR_get_error(), ERR_peek_error(), ERR_get_error_line() and
ERR_peek_error_line() are available in all versions of SSLeay and
OpenSSL. ERR_get_error_line_data() and ERR_peek_error_line_data()
were added in SSLeay 0.9.0.
ERR_peek_last_error(), ERR_peek_last_error_line() and
ERR_peek_last_error_line_data() were added in OpenSSL 0.9.7.
=cut

46
openssl-1.0.2f/doc/crypto/ERR_load_crypto_strings.pod Normal file
View File

@@ -0,0 +1,46 @@
=pod
=head1 NAME
ERR_load_crypto_strings, SSL_load_error_strings, ERR_free_strings -
load and free error strings
=head1 SYNOPSIS
#include <openssl/err.h>
void ERR_load_crypto_strings(void);
void ERR_free_strings(void);
#include <openssl/ssl.h>
void SSL_load_error_strings(void);
=head1 DESCRIPTION
ERR_load_crypto_strings() registers the error strings for all
B<libcrypto> functions. SSL_load_error_strings() does the same,
but also registers the B<libssl> error strings.
One of these functions should be called before generating
textual error messages. However, this is not required when memory
usage is an issue.
ERR_free_strings() frees all previously loaded error strings.
=head1 RETURN VALUES
ERR_load_crypto_strings(), SSL_load_error_strings() and
ERR_free_strings() return no values.
=head1 SEE ALSO
L<err(3)|err(3)>, L<ERR_error_string(3)|ERR_error_string(3)>
=head1 HISTORY
ERR_load_error_strings(), SSL_load_error_strings() and
ERR_free_strings() are available in all versions of SSLeay and
OpenSSL.
=cut

54
openssl-1.0.2f/doc/crypto/ERR_load_strings.pod Normal file
View File

@@ -0,0 +1,54 @@
=pod
=head1 NAME
ERR_load_strings, ERR_PACK, ERR_get_next_error_library - load
arbitrary error strings
=head1 SYNOPSIS
#include <openssl/err.h>
void ERR_load_strings(int lib, ERR_STRING_DATA str[]);
int ERR_get_next_error_library(void);
unsigned long ERR_PACK(int lib, int func, int reason);
=head1 DESCRIPTION
ERR_load_strings() registers error strings for library number B<lib>.
B<str> is an array of error string data:
typedef struct ERR_string_data_st
{
unsigned long error;
char *string;
} ERR_STRING_DATA;
The error code is generated from the library number and a function and
reason code: B<error> = ERR_PACK(B<lib>, B<func>, B<reason>).
ERR_PACK() is a macro.
The last entry in the array is {0,0}.
ERR_get_next_error_library() can be used to assign library numbers
to user libraries at runtime.
=head1 RETURN VALUE
ERR_load_strings() returns no value. ERR_PACK() return the error code.
ERR_get_next_error_library() returns a new library number.
=head1 SEE ALSO
L<err(3)|err(3)>, L<ERR_load_strings(3)|ERR_load_strings(3)>
=head1 HISTORY
ERR_load_error_strings() and ERR_PACK() are available in all versions
of SSLeay and OpenSSL. ERR_get_next_error_library() was added in
SSLeay 0.9.0.
=cut

51
openssl-1.0.2f/doc/crypto/ERR_print_errors.pod Normal file
View File

@@ -0,0 +1,51 @@
=pod
=head1 NAME
ERR_print_errors, ERR_print_errors_fp - print error messages
=head1 SYNOPSIS
#include <openssl/err.h>
void ERR_print_errors(BIO *bp);
void ERR_print_errors_fp(FILE *fp);
=head1 DESCRIPTION
ERR_print_errors() is a convenience function that prints the error
strings for all errors that OpenSSL has recorded to B<bp>, thus
emptying the error queue.
ERR_print_errors_fp() is the same, except that the output goes to a
B<FILE>.
The error strings will have the following format:
[pid]:error:[error code]:[library name]:[function name]:[reason string]:[file name]:[line]:[optional text message]
I<error code> is an 8 digit hexadecimal number. I<library name>,
I<function name> and I<reason string> are ASCII text, as is I<optional
text message> if one was set for the respective error code.
If there is no text string registered for the given error code,
the error string will contain the numeric code.
=head1 RETURN VALUES
ERR_print_errors() and ERR_print_errors_fp() return no values.
=head1 SEE ALSO
L<err(3)|err(3)>, L<ERR_error_string(3)|ERR_error_string(3)>,
L<ERR_get_error(3)|ERR_get_error(3)>,
L<ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3)>,
L<SSL_load_error_strings(3)|SSL_load_error_strings(3)>
=head1 HISTORY
ERR_print_errors() and ERR_print_errors_fp()
are available in all versions of SSLeay and OpenSSL.
=cut

44
openssl-1.0.2f/doc/crypto/ERR_put_error.pod Normal file
View File

@@ -0,0 +1,44 @@
=pod
=head1 NAME
ERR_put_error, ERR_add_error_data - record an error
=head1 SYNOPSIS
#include <openssl/err.h>
void ERR_put_error(int lib, int func, int reason, const char *file,
int line);
void ERR_add_error_data(int num, ...);
=head1 DESCRIPTION
ERR_put_error() adds an error code to the thread's error queue. It
signals that the error of reason code B<reason> occurred in function
B<func> of library B<lib>, in line number B<line> of B<file>.
This function is usually called by a macro.
ERR_add_error_data() associates the concatenation of its B<num> string
arguments with the error code added last.
L<ERR_load_strings(3)|ERR_load_strings(3)> can be used to register
error strings so that the application can a generate human-readable
error messages for the error code.
=head1 RETURN VALUES
ERR_put_error() and ERR_add_error_data() return
no values.
=head1 SEE ALSO
L<err(3)|err(3)>, L<ERR_load_strings(3)|ERR_load_strings(3)>
=head1 HISTORY
ERR_put_error() is available in all versions of SSLeay and OpenSSL.
ERR_add_error_data() was added in SSLeay 0.9.0.
=cut

45
openssl-1.0.2f/doc/crypto/ERR_remove_state.pod Normal file
View File

@@ -0,0 +1,45 @@
=pod
=head1 NAME
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_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_thread_state and ERR_remove_state() return no value.
=head1 SEE ALSO
L<err(3)|err(3)>
=head1 HISTORY
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

38
openssl-1.0.2f/doc/crypto/ERR_set_mark.pod Normal file
View File

@@ -0,0 +1,38 @@
=pod
=head1 NAME
ERR_set_mark, ERR_pop_to_mark - set marks and pop errors until mark
=head1 SYNOPSIS
#include <openssl/err.h>
int ERR_set_mark(void);
int ERR_pop_to_mark(void);
=head1 DESCRIPTION
ERR_set_mark() sets a mark on the current topmost error record if there
is one.
ERR_pop_to_mark() will pop the top of the error stack until a mark is found.
The mark is then removed. If there is no mark, the whole stack is removed.
=head1 RETURN VALUES
ERR_set_mark() returns 0 if the error stack is empty, otherwise 1.
ERR_pop_to_mark() returns 0 if there was no mark in the error stack, which
implies that the stack became empty, otherwise 1.
=head1 SEE ALSO
L<err(3)|err(3)>
=head1 HISTORY
ERR_set_mark() and ERR_pop_to_mark() were added in OpenSSL 0.9.8.
=cut

70
openssl-1.0.2f/doc/crypto/EVP_BytesToKey.pod Normal file
View File

@@ -0,0 +1,70 @@
=pod
=head1 NAME
EVP_BytesToKey - password based encryption routine
=head1 SYNOPSIS
#include <openssl/evp.h>
int EVP_BytesToKey(const EVP_CIPHER *type,const EVP_MD *md,
const unsigned char *salt,
const unsigned char *data, int datal, int count,
unsigned char *key,unsigned char *iv);
=head1 DESCRIPTION
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> 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>
and B<iv> respectively.
=head1 NOTES
A typical application of this function is to derive keying material for an
encryption algorithm from a password in the B<data> parameter.
Increasing the B<count> parameter slows down the algorithm which makes it
harder for an attacker to peform a brute force attack using a large number
of candidate passwords.
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 a more modern algorithm such as PBKDF2 as
defined in PKCS#5v2.1 and provided by PKCS5_PBKDF2_HMAC.
=head1 KEY DERIVATION ALGORITHM
The key and IV is derived by concatenating D_1, D_2, etc until
enough data is available for the key and IV. D_i is defined as:
D_i = HASH^count(D_(i-1) || data || salt)
where || denotes concatentaion, D_0 is empty, HASH is the digest
algorithm in use, HASH^1(data) is simply HASH(data), HASH^2(data)
is HASH(HASH(data)) and so on.
The initial bytes are used for the key and the subsequent bytes for
the IV.
=head1 RETURN VALUES
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
L<evp(3)|evp(3)>, L<rand(3)|rand(3)>,
L<EVP_EncryptInit(3)|EVP_EncryptInit(3)>
=head1 HISTORY
=cut

282
openssl-1.0.2f/doc/crypto/EVP_DigestInit.pod Normal file
View File

@@ -0,0 +1,282 @@
=pod
=head1 NAME
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_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
=head1 SYNOPSIS
#include <openssl/evp.h>
void EVP_MD_CTX_init(EVP_MD_CTX *ctx);
EVP_MD_CTX *EVP_MD_CTX_create(void);
int EVP_DigestInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl);
int EVP_DigestUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt);
int EVP_DigestFinal_ex(EVP_MD_CTX *ctx, unsigned char *md,
unsigned int *s);
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_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);
#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);
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)
const EVP_MD *EVP_md_null(void);
const EVP_MD *EVP_md2(void);
const EVP_MD *EVP_md5(void);
const EVP_MD *EVP_sha(void);
const EVP_MD *EVP_sha1(void);
const EVP_MD *EVP_dss(void);
const EVP_MD *EVP_dss1(void);
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))
=head1 DESCRIPTION
The EVP digest routines are a high level interface to message digests.
EVP_MD_CTX_init() initializes digest context B<ctx>.
EVP_MD_CTX_create() allocates, initializes and returns a digest context.
EVP_DigestInit_ex() sets up digest context B<ctx> to use a digest
B<type> from ENGINE B<impl>. B<ctx> must be initialized before calling this
function. B<type> will typically be supplied by a functionsuch as EVP_sha1().
If B<impl> is NULL then the default implementation of digest B<type> is used.
EVP_DigestUpdate() hashes B<cnt> bytes of data at B<d> into the
digest context B<ctx>. This function can be called several times on the
same B<ctx> to hash additional data.
EVP_DigestFinal_ex() retrieves the digest value from B<ctx> and places
it in B<md>. If the B<s> parameter is not NULL then the number of
bytes of data written (i.e. the length of the digest) will be written
to the integer at B<s>, at most B<EVP_MAX_MD_SIZE> bytes will be written.
After calling EVP_DigestFinal_ex() no additional calls to EVP_DigestUpdate()
can be made, but EVP_DigestInit_ex() can be called to initialize a new
digest operation.
EVP_MD_CTX_cleanup() cleans up digest context B<ctx>, it should be called
after a digest context is no longer needed.
EVP_MD_CTX_destroy() cleans up digest context B<ctx> and frees up the
space allocated to it, it should be called only on a context created
using EVP_MD_CTX_create().
EVP_MD_CTX_copy_ex() can be used to copy the message digest state from
B<in> to B<out>. This is useful if large amounts of data are to be
hashed which only differ in the last few bytes. B<out> must be initialized
before calling this function.
EVP_DigestInit() behaves in the same way as EVP_DigestInit_ex() except
the passed context B<ctx> does not have to be initialized, and it always
uses the default digest implementation.
EVP_DigestFinal() is similar to EVP_DigestFinal_ex() except the digest
context B<ctx> is automatically cleaned up.
EVP_MD_CTX_copy() is similar to EVP_MD_CTX_copy_ex() except the destination
B<out> does not have to be initialized.
EVP_MD_size() and EVP_MD_CTX_size() return the size of the message digest
when passed an B<EVP_MD> or an B<EVP_MD_CTX> structure, i.e. the size of the
hash.
EVP_MD_block_size() and EVP_MD_CTX_block_size() return the block size of the
message digest when passed an B<EVP_MD> or an B<EVP_MD_CTX> structure.
EVP_MD_type() and EVP_MD_CTX_type() return the NID of the OBJECT IDENTIFIER
representing the given message digest when passed an B<EVP_MD> structure.
For example EVP_MD_type(EVP_sha1()) returns B<NID_sha1>. This function is
normally used when setting ASN1 OIDs.
EVP_MD_CTX_md() returns the B<EVP_MD> structure corresponding to the passed
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>. 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_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
no need to use these pseudo-digests in OpenSSL 1.0.0 and later, they are
however retained for compatibility.
EVP_md_null() is a "null" message digest that does nothing: i.e. the hash it
returns is of zero length.
EVP_get_digestbyname(), EVP_get_digestbynid() and EVP_get_digestbyobj()
return an B<EVP_MD> structure when passed a digest name, a digest NID or
an ASN1_OBJECT structure respectively. The digest table must be initialized
using, for example, OpenSSL_add_all_digests() for these functions to work.
=head1 RETURN VALUES
EVP_DigestInit_ex(), EVP_DigestUpdate() and EVP_DigestFinal_ex() return 1 for
success and 0 for failure.
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() 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
corresponding EVP_MD structures.
EVP_get_digestbyname(), EVP_get_digestbynid() and EVP_get_digestbyobj()
return either an B<EVP_MD> structure or NULL if an error occurs.
=head1 NOTES
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.
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
obsolete but are retained to maintain compatibility with existing code. New
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.
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
This example digests the data "Test Message\n" and "Hello World\n", using the
digest name passed on the command line.
#include <stdio.h>
#include <openssl/evp.h>
main(int argc, char *argv[])
{
EVP_MD_CTX *mdctx;
const EVP_MD *md;
char mess1[] = "Test Message\n";
char mess2[] = "Hello World\n";
unsigned char md_value[EVP_MAX_MD_SIZE];
int md_len, i;
OpenSSL_add_all_digests();
if(!argv[1]) {
printf("Usage: mdtest digestname\n");
exit(1);
}
md = EVP_get_digestbyname(argv[1]);
if(!md) {
printf("Unknown message digest %s\n", argv[1]);
exit(1);
}
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]);
printf("\n");
/* Call this once before exit. */
EVP_cleanup();
exit(0);
}
=head1 SEE ALSO
L<dgst(1)|dgst(1)>,
L<evp(3)|evp(3)>
=head1 HISTORY
EVP_DigestInit(), EVP_DigestUpdate() and EVP_DigestFinal() are
available in all versions of SSLeay and OpenSSL.
EVP_MD_CTX_init(), EVP_MD_CTX_create(), EVP_MD_CTX_copy_ex(),
EVP_MD_CTX_cleanup(), EVP_MD_CTX_destroy(), EVP_DigestInit_ex()
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 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
use EVP_dss1() any more.
OpenSSL 1.0 and later does not include the MD2 digest algorithm in the
default configuration due to its security weaknesses.
=cut

87
openssl-1.0.2f/doc/crypto/EVP_DigestSignInit.pod Normal file
View File

@@ -0,0 +1,87 @@
=pod
=head1 NAME
EVP_DigestSignInit, EVP_DigestSignUpdate, EVP_DigestSignFinal - EVP signing functions
=head1 SYNOPSIS
#include <openssl/evp.h>
int EVP_DigestSignInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx,
const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey);
int EVP_DigestSignUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt);
int EVP_DigestSignFinal(EVP_MD_CTX *ctx, unsigned char *sig, size_t *siglen);
=head1 DESCRIPTION
The EVP signature routines are a high level interface to digital signatures.
EVP_DigestSignInit() sets up signing context B<ctx> to use digest B<type> from
ENGINE B<impl> and private key B<pkey>. B<ctx> must be initialized with
EVP_MD_CTX_init() before calling this function. If B<pctx> is not NULL the
EVP_PKEY_CTX of the signing operation will be written to B<*pctx>: this can
be used to set alternative signing options.
EVP_DigestSignUpdate() hashes B<cnt> bytes of data at B<d> into the
signature context B<ctx>. This function can be called several times on the
same B<ctx> to include additional data. This function is currently implemented
usig a macro.
EVP_DigestSignFinal() signs the data in B<ctx> places the signature in B<sig>.
If B<sig> is B<NULL> then the maximum size of the output buffer is written to
the B<siglen> parameter. If B<sig> is not B<NULL> then before the call the
B<siglen> parameter should contain the length of the B<sig> buffer, if the
call is successful the signature is written to B<sig> and the amount of data
written to B<siglen>.
=head1 RETURN VALUES
EVP_DigestSignInit() EVP_DigestSignUpdate() and EVP_DigestSignaFinal() 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.
The error codes can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>.
=head1 NOTES
The B<EVP> interface to digital signatures should almost always be used in
preference to the low level interfaces. This is because the code then becomes
transparent to the algorithm used and much more flexible.
In previous versions of OpenSSL there was a link between message digest types
and public key algorithms. This meant that "clone" digests such as EVP_dss1()
needed to be used to sign using SHA1 and DSA. This is no longer necessary and
the use of clone digest is now discouraged.
For some key types and parameters the random number generator must be seeded
or the operation will fail.
The call to EVP_DigestSignFinal() internally finalizes a copy of the digest
context. This means that calls to EVP_DigestSignUpdate() and
EVP_DigestSignFinal() can be called later to digest and sign additional data.
Since only a copy of the digest context is ever finalized the context must
be cleaned up after use by calling EVP_MD_CTX_cleanup() or a memory leak
will occur.
The use of EVP_PKEY_size() with these functions is discouraged because some
signature operations may have a signature length which depends on the
parameters set. As a result EVP_PKEY_size() would have to return a value
which indicates the maximum possible signature for any set of parameters.
=head1 SEE ALSO
L<EVP_DigestVerifyInit(3)|EVP_DigestVerifyInit(3)>,
L<EVP_DigestInit(3)|EVP_DigestInit(3)>, L<err(3)|err(3)>,
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)>
=head1 HISTORY
EVP_DigestSignInit(), EVP_DigestSignUpdate() and EVP_DigestSignFinal()
were first added to OpenSSL 1.0.0.
=cut

Some files were not shown because too many files have changed in this diff Show More