ag/cpython-source-deps
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Import OpenSSL 1.1.0f

Browse Source
This commit is contained in:
Steve Dower
2017-09-07 16:27:43 -07:00
committed by Steve Dower
parent ccd3ab4aff
commit f4b81cb7c9
3340 changed files with 325158 additions and 557542 deletions
Download Patch File Download Diff File Expand all files Collapse all files

133
doc/crypto/ASN1_INTEGER_get_int64.pod Normal file
View File

@@ -0,0 +1,133 @@
=pod
=head1 NAME
ASN1_INTEGER_get_uint64, ASN1_INTEGER_set_uint64,
ASN1_INTEGER_get_int64, ASN1_INTEGER_get, ASN1_INTEGER_set_int64, ASN1_INTEGER_set, BN_to_ASN1_INTEGER, ASN1_INTEGER_to_BN, ASN1_ENUMERATED_get_int64, ASN1_ENUMERATED_get, ASN1_ENUMERATED_set_int64, ASN1_ENUMERATED_set, BN_to_ASN1_ENUMERATED, ASN1_ENUMERATED_to_BN
- ASN.1 INTEGER and ENUMERATED utilities
=head1 SYNOPSIS
#include <openssl/asn1.h>
int ASN1_INTEGER_get_int64(int64_t *pr, const ASN1_INTEGER *a);
int ASN1_INTEGER_get(const ASN1_INTEGER *a, long v);
int ASN1_INTEGER_set_int64(ASN1_INTEGER *a, int64_t r);
long ASN1_INTEGER_set(const ASN1_INTEGER *a);
int ASN1_INTEGER_get_uint64(uint64_t *pr, const ASN1_INTEGER *a);
int ASN1_INTEGER_set_uint64(ASN1_INTEGER *a, uint64_t r);
ASN1_INTEGER *BN_to_ASN1_INTEGER(const BIGNUM *bn, ASN1_INTEGER *ai);
BIGNUM *ASN1_INTEGER_to_BN(const ASN1_INTEGER *ai, BIGNUM *bn);
int ASN1_ENUMERATED_get_int64(int64_t *pr, const ASN1_INTEGER *a);
long ASN1_ENUMERATED_get(const ASN1_ENUMERATED *a);
int ASN1_ENUMERATED_set_int64(ASN1_INTEGER *a, int64_t r);
int ASN1_ENUMERATED_set(ASN1_ENUMERATED *a, long v);
ASN1_ENUMERATED *BN_to_ASN1_ENUMERATED(BIGNUM *bn, ASN1_ENUMERATED *ai);
BIGNUM *ASN1_ENUMERATED_to_BN(ASN1_ENUMERATED *ai, BIGNUM *bn);
=head1 DESCRIPTION
These functions convert to and from B<ASN1_INTEGER> and B<ASN1_ENUMERATED>
structures.
ASN1_INTEGER_get_int64() converts an B<ASN1_INTEGER> into an B<int64_t> type
If successful it returns 1 and sets B<*pr> to the value of B<a>. If it fails
(due to invalid type or the value being too big to fit into an B<int64_t> type)
it returns 0.
ASN1_INTEGER_get_uint64() is similar to ASN1_INTEGER_get_int64_t() except it
converts to a B<uint64_t> type and an error is returned if the passed integer
is negative.
ASN1_INTEGER_get() also returns the value of B<a> but it returns 0 if B<a> is
NULL and -1 on error (which is ambiguous because -1 is a legitimate value for
an B<ASN1_INTEGER>). New applications should use ASN1_INTEGER_get_int64()
instead.
ASN1_INTEGER_set_int64() sets the value of B<ASN1_INTEGER> B<a> to the
B<int64_t> value B<r>.
ASN1_INTEGER_set_uint64() sets the value of B<ASN1_INTEGER> B<a> to the
B<uint64_t> value B<r>.
ASN1_INTEGER_set() sets the value of B<ASN1_INTEGER> B<a> to the B<long> value
B<v>.
BN_to_ASN1_INTEGER() converts B<BIGNUM> B<bn> to an B<ASN1_INTEGER>. If B<ai>
is NULL a new B<ASN1_INTEGER> structure is returned. If B<ai> is not NULL then
the existing structure will be used instead.
ASN1_INTEGER_to_BN() converts ASN1_INTEGER B<ai> into a B<BIGNUM>. If B<bn> is
NULL a new B<BIGNUM> structure is returned. If B<bn> is not NULL then the
existing structure will be used instead.
ASN1_ENUMERATED_get_int64(), ASN1_ENUMERATED_set_int64(),
ASN1_ENUMERATED_set(), BN_to_ASN1_ENUMERATED() and ASN1_ENUMERATED_to_BN()
behave in an identical way to their ASN1_INTEGER counterparts except they
operate on an B<ASN1_ENUMERATED> value.
ASN1_ENUMERATED_get() returns the value of B<a> in a similar way to
ASN1_INTEGER_get() but it returns B<0xffffffffL> if the value of B<a> will not
fit in a long type. New applications should use ASN1_ENUMERATED_get_int64()
instead.
=head1 NOTES
In general an B<ASN1_INTEGER> or B<ASN1_ENUMERATED> type can contain an
integer of almost arbitrary size and so cannot always be represented by a C
B<int64_t> type. However in many cases (for example version numbers) they
represent small integers which can be more easily manipulated if converted to
an appropriate C integer type.
=head1 BUGS
The ambiguous return values of ASN1_INTEGER_get() and ASN1_ENUMERATED_get()
mean these functions should be avoided if possible. They are retained for
compatibility. Normally the ambiguous return values are not legitimate
values for the fields they represent.
=head1 RETURN VALUES
ASN1_INTEGER_set_int64(), ASN1_INTEGER_set(), ASN1_ENUMERATED_set_int64() and
ASN1_ENUMERATED_set() return 1 for success and 0 for failure. They will only
fail if a memory allocation error occurs.
ASN1_INTEGER_get_int64() and ASN1_ENUMERATED_get_int64() return 1 for success
and 0 for failure. They will fail if the passed type is incorrect (this will
only happen if there is a programming error) or if the value exceeds the range
of an B<int64_t> type.
BN_to_ASN1_INTEGER() and BN_to_ASN1_ENUMERATED() return an B<ASN1_INTEGER> or
B<ASN1_ENUMERATED> structure respectively or NULL if an error occurs. They will
only fail due to a memory allocation error.
ASN1_INTEGER_to_BN() and ASN1_ENUMERATED_to_BN() return a B<BIGNUM> structure
of NULL if an error occurs. They can fail if the passed type is incorrect
(due to programming error) or due to a memory allocation failure.
=head1 SEE ALSO
L<ERR_get_error(3)>
=head1 HISTORY
ASN1_INTEGER_set_int64(), ASN1_INTEGER_get_int64(),
ASN1_ENUMERATED_set_int64() and ASN1_ENUMERATED_get_int64()
were added to OpenSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

18
doc/crypto/ASN1_OBJECT_new.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
ASN1_OBJECT_new, ASN1_OBJECT_free, - object allocation functions
ASN1_OBJECT_new, ASN1_OBJECT_free - object allocation functions
=head1 SYNOPSIS
@@ -16,9 +16,10 @@ ASN1_OBJECT_new, ASN1_OBJECT_free, - object allocation functions
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_new() allocates and initializes an ASN1_OBJECT structure.
ASN1_OBJECT_free() frees up the B<ASN1_OBJECT> structure B<a>.
If B<a> is NULL, nothing is done.
=head1 NOTES
@@ -29,17 +30,22 @@ 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)>.
code that can be obtained by L<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)>
L<ERR_get_error(3)>, L<d2i_ASN1_OBJECT(3)>
=head1 HISTORY
=head1 COPYRIGHT
ASN1_OBJECT_new() and ASN1_OBJECT_free() are available in all versions of SSLeay and OpenSSL.
Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

32
doc/crypto/ASN1_STRING_length.pod
View File

@@ -3,14 +3,15 @@
=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
ASN1_STRING_type, ASN1_STRING_get0_data, ASN1_STRING_data,
ASN1_STRING_to_UTF8 - ASN1_STRING utility functions
=head1 SYNOPSIS
#include <openssl/asn1.h>
int ASN1_STRING_length(ASN1_STRING *x);
const unsigned char * ASN1_STRING_get0_data(const ASN1_STRING *x);
unsigned char * ASN1_STRING_data(ASN1_STRING *x);
ASN1_STRING * ASN1_STRING_dup(ASN1_STRING *a);
@@ -19,9 +20,9 @@ ASN1_STRING utility functions
int ASN1_STRING_set(ASN1_STRING *str, const void *data, int len);
int ASN1_STRING_type(ASN1_STRING *x);
int ASN1_STRING_type(const ASN1_STRING *x);
int ASN1_STRING_to_UTF8(unsigned char **out, ASN1_STRING *in);
int ASN1_STRING_to_UTF8(unsigned char **out, const ASN1_STRING *in);
=head1 DESCRIPTION
@@ -29,10 +30,14 @@ 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>.
ASN1_STRING_get0_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_data() is similar to ASN1_STRING_get0_data() except the
returned value is not constant. This function is deprecated:
applications should use ASN1_STRING_get0_data() instead.
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
@@ -48,12 +53,12 @@ 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().
should be freed 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
structure. Other types such as B<ASN1_OCTET_STRING> are simply typedef'ed
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
@@ -72,12 +77,17 @@ 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)>
L<ERR_get_error(3)>
=head1 HISTORY
=head1 COPYRIGHT
Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

12
doc/crypto/ASN1_STRING_new.pod
View File

@@ -22,6 +22,7 @@ ASN1_STRING_type_new() returns an allocated B<ASN1_STRING> structure of
type B<type>.
ASN1_STRING_free() frees up B<a>.
If B<a> is NULL nothing is done.
=head1 NOTES
@@ -37,10 +38,15 @@ ASN1_STRING_free() does not return a value.
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>
L<ERR_get_error(3)>
=head1 HISTORY
=head1 COPYRIGHT
TBA
Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

29
doc/crypto/ASN1_STRING_print_ex.pod
View File

@@ -2,16 +2,18 @@
=head1 NAME
ASN1_STRING_print_ex, ASN1_STRING_print_ex_fp, ASN1_STRING_print - ASN1_STRING output routines.
ASN1_tag2str, 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);
int ASN1_STRING_print_ex(BIO *out, const ASN1_STRING *str, unsigned long flags);
int ASN1_STRING_print_ex_fp(FILE *fp, const ASN1_STRING *str, unsigned long flags);
int ASN1_STRING_print(BIO *out, const ASN1_STRING *str);
const char *ASN1_tag2str(int tag);
=head1 DESCRIPTION
@@ -26,11 +28,13 @@ 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 '.'.
ASN1_tag2str() returns a human-readable name of the specified ASN.1 B<tag>.
=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
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.
@@ -75,7 +79,7 @@ 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
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).
@@ -86,11 +90,16 @@ equivalent to:
=head1 SEE ALSO
L<X509_NAME_print_ex(3)|X509_NAME_print_ex(3)>,
L<ASN1_tag2str(3)|ASN1_tag2str(3)>
L<X509_NAME_print_ex(3)>,
L<ASN1_tag2str(3)>
=head1 HISTORY
=head1 COPYRIGHT
TBA
Copyright 2002-2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

15
doc/crypto/ASN1_TIME_set.pod
View File

@@ -3,7 +3,7 @@
=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.
ASN1_TIME_print, ASN1_TIME_diff - ASN.1 Time functions
=head1 SYNOPSIS
@@ -100,7 +100,7 @@ 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 */
/* Invalid time format */
if (day > 0 || sec > 0)
printf("Later\n");
@@ -123,7 +123,16 @@ 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
ASN1_TIME_diff() returns 1 for success and 0 for failure. It can fail if the
pass ASN1_TIME structure has invalid syntax for example.
=head1 COPYRIGHT
Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

100
doc/crypto/ASN1_TYPE_get.pod Normal file
View File

@@ -0,0 +1,100 @@
=pod
=head1 NAME
ASN1_TYPE_get, ASN1_TYPE_set, ASN1_TYPE_set1, ASN1_TYPE_cmp, ASN1_TYPE_unpack_sequence, ASN1_TYPE_pack_sequence - ASN1_TYPE utility
functions
=head1 SYNOPSIS
#include <openssl/asn1.h>
int ASN1_TYPE_get(const ASN1_TYPE *a);
void ASN1_TYPE_set(ASN1_TYPE *a, int type, void *value);
int ASN1_TYPE_set1(ASN1_TYPE *a, int type, const void *value);
int ASN1_TYPE_cmp(const ASN1_TYPE *a, const ASN1_TYPE *b);
void *ASN1_TYPE_unpack_sequence(const ASN1_ITEM *it, const ASN1_TYPE *t);
ASN1_TYPE *ASN1_TYPE_pack_sequence(const ASN1_ITEM *it, void *s,
ASN1_TYPE **t);
=head1 DESCRIPTION
These functions allow an ASN1_TYPE structure to be manipulated. The
ASN1_TYPE structure can contain any ASN.1 type or constructed type
such as a SEQUENCE: it is effectively equivalent to the ASN.1 ANY type.
ASN1_TYPE_get() returns the type of B<a>.
ASN1_TYPE_set() sets the value of B<a> to B<type> and B<value>. This
function uses the pointer B<value> internally so it must B<not> be freed
up after the call.
ASN1_TYPE_set1() sets the value of B<a> to B<type> a copy of B<value>.
ASN1_TYPE_cmp() compares ASN.1 types B<a> and B<b> and returns 0 if
they are identical and non-zero otherwise.
ASN1_TYPE_unpack_sequence() attempts to parse the SEQUENCE present in
B<t> using the ASN.1 structure B<it>. If successful it returns a pointer
to the ASN.1 structure corresponding to B<it> which must be freed by the
caller. If it fails it return NULL.
ASN1_TYPE_pack_sequence() attempts to encode the ASN.1 structure B<s>
corresponding to B<it> into an ASN1_TYPE. If successful the encoded
ASN1_TYPE is returned. If B<t> and B<*t> are not NULL the encoded type
is written to B<t> overwriting any existing data. If B<t> is not NULL
but B<*t> is NULL the returned ASN1_TYPE is written to B<*t>.
=head1 NOTES
The type and meaning of the B<value> parameter for ASN1_TYPE_set() and
ASN1_TYPE_set1() is determined by the B<type> parameter.
If B<type> is V_ASN1_NULL B<value> is ignored. If B<type> is V_ASN1_BOOLEAN
then the boolean is set to TRUE if B<value> is not NULL. If B<type> is
V_ASN1_OBJECT then value is an ASN1_OBJECT structure. Otherwise B<type>
is and ASN1_STRING structure. If B<type> corresponds to a primitive type
(or a string type) then the contents of the ASN1_STRING contain the content
octets of the type. If B<type> corresponds to a constructed type or
a tagged type (V_ASN1_SEQUENCE, V_ASN1_SET or V_ASN1_OTHER) then the
ASN1_STRING contains the entire ASN.1 encoding verbatim (including tag and
length octets).
ASN1_TYPE_cmp() may not return zero if two types are equivalent but have
different encodings. For example the single content octet of the boolean TRUE
value under BER can have any non-zero encoding but ASN1_TYPE_cmp() will
only return zero if the values are the same.
If either or both of the parameters passed to ASN1_TYPE_cmp() is NULL the
return value is non-zero. Technically if both parameters are NULL the two
types could be absent OPTIONAL fields and so should match, however passing
NULL values could also indicate a programming error (for example an
unparseable type which returns NULL) for types which do B<not> match. So
applications should handle the case of two absent values separately.
=head1 RETURN VALUES
ASN1_TYPE_get() returns the type of the ASN1_TYPE argument.
ASN1_TYPE_set() does not return a value.
ASN1_TYPE_set1() returns 1 for success and 0 for failure.
ASN1_TYPE_cmp() returns 0 if the types are identical and non-zero otherwise.
ASN1_TYPE_unpack_sequence() returns a pointer to an ASN.1 structure or
NULL on failure.
ASN1_TYPE_pack_sequence() return an ASN1_TYPE structure if it succeeds or
NULL on failure.
=head1 COPYRIGHT
Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

37
doc/crypto/ASN1_generate_nconf.pod
View File

@@ -8,8 +8,8 @@ ASN1_generate_nconf, ASN1_generate_v3 - ASN1 generation functions
#include <openssl/asn1.h>
ASN1_TYPE *ASN1_generate_nconf(char *str, CONF *nconf);
ASN1_TYPE *ASN1_generate_v3(char *str, X509V3_CTX *cnf);
ASN1_TYPE *ASN1_generate_nconf(const char *str, CONF *nconf);
ASN1_TYPE *ASN1_generate_v3(const char *str, X509V3_CTX *cnf);
=head1 DESCRIPTION
@@ -19,7 +19,7 @@ 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
file whereas 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.
@@ -30,7 +30,7 @@ The actual data encoded is determined by the string B<str> and
the configuration information. The general format of the string
is:
=over 2
=over 4
=item B<[modifier,]type[:value]>
@@ -40,19 +40,19 @@ 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
=head2 Supported Types
The supported types are listed below. Unless otherwise specified
only the B<ASCII> format is permissible.
=over 2
=over 4
=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.
are acceptable.
=item B<NULL>
@@ -78,12 +78,12 @@ 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>.
the format B<YYMMDDHHMMSSZ>.
=item B<GENERALIZEDTIME>, B<GENTIME>
Encodes an ASN1 B<GeneralizedTime> structure, the value should be in
the format B<YYYYMMDDHHMMSSZ>.
the format B<YYYYMMDDHHMMSSZ>.
=item B<OCTETSTRING>, B<OCT>
@@ -119,14 +119,14 @@ will be encoded.
=back
=head2 MODIFIERS
=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
=over 4
=item B<EXPLICIT>, B<EXP>
@@ -181,7 +181,7 @@ 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:
SEQUENCE consisting of a BOOL an OID and a UTF8String:
asn1 = SEQUENCE:seq_section
@@ -252,14 +252,19 @@ structure:
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)>.
The error codes that can be obtained by L<ERR_get_error(3)>.
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>
L<ERR_get_error(3)>
=head1 HISTORY
=head1 COPYRIGHT
ASN1_generate_nconf() and ASN1_generate_v3() were added to OpenSSL 0.9.8
Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

144
doc/crypto/ASYNC_WAIT_CTX_new.pod Normal file
View File

@@ -0,0 +1,144 @@
=pod
=head1 NAME
ASYNC_WAIT_CTX_new, ASYNC_WAIT_CTX_free, ASYNC_WAIT_CTX_set_wait_fd,
ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds,
ASYNC_WAIT_CTX_get_changed_fds, ASYNC_WAIT_CTX_clear_fd - functions to manage
waiting for asynchronous jobs to complete
=head1 SYNOPSIS
#include <openssl/async.h>
ASYNC_WAIT_CTX *ASYNC_WAIT_CTX_new(void);
void ASYNC_WAIT_CTX_free(ASYNC_WAIT_CTX *ctx);
int ASYNC_WAIT_CTX_set_wait_fd(ASYNC_WAIT_CTX *ctx, const void *key,
OSSL_ASYNC_FD fd,
void *custom_data,
void (*cleanup)(ASYNC_WAIT_CTX *, const void *,
OSSL_ASYNC_FD, void *));
int ASYNC_WAIT_CTX_get_fd(ASYNC_WAIT_CTX *ctx, const void *key,
OSSL_ASYNC_FD *fd, void **custom_data);
int ASYNC_WAIT_CTX_get_all_fds(ASYNC_WAIT_CTX *ctx, OSSL_ASYNC_FD *fd,
size_t *numfds);
int ASYNC_WAIT_CTX_get_changed_fds(ASYNC_WAIT_CTX *ctx, OSSL_ASYNC_FD *addfd,
size_t *numaddfds, OSSL_ASYNC_FD *delfd,
size_t *numdelfds);
int ASYNC_WAIT_CTX_clear_fd(ASYNC_WAIT_CTX *ctx, const void *key);
=head1 DESCRIPTION
For an overview of how asynchronous operations are implemented in OpenSSL see
L<ASYNC_start_job(3)>. An ASYNC_WAIT_CTX object represents an asynchronous
"session", i.e. a related set of crypto operations. For example in SSL terms
this would have a one-to-one correspondence with an SSL connection.
Application code must create an ASYNC_WAIT_CTX using the ASYNC_WAIT_CTX_new()
function prior to calling ASYNC_start_job() (see L<ASYNC_start_job(3)>). When
the job is started it is associated with the ASYNC_WAIT_CTX for the duration of
that job. An ASYNC_WAIT_CTX should only be used for one ASYNC_JOB at any one
time, but can be reused after an ASYNC_JOB has finished for a subsequent
ASYNC_JOB. When the session is complete (e.g. the SSL connection is closed),
application code cleans up with ASYNC_WAIT_CTX_free().
ASYNC_WAIT_CTXs can have "wait" file descriptors associated with them. Calling
ASYNC_WAIT_CTX_get_all_fds() and passing in a pointer to an ASYNC_WAIT_CTX in
the B<ctx> parameter will return the wait file descriptors associated with that
job in B<*fd>. The number of file descriptors returned will be stored in
B<*numfds>. It is the caller's responsibility to ensure that sufficient memory
has been allocated in B<*fd> to receive all the file descriptors. Calling
ASYNC_WAIT_CTX_get_all_fds() with a NULL B<fd> value will return no file
descriptors but will still populate B<*numfds>. Therefore application code is
typically expected to call this function twice: once to get the number of fds,
and then again when sufficient memory has been allocated. If only one
asynchronous engine is being used then normally this call will only ever return
one fd. If multiple asynchronous engines are being used then more could be
returned.
The function ASYNC_WAIT_CTX_get_changed_fds() can be used to detect if any fds
have changed since the last call time ASYNC_start_job() returned an ASYNC_PAUSE
result (or since the ASYNC_WAIT_CTX was created if no ASYNC_PAUSE result has
been received). The B<numaddfds> and B<numdelfds> parameters will be populated
with the number of fds added or deleted respectively. B<*addfd> and B<*delfd>
will be populated with the list of added and deleted fds respectively. Similarly
to ASYNC_WAIT_CTX_get_all_fds() either of these can be NULL, but if they are not
NULL then the caller is responsible for ensuring sufficient memory is allocated.
Implementors of async aware code (e.g. engines) are encouraged to return a
stable fd for the lifetime of the ASYNC_WAIT_CTX in order to reduce the "churn"
of regularly changing fds - although no guarantees of this are provided to
applications.
Applications can wait for the file descriptor to be ready for "read" using a
system function call such as select or poll (being ready for "read" indicates
that the job should be resumed). If no file descriptor is made available then an
application will have to periodically "poll" the job by attempting to restart it
to see if it is ready to continue.
Async aware code (e.g. engines) can get the current ASYNC_WAIT_CTX from the job
via L<ASYNC_get_wait_ctx(3)> and provide a file descriptor to use for waiting
on by calling ASYNC_WAIT_CTX_set_wait_fd(). Typically this would be done by an
engine immediately prior to calling ASYNC_pause_job() and not by end user code.
An existing association with a file descriptor can be obtained using
ASYNC_WAIT_CTX_get_fd() and cleared using ASYNC_WAIT_CTX_clear_fd(). Both of
these functions requires a B<key> value which is unique to the async aware
code. This could be any unique value but a good candidate might be the
B<ENGINE *> for the engine. The B<custom_data> parameter can be any value, and
will be returned in a subsequent call to ASYNC_WAIT_CTX_get_fd(). The
ASYNC_WAIT_CTX_set_wait_fd() function also expects a pointer to a "cleanup"
routine. This can be NULL but if provided will automatically get called when
the ASYNC_WAIT_CTX is freed, and gives the engine the opportunity to close the
fd or any other resources. Note: The "cleanup" routine does not get called if
the fd is cleared directly via a call to ASYNC_WAIT_CTX_clear_fd().
An example of typical usage might be an async capable engine. User code would
initiate cryptographic operations. The engine would initiate those operations
asynchronously and then call ASYNC_WAIT_CTX_set_wait_fd() followed by
ASYNC_pause_job() to return control to the user code. The user code can then
perform other tasks or wait for the job to be ready by calling "select" or other
similar function on the wait file descriptor. The engine can signal to the user
code that the job should be resumed by making the wait file descriptor
"readable". Once resumed the engine should clear the wake signal on the wait
file descriptor.
=head1 RETURN VALUES
ASYNC_WAIT_CTX_new() returns a pointer to the newly allocated ASYNC_WAIT_CTX or
NULL on error.
ASYNC_WAIT_CTX_set_wait_fd, ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds,
ASYNC_WAIT_CTX_get_changed_fds and ASYNC_WAIT_CTX_clear_fd all return 1 on
success or 0 on error.
=head1 NOTES
On Windows platforms the openssl/async.h header is dependent on some
of the types customarily made available by including windows.h. The
application developer is likely to require control over when the latter
is included, commonly as one of the first included headers. Therefore
it is defined as an application developer's responsibility to include
windows.h prior to async.h.
=head1 SEE ALSO
L<crypto(3)>, L<ASYNC_start_job(3)>
=head1 HISTORY
ASYNC_WAIT_CTX_new, ASYNC_WAIT_CTX_free, ASYNC_WAIT_CTX_set_wait_fd,
ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds,
ASYNC_WAIT_CTX_get_changed_fds, ASYNC_WAIT_CTX_clear_fd were first added to
OpenSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

330
doc/crypto/ASYNC_start_job.pod Normal file
View File

@@ -0,0 +1,330 @@
=pod
=head1 NAME
ASYNC_get_wait_ctx,
ASYNC_init_thread, ASYNC_cleanup_thread, ASYNC_start_job, ASYNC_pause_job,
ASYNC_get_current_job, ASYNC_block_pause, ASYNC_unblock_pause, ASYNC_is_capable
- asynchronous job management functions
=head1 SYNOPSIS
#include <openssl/async.h>
int ASYNC_init_thread(size_t max_size, size_t init_size);
void ASYNC_cleanup_thread(void);
int ASYNC_start_job(ASYNC_JOB **job, ASYNC_WAIT_CTX *ctx, int *ret,
int (*func)(void *), void *args, size_t size);
int ASYNC_pause_job(void);
ASYNC_JOB *ASYNC_get_current_job(void);
ASYNC_WAIT_CTX *ASYNC_get_wait_ctx(ASYNC_JOB *job);
void ASYNC_block_pause(void);
void ASYNC_unblock_pause(void);
int ASYNC_is_capable(void);
=head1 DESCRIPTION
OpenSSL implements asynchronous capabilities through an ASYNC_JOB. This
represents code that can be started and executes until some event occurs. At
that point the code can be paused and control returns to user code until some
subsequent event indicates that the job can be resumed.
The creation of an ASYNC_JOB is a relatively expensive operation. Therefore, for
efficiency reasons, jobs can be created up front and reused many times. They are
held in a pool until they are needed, at which point they are removed from the
pool, used, and then returned to the pool when the job completes. If the user
application is multi-threaded, then ASYNC_init_thread() may be called for each
thread that will initiate asynchronous jobs. Before
user code exits per-thread resources need to be cleaned up. This will normally
occur automatically (see L<OPENSSL_init_crypto(3)>) but may be explicitly
initiated by using ASYNC_cleanup_thread(). No asynchronous jobs must be
outstanding for the thread when ASYNC_cleanup_thread() is called. Failing to
ensure this will result in memory leaks.
The B<max_size> argument limits the number of ASYNC_JOBs that will be held in
the pool. If B<max_size> is set to 0 then no upper limit is set. When an
ASYNC_JOB is needed but there are none available in the pool already then one
will be automatically created, as long as the total of ASYNC_JOBs managed by the
pool does not exceed B<max_size>. When the pool is first initialised
B<init_size> ASYNC_JOBs will be created immediately. If ASYNC_init_thread() is
not called before the pool is first used then it will be called automatically
with a B<max_size> of 0 (no upper limit) and an B<init_size> of 0 (no ASYNC_JOBs
created up front).
An asynchronous job is started by calling the ASYNC_start_job() function.
Initially B<*job> should be NULL. B<ctx> should point to an ASYNC_WAIT_CTX
object created through the L<ASYNC_WAIT_CTX_new(3)> function. B<ret> should
point to a location where the return value of the asynchronous function should
be stored on completion of the job. B<func> represents the function that should
be started asynchronously. The data pointed to by B<args> and of size B<size>
will be copied and then passed as an argument to B<func> when the job starts.
ASYNC_start_job will return one of the following values:
=over 4
=item B<ASYNC_ERR>
An error occurred trying to start the job. Check the OpenSSL error queue (e.g.
see L<ERR_print_errors(3)>) for more details.
=item B<ASYNC_NO_JOBS>
There are no jobs currently available in the pool. This call can be retried
again at a later time.
=item B<ASYNC_PAUSE>
The job was successfully started but was "paused" before it completed (see
ASYNC_pause_job() below). A handle to the job is placed in B<*job>. Other work
can be performed (if desired) and the job restarted at a later time. To restart
a job call ASYNC_start_job() again passing the job handle in B<*job>. The
B<func>, B<args> and B<size> parameters will be ignored when restarting a job.
When restarting a job ASYNC_start_job() B<must> be called from the same thread
that the job was originally started from.
=item B<ASYNC_FINISH>
The job completed. B<*job> will be NULL and the return value from B<func> will
be placed in B<*ret>.
=back
At any one time there can be a maximum of one job actively running per thread
(you can have many that are paused). ASYNC_get_current_job() can be used to get
a pointer to the currently executing ASYNC_JOB. If no job is currently executing
then this will return NULL.
If executing within the context of a job (i.e. having been called directly or
indirectly by the function "func" passed as an argument to ASYNC_start_job())
then ASYNC_pause_job() will immediately return control to the calling
application with ASYNC_PAUSE returned from the ASYNC_start_job() call. A
subsequent call to ASYNC_start_job passing in the relevant ASYNC_JOB in the
B<*job> parameter will resume execution from the ASYNC_pause_job() call. If
ASYNC_pause_job() is called whilst not within the context of a job then no
action is taken and ASYNC_pause_job() returns immediately.
ASYNC_get_wait_ctx() can be used to get a pointer to the ASYNC_WAIT_CTX
for the B<job>. ASYNC_WAIT_CTXs can have a "wait" file descriptor associated
with them. Applications can wait for the file descriptor to be ready for "read"
using a system function call such as select or poll (being ready for "read"
indicates that the job should be resumed). If no file descriptor is made
available then an application will have to periodically "poll" the job by
attempting to restart it to see if it is ready to continue.
An example of typical usage might be an async capable engine. User code would
initiate cryptographic operations. The engine would initiate those operations
asynchronously and then call L<ASYNC_WAIT_CTX_set_wait_fd(3)> followed by
ASYNC_pause_job() to return control to the user code. The user code can then
perform other tasks or wait for the job to be ready by calling "select" or other
similar function on the wait file descriptor. The engine can signal to the user
code that the job should be resumed by making the wait file descriptor
"readable". Once resumed the engine should clear the wake signal on the wait
file descriptor.
The ASYNC_block_pause() function will prevent the currently active job from
pausing. The block will remain in place until a subsequent call to
ASYNC_unblock_pause(). These functions can be nested, e.g. if you call
ASYNC_block_pause() twice then you must call ASYNC_unblock_pause() twice in
order to re-enable pausing. If these functions are called while there is no
currently active job then they have no effect. This functionality can be useful
to avoid deadlock scenarios. For example during the execution of an ASYNC_JOB an
application acquires a lock. It then calls some cryptographic function which
invokes ASYNC_pause_job(). This returns control back to the code that created
the ASYNC_JOB. If that code then attempts to acquire the same lock before
resuming the original job then a deadlock can occur. By calling
ASYNC_block_pause() immediately after acquiring the lock and
ASYNC_unblock_pause() immediately before releasing it then this situation cannot
occur.
Some platforms cannot support async operations. The ASYNC_is_capable() function
can be used to detect whether the current platform is async capable or not.
=head1 RETURN VALUES
ASYNC_init_thread returns 1 on success or 0 otherwise.
ASYNC_start_job returns one of ASYNC_ERR, ASYNC_NO_JOBS, ASYNC_PAUSE or
ASYNC_FINISH as described above.
ASYNC_pause_job returns 0 if an error occurred or 1 on success. If called when
not within the context of an ASYNC_JOB then this is counted as success so 1 is
returned.
ASYNC_get_current_job returns a pointer to the currently executing ASYNC_JOB or
NULL if not within the context of a job.
ASYNC_get_wait_ctx() returns a pointer to the ASYNC_WAIT_CTX for the job.
ASYNC_is_capable() returns 1 if the current platform is async capable or 0
otherwise.
=head1 NOTES
On Windows platforms the openssl/async.h header is dependent on some
of the types customarily made available by including windows.h. The
application developer is likely to require control over when the latter
is included, commonly as one of the first included headers. Therefore
it is defined as an application developer's responsibility to include
windows.h prior to async.h.
=head1 EXAMPLE
The following example demonstrates how to use most of the core async APIs:
#ifdef _WIN32
# include <windows.h>
#endif
#include <stdio.h>
#include <unistd.h>
#include <openssl/async.h>
#include <openssl/crypto.h>
int unique = 0;
void cleanup(ASYNC_WAIT_CTX *ctx, const void *key, OSSL_ASYNC_FD r, void *vw)
{
OSSL_ASYNC_FD *w = (OSSL_ASYNC_FD *)vw;
close(r);
close(*w);
OPENSSL_free(w);
}
int jobfunc(void *arg)
{
ASYNC_JOB *currjob;
unsigned char *msg;
int pipefds[2] = {0, 0};
OSSL_ASYNC_FD *wptr;
char buf = 'X';
currjob = ASYNC_get_current_job();
if (currjob != NULL) {
printf("Executing within a job\n");
} else {
printf("Not executing within a job - should not happen\n");
return 0;
}
msg = (unsigned char *)arg;
printf("Passed in message is: %s\n", msg);
if (pipe(pipefds) != 0) {
printf("Failed to create pipe\n");
return 0;
}
wptr = OPENSSL_malloc(sizeof(OSSL_ASYNC_FD));
if (wptr == NULL) {
printf("Failed to malloc\n");
return 0;
}
*wptr = pipefds[1];
ASYNC_WAIT_CTX_set_wait_fd(ASYNC_get_wait_ctx(currjob), &unique,
pipefds[0], wptr, cleanup);
/*
* Normally some external event would cause this to happen at some
* later point - but we do it here for demo purposes, i.e.
* immediately signalling that the job is ready to be woken up after
* we return to main via ASYNC_pause_job().
*/
write(pipefds[1], &buf, 1);
/* Return control back to main */
ASYNC_pause_job();
/* Clear the wake signal */
read(pipefds[0], &buf, 1);
printf ("Resumed the job after a pause\n");
return 1;
}
int main(void)
{
ASYNC_JOB *job = NULL;
ASYNC_WAIT_CTX *ctx = NULL;
int ret;
OSSL_ASYNC_FD waitfd;
fd_set waitfdset;
size_t numfds;
unsigned char msg[13] = "Hello world!";
printf("Starting...\n");
ctx = ASYNC_WAIT_CTX_new();
if (ctx == NULL) {
printf("Failed to create ASYNC_WAIT_CTX\n");
abort();
}
for (;;) {
switch(ASYNC_start_job(&job, ctx, &ret, jobfunc, msg, sizeof(msg))) {
case ASYNC_ERR:
case ASYNC_NO_JOBS:
printf("An error occurred\n");
goto end;
case ASYNC_PAUSE:
printf("Job was paused\n");
break;
case ASYNC_FINISH:
printf("Job finished with return value %d\n", ret);
goto end;
}
/* Wait for the job to be woken */
printf("Waiting for the job to be woken up\n");
if (!ASYNC_WAIT_CTX_get_all_fds(ctx, NULL, &numfds)
|| numfds > 1) {
printf("Unexpected number of fds\n");
abort();
}
ASYNC_WAIT_CTX_get_all_fds(ctx, &waitfd, &numfds);
FD_ZERO(&waitfdset);
FD_SET(waitfd, &waitfdset);
select(waitfd + 1, &waitfdset, NULL, NULL, NULL);
}
end:
ASYNC_WAIT_CTX_free(ctx);
printf("Finishing\n");
return 0;
}
The expected output from executing the above example program is:
Starting...
Executing within a job
Passed in message is: Hello world!
Job was paused
Waiting for the job to be woken up
Resumed the job after a pause
Job finished with return value 1
Finishing
=head1 SEE ALSO
L<crypto(3)>, L<ERR_print_errors(3)>
=head1 HISTORY
ASYNC_init_thread, ASYNC_cleanup_thread,
ASYNC_start_job, ASYNC_pause_job, ASYNC_get_current_job, ASYNC_get_wait_ctx(),
ASYNC_block_pause(), ASYNC_unblock_pause() and ASYNC_is_capable() were first
added to OpenSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

33
doc/crypto/blowfish.pod → doc/crypto/BF_encrypt.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
blowfish, BF_set_key, BF_encrypt, BF_decrypt, BF_ecb_encrypt, BF_cbc_encrypt,
BF_set_key, BF_encrypt, BF_decrypt, BF_ecb_encrypt, BF_cbc_encrypt,
BF_cfb64_encrypt, BF_ofb64_encrypt, BF_options - Blowfish encryption
=head1 SYNOPSIS
@@ -14,16 +14,16 @@ BF_cfb64_encrypt, BF_ofb64_encrypt, BF_options - Blowfish encryption
void BF_ecb_encrypt(const unsigned char *in, unsigned char *out,
BF_KEY *key, int enc);
void BF_cbc_encrypt(const unsigned char *in, unsigned char *out,
long length, BF_KEY *schedule, unsigned char *ivec, int enc);
long length, BF_KEY *schedule, unsigned char *ivec, int enc);
void BF_cfb64_encrypt(const unsigned char *in, unsigned char *out,
long length, BF_KEY *schedule, unsigned char *ivec, int *num,
long length, BF_KEY *schedule, unsigned char *ivec, int *num,
int enc);
void BF_ofb64_encrypt(const unsigned char *in, unsigned char *out,
long length, BF_KEY *schedule, unsigned char *ivec, int *num);
long length, BF_KEY *schedule, unsigned char *ivec, int *num);
const char *BF_options(void);
void BF_encrypt(BF_LONG *data,const BF_KEY *key);
void BF_decrypt(BF_LONG *data,const BF_KEY *key);
void BF_encrypt(BF_LONG *data, const BF_KEY *key);
void BF_decrypt(BF_LONG *data, const BF_KEY *key);
=head1 DESCRIPTION
@@ -33,7 +33,7 @@ by Counterpane (see http://www.counterpane.com/blowfish.html ).
Blowfish is a block cipher that operates on 64 bit (8 byte) blocks of data.
It uses a variable size key, but typically, 128 bit (16 byte) keys are
considered good for strong encryption. Blowfish can be used in the same
modes as DES (see L<des_modes(7)|des_modes(7)>). Blowfish is currently one
modes as DES (see L<des_modes(7)>). Blowfish is currently one
of the faster block ciphers. It is quite a bit faster than DES, and much
faster than IDEA or RC2.
@@ -52,7 +52,7 @@ everything after the first 64 bits is ignored.
The mode functions BF_cbc_encrypt(), BF_cfb64_encrypt() and BF_ofb64_encrypt()
all operate on variable length data. They all take an initialization vector
B<ivec> which needs to be passed along into the next call of the same function
B<ivec> which needs to be passed along into the next call of the same function
for the same message. B<ivec> may be initialized with anything, but the
recipient needs to know what it was initialized with, or it won't be able
to decrypt. Some programs and protocols simplify this, like SSH, where
@@ -97,16 +97,21 @@ None of the functions presented here return any value.
=head1 NOTE
Applications should use the higher level functions
L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> etc. instead of calling the
blowfish functions directly.
L<EVP_EncryptInit(3)> etc. instead of calling these
functions directly.
=head1 SEE ALSO
L<des_modes(7)|des_modes(7)>
L<EVP_EncryptInit(3)>,
L<des_modes(7)>
=head1 HISTORY
=head1 COPYRIGHT
The Blowfish functions are available in all versions of SSLeay and OpenSSL.
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

125
doc/crypto/BIO_ADDR.pod Normal file
View File

@@ -0,0 +1,125 @@
=pod
=head1 NAME
BIO_ADDR, BIO_ADDR_new, BIO_ADDR_clear, BIO_ADDR_free, BIO_ADDR_rawmake,
BIO_ADDR_family, BIO_ADDR_rawaddress, BIO_ADDR_rawport,
BIO_ADDR_hostname_string, BIO_ADDR_service_string,
BIO_ADDR_path_string - BIO_ADDR routines
=head1 SYNOPSIS
#include <sys/types.h>
#include <openssl/bio.h>
typedef union bio_addr_st BIO_ADDR;
BIO_ADDR *BIO_ADDR_new(void);
void BIO_ADDR_free(BIO_ADDR *);
void BIO_ADDR_clear(BIO_ADDR *ap);
int BIO_ADDR_rawmake(BIO_ADDR *ap, int family,
const void *where, size_t wherelen, unsigned short port);
int BIO_ADDR_family(const BIO_ADDR *ap);
int BIO_ADDR_rawaddress(const BIO_ADDR *ap, void *p, size_t *l);
unsigned short BIO_ADDR_rawport(const BIO_ADDR *ap);
char *BIO_ADDR_hostname_string(const BIO_ADDR *ap, int numeric);
char *BIO_ADDR_service_string(const BIO_ADDR *ap, int numeric);
char *BIO_ADDR_path_string(const BIO_ADDR *ap);
=head1 DESCRIPTION
The B<BIO_ADDR> type is a wrapper around all types of socket
addresses that OpenSSL deals with, currently transparently
supporting AF_INET, AF_INET6 and AF_UNIX according to what's
available on the platform at hand.
BIO_ADDR_new() creates a new unfilled B<BIO_ADDR>, to be used
with routines that will fill it with information, such as
BIO_accept_ex().
BIO_ADDR_free() frees a B<BIO_ADDR> created with BIO_ADDR_new().
BIO_ADDR_clear() clears any data held within the provided B<BIO_ADDR> and sets
it back to an uninitialised state.
BIO_ADDR_rawmake() takes a protocol B<family>, an byte array of
size B<wherelen> with an address in network byte order pointed at
by B<where> and a port number in network byte order in B<port> (except
for the B<AF_UNIX> protocol family, where B<port> is meaningless and
therefore ignored) and populates the given B<BIO_ADDR> with them.
In case this creates a B<AF_UNIX> B<BIO_ADDR>, B<wherelen> is expected
to be the length of the path string (not including the terminating
NUL, such as the result of a call to strlen()).
I<Read on about the addresses in L</RAW ADDRESSES> below>.
BIO_ADDR_family() returns the protocol family of the given
B<BIO_ADDR>. The possible non-error results are one of the
constants AF_INET, AF_INET6 and AF_UNIX. It will also return AF_UNSPEC if the
BIO_ADDR has not been initialised.
BIO_ADDR_rawaddress() will write the raw address of the given
B<BIO_ADDR> in the area pointed at by B<p> if B<p> is non-NULL,
and will set B<*l> to be the amount of bytes the raw address
takes up if B<l> is non-NULL.
A technique to only find out the size of the address is a call
with B<p> set to B<NULL>. The raw address will be in network byte
order, most significant byte first.
In case this is a B<AF_UNIX> B<BIO_ADDR>, B<l> gets the length of the
path string (not including the terminating NUL, such as the result of
a call to strlen()).
I<Read on about the addresses in L</RAW ADDRESSES> below>.
BIO_ADDR_rawport() returns the raw port of the given B<BIO_ADDR>.
The raw port will be in network byte order.
BIO_ADDR_hostname_string() returns a character string with the
hostname of the given B<BIO_ADDR>. If B<numeric> is 1, the string
will contain the numerical form of the address. This only works for
B<BIO_ADDR> of the protocol families AF_INET and AF_INET6. The
returned string has been allocated on the heap and must be freed
with OPENSSL_free().
BIO_ADDR_service_string() returns a character string with the
service name of the port of the given B<BIO_ADDR>. If B<numeric>
is 1, the string will contain the port number. This only works
for B<BIO_ADDR> of the protocol families AF_INET and AF_INET6. The
returned string has been allocated on the heap and must be freed
with OPENSSL_free().
BIO_ADDR_path_string() returns a character string with the path
of the given B<BIO_ADDR>. This only works for B<BIO_ADDR> of the
protocol family AF_UNIX. The returned string has been allocated
on the heap and must be freed with OPENSSL_free().
=head1 RAW ADDRESSES
Both BIO_ADDR_rawmake() and BIO_ADDR_rawaddress() take a pointer to a
network byte order address of a specific site. Internally, those are
treated as a pointer to B<struct in_addr> (for B<AF_INET>), B<struct
in6_addr> (for B<AF_INET6>) or B<char *> (for B<AF_UNIX>), all
depending on the protocol family the address is for.
=head1 RETURN VALUES
The string producing functions BIO_ADDR_hostname_string(),
BIO_ADDR_service_string() and BIO_ADDR_path_string() will
return B<NULL> on error and leave an error indication on the
OpenSSL error stack.
All other functions described here return 0 or B<NULL> when the
information they should return isn't available.
=head1 SEE ALSO
L<BIO_connect(3)>, L<BIO_s_connect(3)>
=head1 COPYRIGHT
Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

91
doc/crypto/BIO_ADDRINFO.pod Normal file
View File

@@ -0,0 +1,91 @@
=pod
=head1 NAME
BIO_lookup_type,
BIO_ADDRINFO, BIO_ADDRINFO_next, BIO_ADDRINFO_free,
BIO_ADDRINFO_family, BIO_ADDRINFO_socktype, BIO_ADDRINFO_protocol,
BIO_ADDRINFO_address,
BIO_lookup
- BIO_ADDRINFO type and routines
=head1 SYNOPSIS
#include <sys/types.h>
#include <openssl/bio.h>
typedef union bio_addrinfo_st BIO_ADDRINFO;
enum BIO_lookup_type {
BIO_LOOKUP_CLIENT, BIO_LOOKUP_SERVER
};
int BIO_lookup(const char *node, const char *service,
enum BIO_lookup_type lookup_type,
int family, int socktype, BIO_ADDRINFO **res);
const BIO_ADDRINFO *BIO_ADDRINFO_next(const BIO_ADDRINFO *bai);
int BIO_ADDRINFO_family(const BIO_ADDRINFO *bai);
int BIO_ADDRINFO_socktype(const BIO_ADDRINFO *bai);
int BIO_ADDRINFO_protocol(const BIO_ADDRINFO *bai);
const BIO_ADDR *BIO_ADDRINFO_address(const BIO_ADDRINFO *bai);
void BIO_ADDRINFO_free(BIO_ADDRINFO *bai);
=head1 DESCRIPTION
The B<BIO_ADDRINFO> type is a wrapper for address information
types provided on your platform.
B<BIO_ADDRINFO> normally forms a chain of several that can be
picked at one by one.
BIO_lookup() looks up a specified B<host> and B<service>, and
uses B<lookup_type> to determine what the default address should
be if B<host> is B<NULL>. B<family>, B<socktype> are used to
determine what protocol family and protocol should be used for
the lookup. B<family> can be any of AF_INET, AF_INET6, AF_UNIX and
AF_UNSPEC, and B<socktype> can be SOCK_STREAM or SOCK_DGRAM.
B<res> points at a pointer to hold the start of a B<BIO_ADDRINFO>
chain.
For the family B<AF_UNIX>, BIO_lookup() will ignore the B<service>
parameter and expects the B<node> parameter to hold the path to the
socket file.
BIO_ADDRINFO_family() returns the family of the given
B<BIO_ADDRINFO>. The result will be one of the constants
AF_INET, AF_INET6 and AF_UNIX.
BIO_ADDRINFO_socktype() returns the socket type of the given
B<BIO_ADDRINFO>. The result will be one of the constants
SOCK_STREAM and SOCK_DGRAM.
BIO_ADDRINFO_protocol() returns the protocol id of the given
B<BIO_ADDRINFO>. The result will be one of the constants
IPPROTO_TCP and IPPROTO_UDP.
BIO_ADDRINFO_address() returns the underlying B<BIO_ADDR>
of the given B<BIO_ADDRINFO>.
BIO_ADDRINFO_next() returns the next B<BIO_ADDRINFO> in the chain
from the given one.
BIO_ADDRINFO_free() frees the chain of B<BIO_ADDRINFO> starting
with the given one.
=head1 RETURN VALUES
BIO_lookup() returns 1 on success and 0 when an error occurred, and
will leave an error indication on the OpenSSL error stack in that case.
All other functions described here return 0 or B<NULL> when the
information they should return isn't available.
=head1 COPYRIGHT
Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

112
doc/crypto/BIO_connect.pod Normal file
View File

@@ -0,0 +1,112 @@
=pod
=head1 NAME
BIO_socket, BIO_connect, BIO_listen, BIO_accept_ex, BIO_closesocket - BIO
socket communication setup routines
=head1 SYNOPSIS
#include <openssl/bio.h>
int BIO_socket(int domain, int socktype, int protocol, int options);
int BIO_connect(int sock, const BIO_ADDR *addr, int options);
int BIO_listen(int sock, const BIO_ADDR *addr, int options);
int BIO_accept_ex(int accept_sock, BIO_ADDR *peer, int options);
int BIO_closesocket(int sock);
=head1 DESCRIPTION
BIO_socket() creates a socket in the domain B<domain>, of type
B<socktype> and B<protocol>. Socket B<options> are currently unused,
but is present for future use.
BIO_connect() connects B<sock> to the address and service given by
B<addr>. Connection B<options> may be zero or any combination of
B<BIO_SOCK_KEEPALIVE>, B<BIO_SOCK_NONBLOCK> and B<BIO_SOCK_NODELAY>.
The flags are described in L</FLAGS> below.
BIO_listen() has B<sock> start listening on the address and service
given by B<addr>. Connection B<options> may be zero or any
combination of B<BIO_SOCK_KEEPALIVE>, B<BIO_SOCK_NONBLOCK>,
B<BIO_SOCK_NODELAY>, B<BIO_SOCK_REUSEADDR> and B<BIO_SOCK_V6_ONLY>.
The flags are described in L</FLAGS> below.
BIO_accept_ex() waits for an incoming connections on the given
socket B<accept_sock>. When it gets a connection, the address and
port of the peer gets stored in B<peer> if that one is non-NULL.
Accept B<options> may be zero or B<BIO_SOCK_NONBLOCK>, and is applied
on the accepted socket. The flags are described in L</FLAGS> below.
BIO_closesocket() closes B<sock>.
=head1 FLAGS
=over 4
=item BIO_SOCK_KEEPALIVE
Enables regular sending of keep-alive messages.
=item BIO_SOCK_NONBLOCK
Sets the socket to non-blocking mode.
=item BIO_SOCK_NODELAY
Corresponds to B<TCP_NODELAY>, and disables the Nagle algorithm. With
this set, any data will be sent as soon as possible instead of being
buffered until there's enough for the socket to send out in one go.
=item BIO_SOCK_REUSEADDR
Try to reuse the address and port combination for a recently closed
port.
=item BIO_SOCK_V6_ONLY
When creating an IPv6 socket, make it only listen for IPv6 addresses
and not IPv4 addresses mapped to IPv6.
=back
These flags are bit flags, so they are to be combined with the
C<|> operator, for example:
BIO_connect(sock, addr, BIO_SOCK_KEEPALIVE | BIO_SOCK_NONBLOCK);
=head1 RETURN VALUES
BIO_socket() returns the socket number on success or B<INVALID_SOCKET>
(-1) on error. When an error has occurred, the OpenSSL error stack
will hold the error data and errno has the system error.
BIO_connect() and BIO_listen() return 1 on success or 0 on error.
When an error has occurred, the OpenSSL error stack will hold the error
data and errno has the system error.
BIO_accept_ex() returns the accepted socket on success or
B<INVALID_SOCKET> (-1) on error. When an error has occurred, the
OpenSSL error stack will hold the error data and errno has the system
error.
=head1 HISTORY
BIO_gethostname(), BIO_get_port(), BIO_get_host_ip(),
BIO_get_accept_socket() and BIO_accept() are deprecated since OpenSSL
1.1. Use the functions described above instead.
=head1 SEE ALSO
L<BIO_ADDR(3)>
=head1 COPYRIGHT
Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

36
doc/crypto/BIO_ctrl.pod
View File

@@ -5,33 +5,34 @@
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
BIO_get_info_callback, BIO_set_info_callback, bio_info_cb
- 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);
typedef void (*bio_info_cb)(BIO *b, int oper, const char *ptr, int arg1, long arg2, long arg3);
long BIO_ctrl(BIO *bp, int cmd, long larg, void *parg);
long BIO_callback_ctrl(BIO *b, int cmd, bio_info_cb cb);
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_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);
int BIO_get_info_callback(BIO *b, bio_info_cb **cbp);
int BIO_set_info_callback(BIO *b, bio_info_cb *cb);
=head1 DESCRIPTION
@@ -94,7 +95,7 @@ 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().
that the call should be retried later in a similar manner to BIO_write_ex().
The BIO_should_retry() call should be used and appropriate action taken
is the call fails.
@@ -121,8 +122,15 @@ operation.
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.
the case of BIO_seek() on a file BIO for a successful operation.
=head1 SEE ALSO
=head1 COPYRIGHT
TBA
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

21
doc/crypto/BIO_f_base64.pod
View File

@@ -4,12 +4,14 @@
BIO_f_base64 - base64 BIO filter
=for comment multiple includes
=head1 SYNOPSIS
#include <openssl/bio.h>
#include <openssl/evp.h>
BIO_METHOD * BIO_f_base64(void);
const BIO_METHOD *BIO_f_base64(void);
=head1 DESCRIPTION
@@ -17,7 +19,7 @@ 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().
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
@@ -63,8 +65,8 @@ data to standard output:
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);
while((inlen = BIO_read(b64, inbuf, 512)) > 0)
BIO_write(bio_out, inbuf, inlen);
BIO_flush(bio_out);
BIO_free_all(b64);
@@ -77,6 +79,13 @@ 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
=head1 COPYRIGHT
TBA
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

44
doc/crypto/BIO_f_buffer.pod
View File

@@ -2,19 +2,25 @@
=head1 NAME
BIO_f_buffer - buffering BIO
BIO_get_buffer_num_lines,
BIO_set_read_buffer_size,
BIO_set_write_buffer_size,
BIO_set_buffer_size,
BIO_set_buffer_read_data,
BIO_f_buffer
- buffering BIO
=head1 SYNOPSIS
#include <openssl/bio.h>
BIO_METHOD * BIO_f_buffer(void);
const 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)
long BIO_get_buffer_num_lines(BIO *b);
long BIO_set_read_buffer_size(BIO *b, long size);
long BIO_set_write_buffer_size(BIO *b, long size);
long BIO_set_buffer_size(BIO *b, long size);
long BIO_set_buffer_read_data(BIO *b, void *buf, long num);
=head1 DESCRIPTION
@@ -41,6 +47,8 @@ is expanded.
=head1 NOTES
These functions, other than BIO_f_buffer(), are implemented as macros.
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
@@ -66,9 +74,19 @@ 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)>
L<BIO(3)>,
L<BIO_reset(3)>,
L<BIO_flush(3)>,
L<BIO_pop(3)>,
L<BIO_ctrl(3)>.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

23
doc/crypto/BIO_f_cipher.pod
View File

@@ -4,14 +4,16 @@
BIO_f_cipher, BIO_set_cipher, BIO_get_cipher_status, BIO_get_cipher_ctx - cipher BIO filter
=for comment multiple includes
=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);
const 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)
@@ -22,7 +24,7 @@ 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().
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
@@ -48,7 +50,7 @@ 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
When decrypting an error on the final block is signaled 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.
@@ -67,10 +69,13 @@ for failure.
BIO_get_cipher_ctx() currently always returns 1.
=head1 EXAMPLES
=head1 COPYRIGHT
TBA
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
=head1 SEE ALSO
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
TBA
=cut

56
doc/crypto/BIO_f_md.pod
View File

@@ -4,15 +4,17 @@
BIO_f_md, BIO_set_md, BIO_get_md, BIO_get_md_ctx - message digest BIO filter
=for comment multiple includes
=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);
const 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
@@ -58,10 +60,8 @@ 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
Calling BIO_get_md_ctx() will return the context and initialize the BIO
state. This allows applications to initialize the context externally
if the standard calls such as BIO_set_md() are not sufficiently flexible.
=head1 RETURN VALUES
@@ -105,9 +105,9 @@ The next example digests data by reading through a chain instead:
BIO_set_md(mdtmp, EVP_md5());
bio = BIO_push(mdtmp, bio);
do {
rdlen = BIO_read(bio, buf, sizeof(buf));
rdlen = BIO_read(bio, buf, sizeof(buf));
/* Might want to do something with the data here */
} while(rdlen > 0);
} 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.
@@ -116,18 +116,18 @@ outputs them. This could be used with the examples above.
unsigned char mdbuf[EVP_MAX_MD_SIZE];
int mdlen;
int i;
mdtmp = bio; /* Assume bio has previously been set up */
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);
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);
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);
@@ -139,6 +139,18 @@ 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
=head1 HISTORY
TBA
Before OpenSSL 1.0.0., the call to BIO_get_md_ctx() would only work if the
BIO was initialized first.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

13
doc/crypto/BIO_f_null.pod
View File

@@ -8,7 +8,7 @@ BIO_f_null - null filter
#include <openssl/bio.h>
BIO_METHOD * BIO_f_null(void);
const BIO_METHOD * BIO_f_null(void);
=head1 DESCRIPTION
@@ -27,6 +27,13 @@ As may be apparent a null filter BIO is not particularly useful.
BIO_f_null() returns the null filter BIO method.
=head1 SEE ALSO
=head1 COPYRIGHT
TBA
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

220
doc/crypto/BIO_f_ssl.pod
View File

@@ -2,41 +2,42 @@
=head1 NAME
BIO_f_ssl, BIO_set_ssl, BIO_get_ssl, BIO_set_ssl_mode, BIO_set_ssl_renegotiate_bytes,
BIO_do_handshake,
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
=for comment multiple includes
=head1 SYNOPSIS
#include <openssl/bio.h>
#include <openssl/ssl.h>
BIO_METHOD *BIO_f_ssl(void);
const 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);
long BIO_set_ssl(BIO *b, SSL *ssl, long c);
long BIO_get_ssl(BIO *b, SSL **sslp);
long BIO_set_ssl_mode(BIO *b, long client);
long BIO_set_ssl_renegotiate_bytes(BIO *b, long num);
long BIO_set_ssl_renegotiate_timeout(BIO *b, long seconds);
long BIO_get_num_renegotiates(BIO *b);
BIO *BIO_new_ssl(SSL_CTX *ctx,int client);
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);
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)
long BIO_do_handshake(BIO *b);
=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.
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
@@ -63,7 +64,7 @@ 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)
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.
@@ -84,7 +85,7 @@ 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_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.
@@ -110,7 +111,7 @@ 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
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.
@@ -124,15 +125,15 @@ 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
BIO_set_ssl(), BIO_get_ssl(), BIO_set_ssl_mode(),
BIO_set_ssl_renegotiate_bytes(), BIO_set_ssl_renegotiate_timeout(),
BIO_get_num_renegotiates(), and BIO_do_handshake() are implemented as macros.
=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)>.
unencrypted example in L<BIO_s_connect(3)>.
BIO *sbio, *out;
int len;
@@ -140,57 +141,48 @@ unencrypted example in L<BIO_s_connect(3)|BIO_s_connect(3)>.
SSL_CTX *ctx;
SSL *ssl;
ERR_load_crypto_strings();
ERR_load_SSL_strings();
OpenSSL_add_all_algorithms();
/* XXX Seed the PRNG if needed. */
/* We would seed the PRNG here if the platform didn't
* do it automatically
*/
ctx = SSL_CTX_new(TLS_client_method());
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.
*/
/* XXX Set verify paths and mode here. */
sbio = BIO_new_ssl_connect(ctx);
BIO_get_ssl(sbio, &ssl);
if(!ssl) {
fprintf(stderr, "Can't locate SSL pointer\n");
/* whatever ... */
if (ssl == NULL) {
fprintf(stderr, "Can't locate SSL pointer\n");
ERR_print_errors_fp(stderr);
exit(1);
}
/* Don't want any retries */
SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY);
/* We might want to do other things with ssl here */
/* XXX We might want to do other things with ssl here */
BIO_set_conn_hostname(sbio, "localhost:https");
/* An empty host part means the loopback address */
BIO_set_conn_hostname(sbio, ":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_connect(sbio) <= 0) {
fprintf(stderr, "Error connecting to server\n");
ERR_print_errors_fp(stderr);
exit(1);
}
if (BIO_do_handshake(sbio) <= 0) {
fprintf(stderr, "Error establishing SSL connection\n");
ERR_print_errors_fp(stderr);
exit(1);
}
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 */
/* XXX 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);
for ( ; ; ) {
len = BIO_read(sbio, tmpbuf, 1024);
if (len <= 0)
break;
BIO_write(out, tmpbuf, len);
}
BIO_free_all(sbio);
BIO_free(out);
@@ -206,106 +198,83 @@ a client and also echoes the request to standard output.
SSL_CTX *ctx;
SSL *ssl;
ERR_load_crypto_strings();
ERR_load_SSL_strings();
OpenSSL_add_all_algorithms();
/* XXX Seed the PRNG if needed. */
/* 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;
ctx = SSL_CTX_new(TLS_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);
exit(1);
}
/* Might do other things here like setting verify locations and
* DH and/or RSA temporary key callbacks
*/
/* XXX Other things like set verify locations, EDH temp callbacks. */
/* New SSL BIO setup as server */
sbio=BIO_new_ssl(ctx,0);
sbio = BIO_new_ssl(ctx, 0);
BIO_get_ssl(sbio, &ssl);
if(!ssl) {
fprintf(stderr, "Can't locate SSL pointer\n");
/* whatever ... */
if (ssl == NULL) {
fprintf(stderr, "Can't locate SSL pointer\n");
ERR_print_errors_fp(stderr);
exit(1);
}
/* 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");
acpt=BIO_new_accept("4433");
/* By doing this when a new connection is established
/*
* 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.
* will be freed when the accept BIO is freed.
*/
BIO_set_accept_bios(acpt,sbio);
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;
if (BIO_do_accept(acpt) <= 0) {
fprintf(stderr, "Error setting up accept BIO\n");
ERR_print_errors_fp(stderr);
exit(1);
}
/* Now wait for incoming connection */
if(BIO_do_accept(acpt) <= 0) {
fprintf(stderr, "Error in connection\n");
ERR_print_errors_fp(stderr);
return 0;
if (BIO_do_accept(acpt) <= 0) {
fprintf(stderr, "Error in connection\n");
ERR_print_errors_fp(stderr);
exit(1);
}
/* We only want one connection so remove and free
* accept BIO
*/
/* 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;
if (BIO_do_handshake(sbio) <= 0) {
fprintf(stderr, "Error in SSL handshake\n");
ERR_print_errors_fp(stderr);
exit(1);
}
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;
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
@@ -317,6 +286,13 @@ 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
=head1 COPYRIGHT
TBA
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

77
doc/crypto/BIO_find_type.pod
View File

@@ -8,46 +8,23 @@ BIO_find_type, BIO_next, BIO_method_type - BIO chain traversal
#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
BIO *BIO_find_type(BIO *b, int bio_type);
BIO *BIO_next(BIO *b);
int BIO_method_type(const BIO *b);
=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
at BIO B<b>. If B<type> is a specific type (such as B<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.
The following general types are defined:
B<BIO_TYPE_DESCRIPTOR>, B<BIO_TYPE_FILTER>, and B<BIO_TYPE_SOURCE_SINK>.
For a list of the specific types, see the B<openssl/bio.h> header file.
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
@@ -63,36 +40,30 @@ 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 */
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_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);
btmp = BIO_next(btmp);
} while (btmp);
=head1 SEE ALSO
=head1 COPYRIGHT
TBA
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

65
doc/crypto/BIO_get_data.pod Normal file
View File

@@ -0,0 +1,65 @@
=pod
=head1 NAME
BIO_set_data, BIO_get_data, BIO_set_init, BIO_get_init, BIO_set_shutdown,
BIO_get_shutdown - functions for managing BIO state information
=head1 SYNOPSIS
#include <openssl/bio.h>
void BIO_set_data(BIO *a, void *ptr);
void *BIO_get_data(BIO *a);
void BIO_set_init(BIO *a, int init);
int BIO_get_init(BIO *a);
void BIO_set_shutdown(BIO *a, int shut);
int BIO_get_shutdown(BIO *a);
=head1 DESCRIPTION
These functions are mainly useful when implementing a custom BIO.
The BIO_set_data() function associates the custom data pointed to by B<ptr> with
the BIO. This data can subsequently be retrieved via a call to BIO_get_data().
This can be used by custom BIOs for storing implementation specific information.
The BIO_set_init() function sets the value of the BIO's "init" flag to indicate
whether initialisation has been completed for this BIO or not. A non-zero value
indicates that initialisation is complete, whilst zero indicates that it is not.
Often initialisation will complete during initial construction of the BIO. For
some BIOs however, initialisation may not complete until after additional steps
have occurred (for example through calling custom ctrls). The BIO_get_init()
function returns the value of the "init" flag.
The BIO_set_shutdown() and BIO_get_shutdown() functions set and get the state of
this BIO's shutdown (i.e. BIO_CLOSE) flag. If set then the underlying resource
is also closed when the BIO is freed.
=head1 RETURN VALUES
BIO_get_data() returns a pointer to the implementation specific custom data
associated with this BIO, or NULL if none has been set.
BIO_get_init() returns the state of the BIO's init flag.
BIO_get_shutdown() returns the stat of the BIO's shutdown (i.e. BIO_CLOSE) flag.
=head1 SEE ALSO
L<bio>, L<BIO_meth_new>
=head1 HISTORY
The functions described here were added in OpenSSL version 1.1.0.
=head1 COPYRIGHT
Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

64
doc/crypto/BIO_get_ex_new_index.pod Normal file
View File

@@ -0,0 +1,64 @@
=pod
=head1 NAME
BIO_get_ex_new_index, BIO_set_ex_data, BIO_get_ex_data,
ENGINE_get_ex_new_index, ENGINE_set_ex_data, ENGINE_get_ex_data,
UI_get_ex_new_index, UI_set_ex_data, UI_get_ex_data,
X509_get_ex_new_index, X509_set_ex_data, X509_get_ex_data,
X509_STORE_get_ex_new_index, X509_STORE_set_ex_data, X509_STORE_get_ex_data,
X509_STORE_CTX_get_ex_new_index, X509_STORE_CTX_set_ex_data, X509_STORE_CTX_get_ex_data,
DH_get_ex_new_index, DH_set_ex_data, DH_get_ex_data,
DSA_get_ex_new_index, DSA_set_ex_data, DSA_get_ex_data,
ECDH_get_ex_new_index, ECDH_set_ex_data, ECDH_get_ex_data,
ECDSA_get_ex_new_index, ECDSA_set_ex_data, ECDSA_get_ex_data,
RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data
- application-specific data
=for comment generic
=head1 SYNOPSIS
#include <openssl/x509.h>
int TYPE_get_ex_new_index(long argl, void *argp,
CRYPTO_EX_new *new_func,
CRYPTO_EX_dup *dup_func,
CRYPTO_EX_free *free_func);
int TYPE_set_ex_data(TYPE *d, int idx, void *arg);
void *TYPE_get_ex_data(TYPE *d, int idx);
=head1 DESCRIPTION
In the description here, I<TYPE> is used a placeholder
for any of the OpenSSL datatypes listed in
L<CRYPTO_get_ex_new_index(3)>.
These functions handle application-specific data for OpenSSL data
structures.
TYPE_get_new_ex_index() is a macro that calls CRYPTO_get_ex_new_index()
with the correct B<index> value.
TYPE_set_ex_data() is a function that calls CRYPTO_set_ex_data() with
an offset into the opaque exdata part of the TYPE object.
TYPE_get_ex_data() is a function that calls CRYPTO_get_ex_data() with an
an offset into the opaque exdata part of the TYPE object.
=head1 SEE ALSO
L<CRYPTO_get_ex_new_index(3)>.
=head1 COPYRIGHT
Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

131
doc/crypto/BIO_meth_new.pod Normal file
View File

@@ -0,0 +1,131 @@
=pod
=head1 NAME
BIO_get_new_index,
BIO_meth_new, BIO_meth_free, BIO_meth_get_write, BIO_meth_set_write,
BIO_meth_get_read, BIO_meth_set_read, BIO_meth_get_puts, BIO_meth_set_puts,
BIO_meth_get_gets, BIO_meth_set_gets, BIO_meth_get_ctrl, BIO_meth_set_ctrl,
BIO_meth_get_create, BIO_meth_set_create, BIO_meth_get_destroy,
BIO_meth_set_destroy, BIO_meth_get_callback_ctrl,
BIO_meth_set_callback_ctrl - Routines to build up BIO methods
=head1 SYNOPSIS
#include <openssl/bio.h>
int BIO_get_new_index(void);
BIO_METHOD *BIO_meth_new(int type, const char *name);
void BIO_meth_free(BIO_METHOD *biom);
int (*BIO_meth_get_write(BIO_METHOD *biom)) (BIO *, const char *, int);
int BIO_meth_set_write(BIO_METHOD *biom,
int (*write) (BIO *, const char *, int));
int (*BIO_meth_get_read(BIO_METHOD *biom)) (BIO *, char *, int);
int BIO_meth_set_read(BIO_METHOD *biom,
int (*read) (BIO *, char *, int));
int (*BIO_meth_get_puts(BIO_METHOD *biom)) (BIO *, const char *);
int BIO_meth_set_puts(BIO_METHOD *biom,
int (*puts) (BIO *, const char *));
int (*BIO_meth_get_gets(BIO_METHOD *biom)) (BIO *, char *, int);
int BIO_meth_set_gets(BIO_METHOD *biom,
int (*gets) (BIO *, char *, int));
long (*BIO_meth_get_ctrl(BIO_METHOD *biom)) (BIO *, int, long, void *);
int BIO_meth_set_ctrl(BIO_METHOD *biom,
long (*ctrl) (BIO *, int, long, void *));
int (*BIO_meth_get_create(BIO_METHOD *bion)) (BIO *);
int BIO_meth_set_create(BIO_METHOD *biom, int (*create) (BIO *));
int (*BIO_meth_get_destroy(BIO_METHOD *biom)) (BIO *);
int BIO_meth_set_destroy(BIO_METHOD *biom, int (*destroy) (BIO *));
long (*BIO_meth_get_callback_ctrl(BIO_METHOD *biom))
(BIO *, int, bio_info_cb *);
int BIO_meth_set_callback_ctrl(BIO_METHOD *biom,
long (*callback_ctrl) (BIO *, int,
bio_info_cb *));
=head1 DESCRIPTION
The B<BIO_METHOD> type is a structure used for the implementation of new BIO
types. It provides a set of of functions used by OpenSSL for the implementation
of the various BIO capabilities. See the L<bio> page for more information.
BIO_meth_new() creates a new B<BIO_METHOD> structure. It should be given a
unique integer B<type> and a string that represents its B<name>.
Use BIO_get_new_index() to get the value for B<type>.
The set of
standard OpenSSL provided BIO types is provided in B<bio.h>. Some examples
include B<BIO_TYPE_BUFFER> and B<BIO_TYPE_CIPHER>. Filter BIOs should have a
type which have the "filter" bit set (B<BIO_TYPE_FILTER>). Source/sink BIOs
should have the "source/sink" bit set (B<BIO_TYPE_SOURCE_SINK>). File descriptor
based BIOs (e.g. socket, fd, connect, accept etc) should additionally have the
"descriptor" bit set (B<BIO_TYPE_DESCRIPTOR>). See the L<BIO_find_type> page for
more information.
BIO_meth_free() destroys a B<BIO_METHOD> structure and frees up any memory
associated with it.
BIO_meth_get_write() and BIO_meth_set_write() get and set the function used for
writing arbitrary length data to the BIO respectively. This function will be
called in response to the application calling BIO_write(). The parameters for
the function have the same meaning as for BIO_write().
BIO_meth_get_read() and BIO_meth_set_read() get and set the function used for
reading arbitrary length data from the BIO respectively. This function will be
called in response to the application calling BIO_read(). The parameters for the
function have the same meaning as for BIO_read().
BIO_meth_get_puts() and BIO_meth_set_puts() get and set the function used for
writing a NULL terminated string to the BIO respectively. This function will be
called in response to the application calling BIO_puts(). The parameters for
the function have the same meaning as for BIO_puts().
BIO_meth_get_gets() and BIO_meth_set_gets() get and set the function typically
used for reading a line of data from the BIO respectively (see the L<BIO_gets(3)>
page for more information). This function will be called in response to the
application calling BIO_gets(). The parameters for the function have the same
meaning as for BIO_gets().
BIO_meth_get_ctrl() and BIO_meth_set_ctrl() get and set the function used for
processing ctrl messages in the BIO respectively. See the L<BIO_ctrl> page for
more information. This function will be called in response to the application
calling BIO_ctrl(). The parameters for the function have the same meaning as for
BIO_ctrl().
BIO_meth_get_create() and BIO_meth_set_create() get and set the function used
for creating a new instance of the BIO respectively. This function will be
called in response to the application calling BIO_new() and passing
in a pointer to the current BIO_METHOD. The BIO_new() function will allocate the
memory for the new BIO, and a pointer to this newly allocated structure will
be passed as a parameter to the function.
BIO_meth_get_destroy() and BIO_meth_set_destroy() get and set the function used
for destroying an instance of a BIO respectively. This function will be
called in response to the application calling BIO_free(). A pointer to the BIO
to be destroyed is passed as a parameter. The destroy function should be used
for BIO specific clean up. The memory for the BIO itself should not be freed by
this function.
BIO_meth_get_callback_ctrl() and BIO_meth_set_callback_ctrl() get and set the
function used for processing callback ctrl messages in the BIO respectively. See
the L<BIO_callback_ctrl(3)> page for more information. This function will be called
in response to the application calling BIO_callback_ctrl(). The parameters for
the function have the same meaning as for BIO_callback_ctrl().
=head1 SEE ALSO
L<bio>, L<BIO_find_type>, L<BIO_ctrl>, L<BIO_read>, L<BIO_new>
=head1 HISTORY
The functions described here were added in OpenSSL version 1.1.0.
=head1 COPYRIGHT
Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

47
doc/crypto/BIO_new.pod
View File

@@ -2,57 +2,57 @@
=head1 NAME
BIO_new, BIO_set, BIO_free, BIO_vfree, BIO_free_all - BIO allocation and freeing functions
BIO_new, BIO_up_ref, BIO_free, BIO_vfree, BIO_free_all,
BIO_set - 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);
BIO * BIO_new(const BIO_METHOD *type);
int BIO_set(BIO *a, const BIO_METHOD *type);
int BIO_up_ref(BIO *a);
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_up_ref() increments the reference count associated with the BIO object.
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
but it does not return a value.
If B<a> is NULL nothing is done.
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.
If B<a> is NULL nothing is done.
=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_set(), BIO_up_ref() and 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()
Calling BIO_free_all() on a single BIO has the same effect as calling BIO_free()
on it other than the discarded return value.
Normally the B<type> argument is supplied by a function which returns a
pointer to a BIO_METHOD. There is a naming convention for such functions:
a source/sink BIO is normally called BIO_s_*() and a filter BIO
BIO_f_*();
=head1 HISTORY
BIO_set() was removed in OpenSSL 1.1.0 as BIO type is now opaque.
=head1 EXAMPLE
@@ -60,6 +60,13 @@ Create a memory BIO:
BIO *mem = BIO_new(BIO_s_mem());
=head1 SEE ALSO
=head1 COPYRIGHT
TBA
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

15
doc/crypto/BIO_new_CMS.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
BIO_new_CMS - CMS streaming filter BIO
BIO_new_CMS - CMS streaming filter BIO
=head1 SYNOPSIS
@@ -56,11 +56,20 @@ 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)>
L<ERR_get_error(3)>, L<CMS_sign(3)>,
L<CMS_encrypt(3)>
=head1 HISTORY
BIO_new_CMS() was added to OpenSSL 1.0.0
=head1 COPYRIGHT
Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

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

@@ -0,0 +1,74 @@
=pod
=head1 NAME
BIO_hostserv_priorities,
BIO_parse_hostserv
- utility routines to parse a standard host and service string
=head1 SYNOPSIS
#include <openssl/bio.h>
enum BIO_hostserv_priorities {
BIO_PARSE_PRIO_HOST, BIO_PARSE_PRIO_SERV
};
int BIO_parse_hostserv(const char *hostserv, char **host, char **service,
enum BIO_hostserv_priorities hostserv_prio);
=head1 DESCRIPTION
BIO_parse_hostserv() will parse the information given in B<hostserv>,
create strings with the host name and service name and give those
back via B<host> and B<service>. Those will need to be freed after
they are used. B<hostserv_prio> helps determine if B<hostserv> shall
be interpreted primarily as a host name or a service name in ambiguous
cases.
The syntax the BIO_parse_hostserv() recognises is:
host + ':' + service
host + ':' + '*'
host + ':'
':' + service
'*' + ':' + service
host
service
The host part can be a name or an IP address. If it's a IPv6
address, it MUST be enclosed in brackets, such as '[::1]'.
The service part can be a service name or its port number.
The returned values will depend on the given B<hostserv> string
and B<hostserv_prio>, as follows:
host + ':' + service => *host = "host", *service = "service"
host + ':' + '*' => *host = "host", *service = NULL
host + ':' => *host = "host", *service = NULL
':' + service => *host = NULL, *service = "service"
'*' + ':' + service => *host = NULL, *service = "service"
in case no ':' is present in the string, the result depends on
hostserv_prio, as follows:
when hostserv_prio == BIO_PARSE_PRIO_HOST
host => *host = "host", *service untouched
when hostserv_prio == BIO_PARSE_PRIO_SERV
service => *host untouched, *service = "service"
=head1 SEE ALSO
L<BIO_ADDRINFO(3)>
=head1 COPYRIGHT
Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

50
doc/crypto/BIO_printf.pod Normal file
View File

@@ -0,0 +1,50 @@
=pod
=head1 NAME
BIO_printf, BIO_vprintf, BIO_snprintf, BIO_vsnprintf
- formatted output to a BIO
=head1 SYNOPSIS
#include <openssl/bio.h>
int BIO_printf(BIO *bio, const char *format, ...)
int BIO_vprintf(BIO *bio, const char *format, va_list args)
int BIO_snprintf(char *buf, size_t n, const char *format, ...)
int BIO_vsnprintf(char *buf, size_t n, const char *format, va_list args)
=head1 DESCRIPTION
BIO_printf() is similar to the standard C printf() function, except that
the output is sent to the specified BIO, B<bio>, rather than standard
output. All common format specifiers are supported.
BIO_vprintf() is similar to the vprintf() function found on many platforms,
the output is sent to the specified BIO, B<bio>, rather than standard
output. All common format specifiers are supported. The argument
list B<args> is a stdarg argument list.
BIO_snprintf() is for platforms that do not have the common snprintf()
function. It is like sprintf() except that the size parameter, B<n>,
specifies the size of the output buffer.
BIO_vsnprintf() is to BIO_snprintf() as BIO_vprintf() is to BIO_printf().
=head1 RETURN VALUES
All functions return the number of bytes written, or -1 on error.
For BIO_snprintf() and BIO_vsnprintf() this includes when the output
buffer is too small.
=head1 COPYRIGHT
Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

28
doc/crypto/BIO_push.pod
View File

@@ -2,14 +2,15 @@
=head1 NAME
BIO_push, BIO_pop - add and remove BIOs from a chain.
BIO_push, BIO_pop, BIO_set_next - 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);
BIO *BIO_push(BIO *b, BIO *append);
BIO *BIO_pop(BIO *b);
void BIO_set_next(BIO *b, BIO *next);
=head1 DESCRIPTION
@@ -21,6 +22,10 @@ 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.
BIO_set_next() replaces the existing next BIO in a chain with the BIO pointed to
by B<next>. The new chain may include some of the same BIOs from the old chain
or it may be completely different.
=head1 NOTES
The names of these functions are perhaps a little misleading. BIO_push()
@@ -66,4 +71,19 @@ BIO.
=head1 SEE ALSO
TBA
L<bio>
=head1 HISTORY
The BIO_set_next() function was added in OpenSSL version 1.1.0.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

35
doc/crypto/BIO_read.pod
View File

@@ -8,10 +8,10 @@ BIO_read, BIO_write, BIO_gets, BIO_puts - BIO I/O functions
#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);
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
@@ -20,20 +20,22 @@ 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
from the BIO of maximum length B<len-1>. 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.
The returned string is always NUL-terminated.
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>.
BIO_puts() attempts to write a NUL-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.
the operation is not implemented in the specific BIO type. The trailing
NUL is not included in the length returned by BIO_gets().
=head1 NOTES
@@ -52,15 +54,24 @@ 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
See L<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)>
work around this by adding a buffering BIO L<BIO_f_buffer(3)>
to the chain.
=head1 SEE ALSO
L<BIO_should_retry(3)|BIO_should_retry(3)>
L<BIO_should_retry(3)>
TBA
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

117
doc/crypto/BIO_s_accept.pod
View File

@@ -2,17 +2,20 @@
=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
BIO_s_accept, BIO_set_accept_name, BIO_set_accept_port, BIO_get_accept_name,
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);
const BIO_METHOD *BIO_s_accept(void);
long BIO_set_accept_port(BIO *b, char *name);
long BIO_set_accept_name(BIO *b, char *name);
char *BIO_get_accept_name(BIO *b);
long BIO_set_accept_port(BIO *b, char *port);
char *BIO_get_accept_port(BIO *b);
BIO *BIO_new_accept(char *host_port);
@@ -21,11 +24,7 @@ BIO_get_bind_mode, BIO_do_accept - accept BIO
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
long BIO_get_bind_mode(BIO *b);
int BIO_do_accept(BIO *b);
@@ -49,23 +48,30 @@ 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
Calling BIO_reset() on an 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)>
the accept socket. See L<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",
BIO_set_accept_name() uses the string B<name> to set the accept
name. The name 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.
The host can be "*" or empty which is interpreted as meaning
any interface. If the host is an IPv6 address, it has to be
enclosed in brackets, for example "[::1]:https". "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
BIO_set_accept_port() uses the string B<port> to set the accept
port. "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_name() into
a single call: that is it creates a new accept BIO with port
B<host_port>.
@@ -74,19 +80,19 @@ BIO_set_nbio_accept() sets the accept socket to blocking mode
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
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
the current bind mode. If B<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
B<BIO_BIND_REUSEADDR> is set then other sockets can bind to the
same port. If B<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.
using B<BIO_BIND_REUSEADDR>.
BIO_do_accept() serves two functions. When it is first
called, after the accept BIO has been setup, it will attempt
@@ -137,13 +143,24 @@ 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.
BIO_set_accept_name(), BIO_get_accept_name(), 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
BIO_do_accept(),
BIO_set_accept_name(), BIO_set_accept_port(), BIO_set_nbio_accept(),
BIO_set_accept_bios(), and BIO_set_bind_mode(), return 1 for success and 0 or
-1 for failure.
BIO_get_accept_name() returns the accept name or NULL on error.
BIO_get_accept_port() returns the port as a string or NULL on error.
BIO_get_bind_mode() returns the set of B<BIO_BIND> flags, or -1 on failure.
BIO_new_accept() returns a BIO or NULL on error.
=head1 EXAMPLE
@@ -151,34 +168,36 @@ 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);
abio = BIO_new_accept("4444");
if (BIO_do_accept(abio) <= 0) {
fprintf(stderr, "Error setting up accept\n");
ERR_print_errors_fp(stderr);
exit(1);
}
/* Wait for incoming connection */
if(BIO_do_accept(abio) <= 0) {
fprintf(stderr, "Error accepting connection\n");
ERR_print_errors_fp(stderr);
exit(0);
if (BIO_do_accept(abio) <= 0) {
fprintf(stderr, "Error accepting connection\n");
ERR_print_errors_fp(stderr);
exit(1);
}
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);
if (BIO_do_accept(abio) <= 0) {
fprintf(stderr, "Error accepting connection\n");
ERR_print_errors_fp(stderr);
exit(1);
}
fprintf(stderr, "Connection 2 established\n");
/* Close accept BIO to refuse further connections */
cbio2 = BIO_pop(abio);
BIO_free(abio);
@@ -186,10 +205,18 @@ down each and finally closes both down.
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
=head1 COPYRIGHT
TBA
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

58
doc/crypto/BIO_s_bio.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
BIO_s_bio, BIO_make_bio_pair, BIO_destroy_bio_pair, BIO_shutdown_wr,
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
@@ -11,24 +11,22 @@ BIO_ctrl_get_read_request, BIO_ctrl_reset_read_request - BIO pair BIO
#include <openssl/bio.h>
BIO_METHOD *BIO_s_bio(void);
const 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)
int BIO_make_bio_pair(BIO *b1, BIO *b2);
int BIO_destroy_bio_pair(BIO *b);
int BIO_shutdown_wr(BIO *b);
#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_set_write_buf_size(BIO *b, long size);
size_t BIO_get_write_buf_size(BIO *b, long size);
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)
int BIO_get_write_guarantee(BIO *b);
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)
int BIO_get_read_request(BIO *b);
size_t BIO_ctrl_get_read_request(BIO *b);
int BIO_ctrl_reset_read_request(BIO *b);
=head1 DESCRIPTION
@@ -65,7 +63,7 @@ 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.
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
@@ -123,6 +121,11 @@ never sent!
BIO_eof() is true if no data is in the peer BIO and the peer BIO has been
shutdown.
BIO_make_bio_pair(), BIO_destroy_bio_pair(), BIO_shutdown_wr(),
BIO_set_write_buf_size(), BIO_get_write_buf_size(),
BIO_get_write_guarantee(), and BIO_get_read_request() are implemented
as macros.
=head1 RETURN VALUES
BIO_new_bio_pair() returns 1 on success, with the new BIOs available in
@@ -139,9 +142,9 @@ without having to go through the SSL-interface.
BIO *internal_bio, *network_bio;
...
BIO_new_bio_pair(internal_bio, 0, network_bio, 0);
BIO_new_bio_pair(&internal_bio, 0, &network_bio, 0);
SSL_set_bio(ssl, internal_bio, internal_bio);
SSL_operations();
SSL_operations(); //e.g SSL_read and SSL_write
...
application | TLS-engine
@@ -150,12 +153,16 @@ without having to go through the SSL-interface.
| /\ ||
| || \/
| BIO-pair (internal_bio)
+----------< BIO-pair (network_bio)
| BIO-pair (network_bio)
| || /\
| \/ ||
+-----------< BIO_operations()
| |
socket |
| |
socket
...
SSL_free(ssl); /* implicitly frees internal_bio */
SSL_free(ssl); /* implicitly frees internal_bio */
BIO_free(network_bio);
...
@@ -165,13 +172,13 @@ 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
and must be transferred 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
As the data is buffered, SSL_operation() may return with an 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
@@ -179,7 +186,16 @@ 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)>
L<SSL_set_bio(3)>, L<ssl(3)>, L<bio(3)>,
L<BIO_should_retry(3)>, L<BIO_read(3)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

76
doc/crypto/BIO_s_connect.pod
View File

@@ -2,27 +2,26 @@
=head1 NAME
BIO_set_conn_address, BIO_get_conn_address,
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_get_conn_hostname,
BIO_get_conn_port,
BIO_set_nbio, BIO_do_connect - connect BIO
=head1 SYNOPSIS
#include <openssl/bio.h>
BIO_METHOD * BIO_s_connect(void);
const 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_conn_address(BIO *b, BIO_ADDR *addr);
const char *BIO_get_conn_hostname(BIO *b);
const char *BIO_get_conn_port(BIO *b);
const BIO_ADDR *BIO_get_conn_address(BIO *b);
long BIO_set_nbio(BIO *b, long n);
@@ -57,36 +56,33 @@ 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".
The hostname can be an IP address; if the address is an IPv6 one, it
must be enclosed with brackets. The hostname can also include the
port in the form hostname:port.
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.
fails a standard table of port names will be used. This internal
list is http, telnet, socks, https, ssl, ftp, and gopher.
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_set_conn_address() sets the address and port information using
a BIO_ADDR(3ssl).
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.
This return value is an internal pointer which should not be modified.
BIO_get_conn_ip() returns the IP address in binary form.
BIO_get_conn_int_port() returns the port as an int.
BIO_get_conn_address() returns the address information as a BIO_ADDR.
This return value is an internal pointer which should not be modified.
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
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
@@ -169,19 +165,20 @@ 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 ... */
}
if (BIO_do_connect(cbio) <= 0) {
fprintf(stderr, "Error connecting to server\n");
ERR_print_errors_fp(stderr);
exit(1);
}
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);
for ( ; ; ) {
len = BIO_read(cbio, tmpbuf, 1024);
if (len <= 0)
break;
BIO_write(out, tmpbuf, len);
}
BIO_free(cbio);
BIO_free(out);
@@ -189,4 +186,15 @@ to retrieve a page and copy the result to standard output.
=head1 SEE ALSO
TBA
L<BIO_ADDR(3)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

51
doc/crypto/BIO_s_fd.pod
View File

@@ -8,10 +8,10 @@ BIO_s_fd, BIO_set_fd, BIO_get_fd, BIO_new_fd - file descriptor BIO
#include <openssl/bio.h>
BIO_METHOD * BIO_s_fd(void);
const 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)
int BIO_set_fd(BIO *b, int fd, int c);
int BIO_get_fd(BIO *b, int *c);
BIO *BIO_new_fd(int fd, int close_flag);
@@ -23,46 +23,43 @@ 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
If the close flag is set 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).
such as by using B<lseek(fd, 0, 0)>.
BIO_seek() sets the file pointer to position B<ofs> from start of file
using lseek(fd, ofs, 0).
such as by using B<lseek(fd, ofs, 0)>.
BIO_tell() returns the current file position by calling lseek(fd, 0, 1).
BIO_tell() returns the current file position such as by calling
B<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 *).
returns the file descriptor.
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
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)>
manner described in the L<BIO_read(3)> and L<BIO_should_retry(3)>
manual pages.
File descriptor BIOs should not be used for socket I/O. Use socket BIOs
instead.
BIO_set_fd() and BIO_get_fd() are implemented as macros.
=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
@@ -76,14 +73,26 @@ occurred.
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)>
L<BIO_seek(3)>, L<BIO_tell(3)>,
L<BIO_reset(3)>, L<BIO_read(3)>,
L<BIO_write(3)>, L<BIO_puts(3)>,
L<BIO_gets(3)>, L<BIO_printf(3)>,
L<BIO_set_close(3)>, L<BIO_get_close(3)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

41
doc/crypto/BIO_s_file.pod
View File

@@ -10,12 +10,12 @@ BIO_rw_filename - FILE bio
#include <openssl/bio.h>
BIO_METHOD * BIO_s_file(void);
const 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);
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)
@@ -92,15 +92,15 @@ 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 ... */
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 */
if (!out) /* Error occurred */
BIO_printf(out, "Hello World\n");
BIO_free(out);
@@ -108,8 +108,8 @@ Alternative technique:
BIO *out;
out = BIO_new(BIO_s_file());
if(out == NULL) /* Error ... */
if(!BIO_write_filename(out, "filename.txt")) /* Error ... */
if (out == NULL) /* Error ... */
if (!BIO_write_filename(out, "filename.txt")) /* Error ... */
BIO_printf(out, "Hello World\n");
BIO_free(out);
@@ -128,7 +128,7 @@ BIO_seek() returns the same value as the underlying fseek() function:
BIO_tell() returns the current file position.
BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and
BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and
BIO_rw_filename() return 1 for success or 0 for failure.
=head1 BUGS
@@ -140,9 +140,20 @@ occurred this differs from other types of BIO which will typically return
=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)>
L<BIO_seek(3)>, L<BIO_tell(3)>,
L<BIO_reset(3)>, L<BIO_flush(3)>,
L<BIO_read(3)>,
L<BIO_write(3)>, L<BIO_puts(3)>,
L<BIO_gets(3)>, L<BIO_printf(3)>,
L<BIO_set_close(3)>, L<BIO_get_close(3)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

45
doc/crypto/BIO_s_mem.pod
View File

@@ -2,6 +2,7 @@
=head1 NAME
BIO_s_secmem,
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
@@ -9,23 +10,27 @@ BIO_get_mem_ptr, BIO_new_mem_buf - memory BIO
#include <openssl/bio.h>
BIO_METHOD * BIO_s_mem(void);
const BIO_METHOD * BIO_s_mem(void);
const BIO_METHOD * BIO_s_secmem(void);
BIO_set_mem_eof_return(BIO *b,int v)
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_set_mem_buf(BIO *b, BUF_MEM *bm, int c)
BIO_get_mem_ptr(BIO *b, BUF_MEM **pp)
BIO *BIO_new_mem_buf(const void *buf, int len);
=head1 DESCRIPTION
BIO_s_mem() return the memory BIO method function.
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.
BIO_s_secmem() is like BIO_s_mem() except that the secure heap is used
for buffer storage.
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.
@@ -35,9 +40,10 @@ 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.
Calling BIO_reset() on a read write memory BIO clears any data in it if the
flag BIO_FLAGS_NONCLEAR_RST is not set. On a read only BIO or if the flag
BIO_FLAGS_NONCLEAR_RST is set it restores the BIO to its original state and
the data can be read again.
BIO_eof() is true if no data is in the BIO.
@@ -79,22 +85,19 @@ 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.
Calling BIO_set_mem_buf() on a BIO created with BIO_new_secmem() will
give undefined results, including perhaps a program crash.
=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");
BIO_puts(mem, "Hello World\n");
Create a read only memory BIO:
@@ -108,8 +111,14 @@ Extract the BUF_MEM structure from a memory BIO and then free up the BIO:
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
=head1 COPYRIGHT
TBA
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

13
doc/crypto/BIO_s_null.pod
View File

@@ -8,7 +8,7 @@ BIO_s_null - null data sink
#include <openssl/bio.h>
BIO_METHOD * BIO_s_null(void);
const BIO_METHOD * BIO_s_null(void);
=head1 DESCRIPTION
@@ -32,6 +32,13 @@ by adding a null sink BIO to the end of the chain
BIO_s_null() returns the null sink BIO method.
=head1 SEE ALSO
=head1 COPYRIGHT
TBA
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

29
doc/crypto/BIO_s_socket.pod
View File

@@ -8,10 +8,7 @@ BIO_s_socket, BIO_new_socket - socket BIO
#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);
const BIO_METHOD *BIO_s_socket(void);
BIO *BIO_new_socket(int sock, int close_flag);
@@ -26,12 +23,6 @@ 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
@@ -44,20 +35,20 @@ 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
=head1 COPYRIGHT
TBA
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

191
doc/crypto/BIO_set_callback.pod
View File

@@ -2,99 +2,205 @@
=head1 NAME
BIO_set_callback, BIO_get_callback, BIO_set_callback_arg, BIO_get_callback_arg,
BIO_debug_callback - BIO callback functions
BIO_set_callback_ex, BIO_get_callback_ex, BIO_set_callback, BIO_get_callback,
BIO_set_callback_arg, BIO_get_callback_arg, BIO_debug_callback,
BIO_callback_fn_ex, BIO_callback_fn
- 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)
typedef long (*BIO_callback_fn_ex)(BIO *b, int oper, const char *argp,
size_t len, int argi,
long argl, int ret, size_t *processed);
typedef long (*BIO_callback_fn)(BIO *b, int oper, const char *argp, int argi,
long argl, long ret);
long BIO_debug_callback(BIO *bio,int cmd,const char *argp,int argi,
long argl,long ret);
void BIO_set_callback_ex(BIO *b, BIO_callback_fn_ex callback);
BIO_callback_fn_ex BIO_get_callback_ex(const BIO *b);
typedef long (*callback)(BIO *b, int oper, const char *argp,
int argi, long argl, long retvalue);
void BIO_set_callback(BIO *b, BIO_callack_fn cb);
BIO_callack_fn BIO_get_callback(BIO *b);
void BIO_set_callback_arg(BIO *b, char *arg);
char *BIO_get_callback_arg(const BIO *b);
long BIO_debug_callback(BIO *bio, int cmd, const char *argp, int argi,
long argl, long ret);
=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_ex() and BIO_get_callback_ex() set and retrieve the BIO
callback. 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() and BIO_get_callback() set and retrieve the old format BIO
callback. New code should not use these functions, but they are retained for
backwards compatbility. Any callback set via BIO_set_callback_ex() will get
called in preference to any set by BIO_set_callback().
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
argument is set it 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.
BIO_callback_fn_ex() is the type of the callback function and BIO_callback_fn()
is the type of the old format callback function. The meaning of each argument
is described below:
=over 4
=item B<b>
The BIO the callback is attached to is passed in B<b>.
=item B<oper>
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.
=item B<len>
The length of the data requested to be read or written. This is only useful if
B<oper> is BIO_CB_READ, BIO_CB_WRITE or BIO_CB_GETS.
=item B<argp> B<argi> B<argl>
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
=item B<processed>
B<processed> is a pointer to a location which will be updated with the amount of
data that was actually read or written. Only used for BIO_CB_READ, BIO_CB_WRITE,
BIO_CB_GETS and BIO_CB_PUTS.
=item B<ret>
B<ret> 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
called before the actual BIO operation 1 is placed in B<ret>, 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
=back
The callback should normally simply return B<ret> when it has
finished processing, unless it specifically wishes to modify the
value returned to the application.
=head1 CALLBACK OPERATIONS
In the notes below, B<callback> defers to the actual callback
function that is called.
=over 4
=item B<BIO_free(b)>
callback(b, BIO_CB_FREE, NULL, 0L, 0L, 1L) is called before the
free operation.
callback_ex(b, BIO_CB_FREE, NULL, 0, 0, 0L, 1L, NULL)
=item B<BIO_read(b, out, outl)>
or
callback(b, BIO_CB_FREE, NULL, 0L, 0L, 1L)
is called before the free operation.
=item B<BIO_read_ex(b, data, dlen, readbytes)>
callback_ex(b, BIO_CB_READ, data, dlen, 0, 0L, 1L, readbytes)
or
callback(b, BIO_CB_READ, data, dlen, 0L, 1L)
is called before the read and
callback_ex(b, BIO_CB_READ | BIO_CB_RETURN, data, dlen, 0, 0L, retvalue, readbytes)
or
callback(b, BIO_CB_READ|BIO_CB_RETURN, data, dlen, 0L, retvalue)
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)>
=item B<BIO_write(b, data, dlen, written)>
callback_ex(b, BIO_CB_WRITE, data, dlen, 0, 0L, 1L, written)
or
callback(b, BIO_CB_WRITE, datat, dlen, 0L, 1L)
is called before the write and
callback_ex(b, BIO_CB_WRITE | BIO_CB_RETURN, data, dlen, 0, 0L, retvalue, written)
or
callback(b, BIO_CB_WRITE|BIO_CB_RETURN, data, dlen, 0L, retvalue)
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)>
=item B<BIO_gets(b, buf, size)>
callback_ex(b, BIO_CB_GETS, buf, size, 0, 0L, 1, NULL, NULL)
or
callback(b, BIO_CB_GETS, buf, size, 0L, 1L)
is called before the operation and
callback_ex(b, BIO_CB_GETS | BIO_CB_RETURN, buf, size, 0, 0L, retvalue, readbytes)
or
callback(b, BIO_CB_GETS|BIO_CB_RETURN, buf, size, 0L, retvalue)
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)>
=item B<BIO_puts(b, buf)>
callback_ex(b, BIO_CB_PUTS, buf, 0, 0, 0L, 1L, NULL);
or
callback(b, BIO_CB_PUTS, buf, 0, 0L, 1L)
is called before the operation and
callback_ex(b, BIO_CB_PUTS | BIO_CB_RETURN, buf, 0, 0, 0L, retvalue, written)
or
callback(b, BIO_CB_WRITE|BIO_CB_RETURN, buf, 0, 0L, retvalue)
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.
callback_ex(b, BIO_CB_CTRL, parg, 0, cmd, larg, 1L, NULL)
or
callback(b, BIO_CB_CTRL, parg, cmd, larg, 1L)
is called before the call and
callback_ex(b, BIO_CB_CTRL | BIO_CB_RETURN, parg, 0, cmd, larg, ret, NULL)
or
callback(b, BIO_CB_CTRL|BIO_CB_RETURN, parg, cmd, larg, ret)
after.
=back
@@ -103,6 +209,13 @@ callback(b,BIO_CB_CTRL|BIO_CB_RETURN,parg,cmd, larg,ret) after.
The BIO_debug_callback() function is a good example, its source is
in crypto/bio/bio_cb.c
=head1 SEE ALSO
=head1 COPYRIGHT
TBA
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

54
doc/crypto/BIO_should_retry.pod
View File

@@ -2,28 +2,24 @@
=head1 NAME
BIO_should_retry, BIO_should_read, BIO_should_write,
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
BIO_get_retry_BIO, BIO_get_retry_reason, BIO_set_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)
int BIO_should_read(BIO *b);
int BIO_should_write(BIO *b);
int BIO_should_io_special(iBIO *b);
int BIO_retry_type(BIO *b);
int BIO_should_retry(BIO *b);
#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);
BIO *BIO_get_retry_BIO(BIO *bio, int *reason);
int BIO_get_retry_reason(BIO *bio);
void BIO_set_retry_reason(BIO *bio, int reason);
=head1 DESCRIPTION
@@ -51,7 +47,7 @@ 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
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.
@@ -59,8 +55,14 @@ 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().
BIO_set_retry_reason() sets the retry reason for a special condition for a given
BIO. This would usually only be called by BIO implementations.
=head1 NOTES
BIO_should_read(), BIO_should_write(), BIO_should_io_special(),
BIO_retry_type(), and BIO_should_retry(), are implemented as macros.
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
@@ -94,7 +96,7 @@ 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.
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
@@ -111,4 +113,20 @@ the entire structure can be read or written.
=head1 SEE ALSO
TBA
L<bio>
=head1 HISTORY
The BIO_get_retry_reason() and BIO_set_retry_reason() functions were added in
OpenSSL version 1.1.0.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

81
doc/crypto/BN_BLINDING_new.pod
View File

@@ -2,38 +2,37 @@
=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.
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_is_current_thread, BN_BLINDING_set_current_thread,
BN_BLINDING_lock, BN_BLINDING_unlock, 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);
BIGNUM *mod);
void BN_BLINDING_free(BN_BLINDING *b);
int BN_BLINDING_update(BN_BLINDING *b,BN_CTX *ctx);
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);
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 *);
BN_CTX *ctx);
int BN_BLINDING_is_current_thread(BN_BLINDING *b);
void BN_BLINDING_set_current_thread(BN_BLINDING *b);
int BN_BLINDING_lock(BN_BLINDING *b);
int BN_BLINDING_unlock(BN_BLINDING *b);
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);
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
@@ -41,6 +40,7 @@ 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.
If B<b> is NULL, nothing is done.
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
@@ -57,11 +57,16 @@ 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_is_current_thread() returns whether the B<BN_BLINDING>
structure is owned by the current thread. This is to help users
provide proper locking if needed for multi-threaded use.
BN_BLINDING_set_current_thread() sets the current thread as the
owner of the B<BN_BLINDING> structure.
BN_BLINDING_lock() locks the B<BN_BLINDING> structure.
BN_BLINDING_unlock() unlocks the B<BN_BLINDING> structure.
BN_BLINDING_get_flags() returns the BN_BLINDING flags. Currently
there are two supported flags: B<BN_BLINDING_NO_UPDATE> and
@@ -86,30 +91,32 @@ 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_is_current_thread() returns 1 if the current thread owns
the B<BN_BLINDING> object, 0 otherwise.
BN_BLINDING_set_current_thread() doesn't return anything.
BN_BLINDING_lock(), BN_BLINDING_unlock() return 1 if the operation
succeeded or 0 on error.
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>
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_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 COPYRIGHT
=head1 AUTHOR
Copyright 2005-2017 The OpenSSL Project Authors. All Rights Reserved.
Nils Larsch for the OpenSSL project (http://www.openssl.org).
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

61
doc/crypto/BN_CTX_new.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
BN_CTX_new, BN_CTX_init, BN_CTX_free - allocate and free BN_CTX structures
BN_CTX_new, BN_CTX_secure_new, BN_CTX_free - allocate and free BN_CTX structures
=head1 SYNOPSIS
@@ -10,13 +10,10 @@ BN_CTX_new, BN_CTX_init, BN_CTX_free - allocate and free BN_CTX structures
BN_CTX *BN_CTX_new(void);
BN_CTX *BN_CTX_secure_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
@@ -24,34 +21,56 @@ 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_new() allocates and initializes a B<BN_CTX> structure.
BN_CTX_secure_new() allocates and initializes a B<BN_CTX> structure
but uses the secure heap (see L<CRYPTO_secure_malloc(3)>) to hold the
B<BIGNUM>s.
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>
If L<BN_CTX_start(3)> has been used on the B<BN_CTX>,
L<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.
If B<c> is NULL, nothing is done.
=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_new() and BN_CTX_secure_new() return a pointer to the B<BN_CTX>.
If the allocation fails,
they return B<NULL> and sets an error code that can be obtained by
L<ERR_get_error(3)>.
BN_CTX_init() and BN_CTX_free() have no return values.
BN_CTX_free() has no return values.
=head1 REMOVED FUNCTIONALITY
void BN_CTX_init(BN_CTX *c);
BN_CTX_init() is no longer available as of OpenSSL 1.1.0. Applications should
replace use of BN_CTX_init with BN_CTX_new instead:
BN_CTX *ctx;
ctx = BN_CTX_new();
if(!ctx) /* Handle error */
...
BN_CTX_free(ctx);
=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)>
L<ERR_get_error(3)>, L<BN_add(3)>,
L<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.
BN_CTX_init() was removed in OpenSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

15
doc/crypto/BN_CTX_start.pod
View File

@@ -17,7 +17,7 @@ BN_CTX_start, BN_CTX_get, BN_CTX_end - use temporary BIGNUM variables
=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)>)
a B<BN_CTX> (which can been created by using L<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.
@@ -38,15 +38,20 @@ 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)>.
can be obtained by L<ERR_get_error(3)>.
=head1 SEE ALSO
L<BN_CTX_new(3)|BN_CTX_new(3)>
L<BN_CTX_new(3)>
=head1 HISTORY
=head1 COPYRIGHT
BN_CTX_start(), BN_CTX_get() and BN_CTX_end() were added in OpenSSL 0.9.5.
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

29
doc/crypto/BN_add.pod
View File

@@ -49,10 +49,11 @@ 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>).
I<r> may be the same B<BIGNUM> as I<a> or I<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)>.
For multiplication by powers of 2, use L<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>.
@@ -80,8 +81,8 @@ 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)>.
L<BN_mod_mul_montgomery(3)> and
L<BN_mod_mul_reciprocal(3)>.
BN_mod_sqr() takes the square of I<a> modulo B<m> and places the
result in I<r>.
@@ -98,7 +99,7 @@ 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)>.
temporary variables; see L<BN_CTX_new(3)>.
Unless noted otherwise, the result B<BIGNUM> must be different from
the arguments.
@@ -107,20 +108,20 @@ the arguments.
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)>.
The error codes can be obtained by L<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)>
L<ERR_get_error(3)>, L<BN_CTX_new(3)>,
L<BN_add_word(3)>, L<BN_set_bit(3)>
=head1 HISTORY
=head1 COPYRIGHT
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.
Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

16
doc/crypto/BN_add_word.pod
View File

@@ -40,22 +40,22 @@ 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)>.
on error. The error codes can be obtained by L<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)>
L<ERR_get_error(3)>, L<BN_add(3)>
=head1 HISTORY
=head1 COPYRIGHT
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.
Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
Before 0.9.8a the return value for BN_div_word() and BN_mod_word()
in case of an error was 0.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

55
doc/crypto/BN_bn2bin.pod
View File

@@ -2,16 +2,22 @@
=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
BN_bn2binpad,
BN_bn2bin, BN_bin2bn, BN_bn2lebinpad, BN_lebin2bn, 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);
int BN_bn2binpad(const BIGNUM *a, unsigned char *to, int tolen);
BIGNUM *BN_bin2bn(const unsigned char *s, int len, BIGNUM *ret);
int BN_bn2lebinpad(const BIGNUM *a, unsigned char *to, int tolen);
BIGNUM *BN_lebin2bn(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);
@@ -29,20 +35,28 @@ 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_bn2binpad() also converts the absolute value of B<a> into big-endian form
and stores it at B<to>. B<tolen> indicates the length of the output buffer
B<to>. The result is padded with zeroes if necessary. If B<tolen> is less than
BN_num_bytes(B<a>) an error is returned.
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_bn2lebinpad() and BN_bin2lbn() are identical to BN_bn2binpad() and
BN_bin2bn() except the buffer is in little-endian format.
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_hex2bn() takes as many characters as possible from the string B<str>,
including the leading character '-' which means negative, to form a valid
hexadecimal number representation and converts them 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 length of valid representation.
A "negative zero" is converted to zero.
BN_dec2bn() is the same using the decimal system.
@@ -69,29 +83,34 @@ if B<ret> is NULL.
BN_bn2bin() returns the length of the big-endian number placed at B<to>.
BN_bin2bn() returns the B<BIGNUM>, NULL on error.
BN_bn2binpad() returns the number of bytes written or -1 if the supplied
buffer is too small.
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.
on error. BN_hex2bn() and BN_dec2bn() return the the length of valid
representation in hexadecimal or decimal digits, and 0 on error, in which
case no new B<BIGNUM> will be created.
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)>.
The error codes can be obtained by L<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)>
L<ERR_get_error(3)>, L<BN_zero(3)>,
L<ASN1_INTEGER_to_BN(3)>,
L<BN_num_bytes(3)>
=head1 HISTORY
=head1 COPYRIGHT
BN_bn2bin(), BN_bin2bn(), BN_print_fp() and BN_print() are available
in all versions of SSLeay and OpenSSL.
Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
BN_bn2hex(), BN_bn2dec(), BN_hex2bn(), BN_dec2bn(), BN_bn2mpi() and
BN_mpi2bn() were added in SSLeay 0.9.0.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

13
doc/crypto/BN_cmp.pod
View File

@@ -35,14 +35,13 @@ 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
=head1 COPYRIGHT
L<bn(3)|bn(3)>
Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
=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.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

45
doc/crypto/BN_copy.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
BN_copy, BN_dup - copy BIGNUMs
BN_copy, BN_dup, BN_with_flags - copy BIGNUMs
=head1 SYNOPSIS
@@ -12,23 +12,58 @@ BN_copy, BN_dup - copy BIGNUMs
BIGNUM *BN_dup(const BIGNUM *from);
void BN_with_flags(BIGNUM *dest, const BIGNUM *b, int flags);
=head1 DESCRIPTION
BN_copy() copies B<from> to B<to>. BN_dup() creates a new B<BIGNUM>
containing the value B<from>.
BN_with_flags creates a B<temporary> shallow copy of B<b> in B<dest>. It places
significant restrictions on the copied data. Applications that do no adhere to
these restrictions may encounter unexpected side effects or crashes. For that
reason use of this function is discouraged. Any flags provided in B<flags> will
be set in B<dest> in addition to any flags already set in B<b>. For example this
might commonly be used to create a temporary copy of a BIGNUM with the
B<BN_FLG_CONSTTIME> flag set for constant time operations. The temporary copy in
B<dest> will share some internal state with B<b>. For this reason the following
restrictions apply to the use of B<dest>:
=over 2
=item *
B<dest> should be a newly allocated BIGNUM obtained via a call to BN_new(). It
should not have been used for other purposes or initialised in any way.
=item *
B<dest> must only be used in "read-only" operations, i.e. typically those
functions where the relevant parameter is declared "const".
=item *
B<dest> must be used and freed before any further subsequent use of B<b>
=back
=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)>.
by L<ERR_get_error(3)>.
=head1 SEE ALSO
L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>
L<ERR_get_error(3)>
=head1 HISTORY
=head1 COPYRIGHT
BN_copy() and BN_dup() are available in all versions of SSLeay and OpenSSL.
Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

80
doc/crypto/BN_generate_prime.pod
View File

@@ -3,49 +3,59 @@
=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
BN_GENCB_new, BN_GENCB_free, BN_GENCB_set_old, BN_GENCB_set, BN_GENCB_get_arg,
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,
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_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 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) ...
BN_GENCB *BN_GENCB_new(void);
#define BN_GENCB_set(gencb, callback, cb_arg) ...
void BN_GENCB_free(BN_GENCB *cb);
void BN_GENCB_set_old(BN_GENCB *gencb,
void (*callback)(int, int, void *), void *cb_arg);
void BN_GENCB_set(BN_GENCB *gencb,
int (*callback)(int, int, BN_GENCB *), void *cb_arg);
void *BN_GENCB_get_arg(BN_GENCB *cb);
Deprecated:
#if OPENSSL_API_COMPAT < 0x00908000L
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,
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);
#endif
=head1 DESCRIPTION
BN_generate_prime_ex() generates a pseudo-random prime number of
bit length B<bits>.
at least 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
=over 2
=item *
@@ -103,17 +113,23 @@ 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.
A BN_GENCB structure should be created through a call to BN_GENCB_new(),
and freed through a call to BN_GENCB_free().
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
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
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.
It is possible to obtained the argument associated with a BN_GENCB structure
(set via a call to BN_GENCB_set or BN_GENCB_set_old) using BN_GENCB_get_arg.
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
@@ -132,19 +148,47 @@ prime with an error probability of less than 0.25^B<nchecks>, and
BN_generate_prime() returns the prime number on success, B<NULL> otherwise.
BN_GENCB_new returns a pointer to a BN_GENCB structure on success, or B<NULL>
otherwise.
BN_GENCB_get_arg returns the argument previously associated with a BN_GENCB
structure.
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)>.
The error codes can be obtained by L<ERR_get_error(3)>.
=head1 REMOVED FUNCTIONALITY
As of OpenSSL 1.1.0 it is no longer possible to create a BN_GENCB structure
directly, as in:
BN_GENCB callback;
Instead applications should create a BN_GENCB structure using BN_GENCB_new:
BN_GENCB *callback;
callback = BN_GENCB_new();
if(!callback) /* handle error */
...
BN_GENCB_free(callback);
=head1 SEE ALSO
L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>
L<ERR_get_error(3)>, L<RAND_bytes(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.
BN_GENCB_new(), BN_GENCB_free(),
and BN_GENCB_get_arg() were added in OpenSSL 1.1.0
=head1 COPYRIGHT
Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

13
doc/crypto/BN_mod_inverse.pod
View File

@@ -23,14 +23,19 @@ 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)>.
NULL on error. The error codes can be obtained by L<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<ERR_get_error(3)>, L<BN_add(3)>
=head1 HISTORY
=head1 COPYRIGHT
BN_mod_inverse() is available in all versions of SSLeay and OpenSSL.
Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

43
doc/crypto/BN_mod_mul_montgomery.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
BN_mod_mul_montgomery, BN_MONT_CTX_new, BN_MONT_CTX_init,
BN_mod_mul_montgomery, BN_MONT_CTX_new,
BN_MONT_CTX_free, BN_MONT_CTX_set, BN_MONT_CTX_copy,
BN_from_montgomery, BN_to_montgomery - Montgomery multiplication
@@ -11,7 +11,6 @@ BN_from_montgomery, BN_to_montgomery - Montgomery multiplication
#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);
@@ -29,12 +28,11 @@ BN_from_montgomery, BN_to_montgomery - Montgomery multiplication
=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,
automatically when L<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.
@@ -43,6 +41,7 @@ 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.
If B<mont> is NULL, nothing is done.
BN_mod_mul_montgomery() computes Mont(I<a>,I<b>):=I<a>*I<b>*R^-1 and places
the result in I<r>.
@@ -55,30 +54,15 @@ 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.
BN_MONT_CTX_free() has no return value.
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)>.
The error codes can be obtained by L<ERR_get_error(3)>.
=head1 WARNING
@@ -87,15 +71,20 @@ 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)>
L<ERR_get_error(3)>, L<BN_add(3)>,
L<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() was removed in OpenSSL 1.1.0
BN_MONT_CTX_init() and BN_MONT_CTX_copy() were added in SSLeay 0.9.1b.
=head1 COPYRIGHT
Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

41
doc/crypto/BN_mod_mul_reciprocal.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
BN_mod_mul_reciprocal, BN_div_recp, BN_RECP_CTX_new, BN_RECP_CTX_init,
BN_mod_mul_reciprocal, BN_div_recp, BN_RECP_CTX_new,
BN_RECP_CTX_free, BN_RECP_CTX_set - modular multiplication using
reciprocal
@@ -11,7 +11,6 @@ reciprocal
#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);
@@ -25,16 +24,16 @@ reciprocal
=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
L<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.
If B<recp> is NULL, nothing is done.
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
@@ -44,38 +43,34 @@ 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.
The B<BN_RECP_CTX> structure 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.
BN_RECP_CTX_free() has no return value.
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)>.
The error codes can be obtained by L<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)>
L<ERR_get_error(3)>, L<BN_add(3)>,
L<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.
BN_RECP_CTX_init() was removed in OpenSSL 1.1.0
=head1 COPYRIGHT
Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

35
doc/crypto/BN_new.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
BN_new, BN_init, BN_clear, BN_free, BN_clear_free - allocate and free BIGNUMs
BN_new, BN_secure_new, BN_clear, BN_free, BN_clear_free - allocate and free BIGNUMs
=head1 SYNOPSIS
@@ -10,7 +10,7 @@ BN_new, BN_init, BN_clear, BN_free, BN_clear_free - allocate and free BIGNUMs
BIGNUM *BN_new(void);
void BN_init(BIGNUM *);
BIGNUM *BN_secure_new(void);
void BN_clear(BIGNUM *a);
@@ -20,8 +20,9 @@ BN_new, BN_init, BN_clear, BN_free, BN_clear_free - allocate and free BIGNUMs
=head1 DESCRIPTION
BN_new() allocates and initializes a B<BIGNUM> structure. BN_init()
initializes an existing uninitialized B<BIGNUM>.
BN_new() allocates and initializes a B<BIGNUM> structure.
BN_secure_new() does the same except that the secure heap
OPENSSL_secure_malloc(3) is used to store the value.
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
@@ -30,24 +31,32 @@ 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.
If B<a> is NULL, nothing is done.
=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_new() and BN_secure_new()
return a pointer to the B<BIGNUM>. If the allocation fails,
they return B<NULL> and set an error code that can be obtained
by L<ERR_get_error(3)>.
BN_init(), BN_clear(), BN_free() and BN_clear_free() have no return
values.
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)>
L<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.
BN_init() was removed in OpenSSL 1.1.0; use BN_new() instead.
=head1 COPYRIGHT
Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

14
doc/crypto/BN_num_bytes.pod
View File

@@ -46,12 +46,16 @@ 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)>
L<DH_size(3)>, L<DSA_size(3)>,
L<RSA_size(3)>
=head1 HISTORY
=head1 COPYRIGHT
BN_num_bytes(), BN_num_bits() and BN_num_bits_word() are available in
all versions of SSLeay and OpenSSL.
Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

34
doc/crypto/BN_rand.pod
View File

@@ -21,15 +21,18 @@ BN_rand, BN_pseudo_rand, BN_rand_range, BN_pseudo_rand_range - generate pseudo-r
BN_rand() generates a cryptographically strong pseudo-random number of
B<bits> in length and stores it in B<rnd>.
If B<bits> is less than zero, or too small to
accomodate the requirements specified by the B<top> and B<bottom>
accommodate the requirements specified by the B<top> and B<bottom>
parameters, an error is returned.
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 B<top> parameters specifies
requirements on the most significant bit of the generated number.
If it is B<BN_RAND_TOP_ANY>, there is no constraint.
If it is B<BN_RAND_TOP_ONE>, the top bit must be one.
If it is B<BN_RAND_TOP_TWO>, 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.
numbers will always have 2*B<bits> length.
If B<bottom> is B<BN_RAND_BOTTOM_ODD>, the number will be odd; if it
is B<BN_RAND_BOTTOM_ANY> it can be odd or even.
If B<bits> is 1 then B<top> cannot also be B<BN_RAND_FLG_TOPTWO>.
BN_pseudo_rand() does the same, but pseudo-random numbers generated by
this function are not necessarily unpredictable. They can be used for
@@ -46,18 +49,19 @@ 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)>.
The error codes can be obtained by L<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)>
L<ERR_get_error(3)>, L<RAND_add(3)>, L<RAND_bytes(3)>
=head1 HISTORY
=head1 COPYRIGHT
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.
Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

15
doc/crypto/BN_set_bit.pod
View File

@@ -51,16 +51,19 @@ For the shift functions, B<r> and B<a> may be the same variable.
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)>.
can be obtained by L<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)>
L<BN_num_bytes(3)>, L<BN_add(3)>
=head1 HISTORY
=head1 COPYRIGHT
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.
Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

9
doc/crypto/BN_swap.pod
View File

@@ -14,10 +14,13 @@ BN_swap - exchange BIGNUMs
BN_swap() exchanges the values of I<a> and I<b>.
L<bn(3)|bn(3)>
=head1 COPYRIGHT
=head1 HISTORY
Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
BN_swap was added in OpenSSL 0.9.7.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

26
doc/crypto/BN_zero.pod
View File

@@ -9,7 +9,7 @@ operations
#include <openssl/bn.h>
int BN_zero(BIGNUM *a);
void BN_zero(BIGNUM *a);
int BN_one(BIGNUM *a);
const BIGNUM *BN_value_one(void);
@@ -17,6 +17,12 @@ operations
int BN_set_word(BIGNUM *a, unsigned long w);
unsigned long BN_get_word(BIGNUM *a);
Deprecated:
#if OPENSSL_API_COMPAT < 0x00908000L
int BN_zero(BIGNUM *a);
#endif
=head1 DESCRIPTION
BN_zero(), BN_one() and BN_set_word() set B<a> to the values 0, 1 and
@@ -33,8 +39,10 @@ long.
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_one(), BN_set_word() and the deprecated version of BN_zero()
return 1 on success, 0 otherwise.
BN_value_one() returns the constant.
The preferred version of BN_zero() never fails and returns no value.
=head1 BUGS
@@ -45,15 +53,15 @@ 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)>
L<BN_bn2bin(3)>
=head1 HISTORY
=head1 COPYRIGHT
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.
Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
BN_value_one() was changed to return a true const BIGNUM * in OpenSSL
0.9.7.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

77
doc/crypto/BUF_MEM_new.pod Normal file
View File

@@ -0,0 +1,77 @@
=pod
=head1 NAME
BUF_MEM_new, BUF_MEM_new_ex, BUF_MEM_free, BUF_MEM_grow
BUF_MEM_grow_clean, BUF_reverse
- simple character array structure
standard C library equivalents
=head1 SYNOPSIS
#include <openssl/buffer.h>
BUF_MEM *BUF_MEM_new(void);
BUF_MEM *BUF_MEM_new_ex(unsigned long flags);
void BUF_MEM_free(BUF_MEM *a);
int BUF_MEM_grow(BUF_MEM *str, int len);
size_t BUF_MEM_grow_clean(BUF_MEM *str, size_t len);
void BUF_reverse(unsigned char *out, const unsigned char *in, size_t size);
=head1 DESCRIPTION
The buffer library handles simple character arrays. Buffers are used for
various purposes in the library, most notably memory BIOs.
BUF_MEM_new() allocates a new buffer of zero size.
BUF_MEM_new_ex() allocates a buffer with the specified flags.
The flag B<BUF_MEM_FLAG_SECURE> specifies that the B<data> pointer
should be allocated on the secure heap; see L<CRYPTO_secure_malloc(3)>.
BUF_MEM_free() frees up an already existing buffer. The data is zeroed
before freeing up in case the buffer contains sensitive data.
BUF_MEM_grow() changes the size of an already existing buffer to
B<len>. Any data already in the buffer is preserved if it increases in
size.
BUF_MEM_grow_clean() is similar to BUF_MEM_grow() but it sets any free'd
or additionally-allocated memory to zero.
BUF_reverse() reverses B<size> bytes at B<in> into B<out>. If B<in>
is NULL, the array is reversed in-place.
=head1 RETURN VALUES
BUF_MEM_new() returns the buffer or NULL on error.
BUF_MEM_free() has no return value.
BUF_MEM_grow() and BUF_MEM_grow_clean() return
zero on error or the new size (i.e., B<len>).
=head1 SEE ALSO
L<bio(7)>,
L<CRYPTO_secure_malloc(3)>.
=head1 HISTORY
BUF_MEM_new_ex() was added in OpenSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

23
doc/crypto/CMS_add0_cert.pod
View File

@@ -2,7 +2,8 @@
=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
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
@@ -20,7 +21,7 @@ CMS_add0_cert, CMS_add1_cert, CMS_get1_certs, CMS_add0_crl, CMS_add1_crl, CMS_ge
=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.
must be of type signed data or enveloped data.
CMS_get1_certs() returns all certificates in B<cms>.
@@ -46,7 +47,7 @@ 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.
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
@@ -54,13 +55,17 @@ 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)>
L<ERR_get_error(3)>,
L<CMS_sign(3)>,
L<CMS_encrypt(3)>
=head1 HISTORY
=head1 COPYRIGHT
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
Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

16
doc/crypto/CMS_add1_recipient_cert.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
CMS_add1_recipient_cert, CMS_add0_recipient_key - add recipients to a CMS enveloped data structure
CMS_add1_recipient_cert, CMS_add0_recipient_key - add recipients to a CMS enveloped data structure
=head1 SYNOPSIS
@@ -51,12 +51,16 @@ 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)>,
L<ERR_get_error(3)>, L<CMS_decrypt(3)>,
L<CMS_final(3)>,
=head1 HISTORY
=head1 COPYRIGHT
CMS_add1_recipient_cert() and CMS_add0_recipient_key() were added to OpenSSL
0.9.8
Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

19
doc/crypto/CMS_add1_signer.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
CMS_add1_signer, CMS_SignerInfo_sign - add a signer to a CMS_ContentInfo signed data structure.
CMS_add1_signer, CMS_SignerInfo_sign - add a signer to a CMS_ContentInfo signed data structure
=head1 SYNOPSIS
@@ -52,7 +52,7 @@ 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
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.
@@ -81,7 +81,7 @@ If any of these algorithms is not available then it will not be included: for ex
not loaded.
CMS_add1_signer() returns an internal pointer to the CMS_SignerInfo
structure just added, this can be used to set additional attributes
structure just added, this can be used to set additional attributes
before it is finalized.
=head1 RETURN VALUES
@@ -91,11 +91,16 @@ 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)>,
L<ERR_get_error(3)>, L<CMS_sign(3)>,
L<CMS_final(3)>,
=head1 HISTORY
=head1 COPYRIGHT
CMS_add1_signer() was added to OpenSSL 0.9.8
Copyright 2014-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

14
doc/crypto/CMS_compress.pod
View File

@@ -63,11 +63,19 @@ 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)>
L<ERR_get_error(3)>, L<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.
The B<CMS_STREAM> flag was added in OpenSSL 1.0.0.
=head1 COPYRIGHT
Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

16
doc/crypto/CMS_decrypt.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
CMS_decrypt - decrypt content from a CMS envelopedData structure
CMS_decrypt - decrypt content from a CMS envelopedData structure
=head1 SYNOPSIS
@@ -22,9 +22,6 @@ 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.
@@ -70,10 +67,15 @@ 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)>
L<ERR_get_error(3)>, L<CMS_encrypt(3)>
=head1 HISTORY
=head1 COPYRIGHT
CMS_decrypt() was added to OpenSSL 0.9.8
Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

16
doc/crypto/CMS_encrypt.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
CMS_encrypt - create a CMS envelopedData structure
CMS_encrypt - create a CMS envelopedData structure
=head1 SYNOPSIS
@@ -26,7 +26,7 @@ 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.
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
@@ -86,11 +86,19 @@ 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)>
L<ERR_get_error(3)>, L<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.
=head1 COPYRIGHT
Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

17
doc/crypto/CMS_final.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
CMS_final - finalise a CMS_ContentInfo structure
CMS_final - finalise a CMS_ContentInfo structure
=head1 SYNOPSIS
@@ -14,7 +14,7 @@
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
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.
@@ -31,11 +31,16 @@ 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)>
L<ERR_get_error(3)>, L<CMS_sign(3)>,
L<CMS_encrypt(3)>
=head1 HISTORY
=head1 COPYRIGHT
CMS_final() was added to OpenSSL 0.9.8
Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

22
doc/crypto/CMS_get0_RecipientInfos.pod
View File

@@ -2,7 +2,12 @@
=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
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
@@ -34,7 +39,7 @@ 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>.
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.
@@ -107,14 +112,19 @@ 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)>.
Any error can be obtained from L<ERR_get_error(3)>.
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_decrypt(3)|CMS_decrypt(3)>
L<ERR_get_error(3)>, L<CMS_decrypt(3)>
=head1 HISTORY
=head1 COPYRIGHT
These functions were first was added to OpenSSL 0.9.8
Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

20
doc/crypto/CMS_get0_SignerInfos.pod
View File

@@ -2,7 +2,10 @@
=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.
CMS_SignerInfo_set1_signer_cert,
CMS_get0_SignerInfos, CMS_SignerInfo_get0_signer_id,
CMS_SignerInfo_get0_signature, CMS_SignerInfo_cert_cmp
- CMS signedData signer functions
=head1 SYNOPSIS
@@ -25,7 +28,7 @@ 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
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.
@@ -68,14 +71,19 @@ 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)>
Any error can be obtained from L<ERR_get_error(3)>
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_verify(3)|CMS_verify(3)>
L<ERR_get_error(3)>, L<CMS_verify(3)>
=head1 HISTORY
=head1 COPYRIGHT
These functions were first was added to OpenSSL 0.9.8
Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

16
doc/crypto/CMS_get0_type.pod
View File

@@ -2,13 +2,13 @@
=head1 NAME
CMS_get0_type, CMS_set1_eContentType, CMS_get0_eContentType, CMS_get0_content - get and set CMS content types and content
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);
const ASN1_OBJECT *CMS_get0_type(const 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);
@@ -67,11 +67,15 @@ error can be obtained from ERR_get_error(3).
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>
L<ERR_get_error(3)>
=head1 HISTORY
=head1 COPYRIGHT
CMS_get0_type(), CMS_set1_eContentType() and CMS_get0_eContentType() were all
first added to OpenSSL 0.9.8
Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

21
doc/crypto/CMS_get1_ReceiptRequest.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
CMS_ReceiptRequest_create0, CMS_add1_ReceiptRequest, CMS_get1_ReceiptRequest, CMS_ReceiptRequest_get0_values - CMS signed receipt request functions.
CMS_ReceiptRequest_create0, CMS_add1_ReceiptRequest, CMS_get1_ReceiptRequest, CMS_ReceiptRequest_get0_values - CMS signed receipt request functions
=head1 SYNOPSIS
@@ -45,7 +45,7 @@ CMS_verify().
=head1 RETURN VALUES
CMS_ReceiptRequest_create0() returns a signed receipt request structure or
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.
@@ -56,14 +56,17 @@ 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)>
L<ERR_get_error(3)>, L<CMS_sign(3)>,
L<CMS_sign_receipt(3)>, L<CMS_verify(3)>
L<CMS_verify_receipt(3)>
=head1 HISTORY
=head1 COPYRIGHT
CMS_ReceiptRequest_create0(), CMS_add1_ReceiptRequest(),
CMS_get1_ReceiptRequest() and CMS_ReceiptRequest_get0_values() were added to
OpenSSL 0.9.8
Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

19
doc/crypto/CMS_sign.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
CMS_sign - create a CMS SignedData structure
CMS_sign - create a CMS SignedData structure
=head1 SYNOPSIS
@@ -95,8 +95,8 @@ 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.
attributes added. CMS_final() must then be called to finalize the
structure if streaming is not enabled.
=head1 BUGS
@@ -109,13 +109,20 @@ 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)>
L<ERR_get_error(3)>, L<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.
=head1 COPYRIGHT
Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

17
doc/crypto/CMS_sign_receipt.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
CMS_sign_receipt - create a CMS signed receipt
CMS_sign_receipt - create a CMS signed receipt
=head1 SYNOPSIS
@@ -34,12 +34,17 @@ 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)>
L<ERR_get_error(3)>,
L<CMS_verify_receipt(3)>,
L<CMS_sign(3)>
=head1 HISTORY
=head1 COPYRIGHT
CMS_sign_receipt() was added to OpenSSL 0.9.8
Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

13
doc/crypto/CMS_uncompress.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
CMS_uncompress - uncompress a CMS CompressedData structure
CMS_uncompress - uncompress a CMS CompressedData structure
=head1 SYNOPSIS
@@ -45,10 +45,15 @@ 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)>
L<ERR_get_error(3)>, L<CMS_compress(3)>
=head1 HISTORY
=head1 COPYRIGHT
CMS_uncompress() was added to OpenSSL 0.9.8
Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

21
doc/crypto/CMS_verify.pod
View File

@@ -67,7 +67,7 @@ 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
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.
@@ -81,13 +81,13 @@ 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
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
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
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.
@@ -104,7 +104,7 @@ 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)>
The error can be obtained from L<ERR_get_error(3)>
=head1 BUGS
@@ -117,10 +117,15 @@ 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)>
L<ERR_get_error(3)>, L<CMS_sign(3)>
=head1 HISTORY
=head1 COPYRIGHT
CMS_verify() was added to OpenSSL 0.9.8
Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

21
doc/crypto/CMS_verify_receipt.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
CMS_verify_receipt - verify a CMS signed receipt
CMS_verify_receipt - verify a CMS signed receipt
=head1 SYNOPSIS
@@ -16,7 +16,7 @@ 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).
verification).
B<flags> is an optional set of flags, which can be used to modify the verify
operation.
@@ -32,16 +32,21 @@ supported since they do not make sense in the context of signed receipts.
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)>
The error can be obtained from L<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)>,
L<ERR_get_error(3)>,
L<CMS_sign_receipt(3)>,
L<CMS_verify(3)>,
=head1 HISTORY
=head1 COPYRIGHT
CMS_verify_receipt() was added to OpenSSL 0.9.8
Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

33
doc/crypto/CONF_modules_free.pod
View File

@@ -2,17 +2,22 @@
=head1 NAME
CONF_modules_free, CONF_modules_finish, CONF_modules_unload -
OpenSSL configuration cleanup functions
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);
Deprecated:
#if OPENSSL_API_COMPAT < 0x10100000L
void CONF_modules_free(void)
#endif
=head1 DESCRIPTION
CONF_modules_free() closes down and frees up all memory allocated by all
@@ -27,8 +32,10 @@ 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.
Normally in versions of OpenSSL prior to 1.1.0 applications will only call
CONF_modules_free() at application exit to tidy up any configuration performed.
From 1.1.0 CONF_modules_free() is deprecated and no explicit CONF cleanup is
required at all. For more information see L<OPENSSL_init_crypto(3)>.
=head1 RETURN VALUE
@@ -36,12 +43,20 @@ None of the functions return a value.
=head1 SEE ALSO
L<conf(5)|conf(5)>, L<OPENSSL_config(3)|OPENSSL_config(3)>,
L<CONF_modules_load_file(3)|CONF_modules_load_file(3)>
L<conf(5)>, L<OPENSSL_config(3)>,
L<CONF_modules_load_file(3)>
=head1 HISTORY
CONF_modules_free(), CONF_modules_unload(), and CONF_modules_finish()
first appeared in OpenSSL 0.9.7.
CONF_modules_free() was deprecated in OpenSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

28
doc/crypto/CONF_modules_load_file.pod
View File

@@ -2,16 +2,16 @@
=head1 NAME
CONF_modules_load_file, CONF_modules_load - OpenSSL configuration functions
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);
unsigned long flags);
int CONF_modules_load(const CONF *cnf, const char *appname,
unsigned long flags);
unsigned long flags);
=head1 DESCRIPTION
@@ -19,9 +19,9 @@ 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>.
The behaviour can be customized using B<flags>.
CONF_modules_load() is idential to CONF_modules_load_file() except it
CONF_modules_load() is identical to CONF_modules_load_file() except it
reads configuration information from B<cnf>.
=head1 NOTES
@@ -45,12 +45,6 @@ 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
@@ -127,11 +121,15 @@ return value of the failing module (this will always be zero or negative).
=head1 SEE ALSO
L<conf(5)|conf(5)>, L<OPENSSL_config(3)|OPENSSL_config(3)>,
L<CONF_free(3)|CONF_free(3)>, L<err(3)|err(3)>
L<config(5)>, L<OPENSSL_config(3)>
=head1 HISTORY
=head1 COPYRIGHT
CONF_modules_load_file and CONF_modules_load first appeared in OpenSSL 0.9.7.
Copyright 2004-2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

170
doc/crypto/CRYPTO_THREAD_run_once.pod Normal file
View File

@@ -0,0 +1,170 @@
=pod
=head1 NAME
CRYPTO_THREAD_run_once,
CRYPTO_THREAD_lock_new, CRYPTO_THREAD_read_lock, CRYPTO_THREAD_write_lock,
CRYPTO_THREAD_unlock, CRYPTO_THREAD_lock_free, CRYPTO_atomic_add - OpenSSL thread support
=head1 SYNOPSIS
#include <openssl/crypto.h>
CRYPTO_ONCE CRYPTO_ONCE_STATIC_INIT;
int CRYPTO_THREAD_run_once(CRYPTO_ONCE *once, void (*init)(void));
CRYPTO_RWLOCK *CRYPTO_THREAD_lock_new(void);
int CRYPTO_THREAD_read_lock(CRYPTO_RWLOCK *lock);
int CRYPTO_THREAD_write_lock(CRYPTO_RWLOCK *lock);
int CRYPTO_THREAD_unlock(CRYPTO_RWLOCK *lock);
void CRYPTO_THREAD_lock_free(CRYPTO_RWLOCK *lock);
int CRYPTO_atomic_add(int *val, int amount, int *ret, CRYPTO_RWLOCK *lock);
=head1 DESCRIPTION
OpenSSL can be safely used in multi-threaded applications provided that
support for the underlying OS threading API is built-in. Currently, OpenSSL
supports the pthread and Windows APIs. OpenSSL can also be built without
any multi-threading support, for example on platforms that don't provide
any threading support or that provide a threading API that is not yet
supported by OpenSSL.
The following multi-threading function are provided:
=over 2
=item *
CRYPTO_THREAD_run_once() can be used to perform one-time initialization.
The B<once> argument must be a pointer to a static object of type
B<CRYPTO_ONCE> that was statically initialized to the value
B<CRYPTO_ONCE_STATIC_INIT>.
The B<init> argument is a pointer to a function that performs the desired
exactly once initialization.
In particular, this can be used to allocate locks in a thread-safe manner,
which can then be used with the locking functions below.
=item *
CRYPTO_THREAD_lock_new() allocates, initializes and returns a new read/write
lock.
=item *
CRYPTO_THREAD_read_lock() locks the provided B<lock> for reading.
=item *
CRYPTO_THREAD_write_lock() locks the provided B<lock> for writing.
=item *
CRYPTO_THREAD_unlock() unlocks the previously locked B<lock>.
=item *
CRYPTO_THREAD_lock_frees() frees the provided B<lock>.
=item *
CRYPTO_atomic_add() atomically adds B<amount> to B<val> and returns the
result of the operation in B<ret>. B<lock> will be locked, unless atomic
operations are supported on the specific platform. Because of this, if a
variable is modified by CRYPTO_atomic_add() then CRYPTO_atomic_add() must
be the only way that the variable is modified.
=back
=head1 RETURN VALUES
CRYPTO_THREAD_run_once() returns 1 on success, or 0 on error.
CRYPTO_THREAD_lock_new() returns the allocated lock, or NULL on error.
CRYPTO_THREAD_lock_frees() returns no value.
The other functions return 1 on success or 0 on error.
=head1 NOTES
On Windows platforms the CRYPTO_THREAD_* types and functions in the
openssl/crypto.h header are dependent on some of the types customarily
made available by including windows.h. The application developer is
likely to require control over when the latter is included, commonly as
one of the first included headers. Therefore it is defined as an
application developer's responsibility to include windows.h prior to
crypto.h where use of CRYPTO_THREAD_* types and functions is required.
=head1 EXAMPLE
This example safely initializes and uses a lock.
#ifdef _WIN32
# include <windows.h>
#endif
#include <openssl/crypto.h>
static CRYPTO_ONCE once = CRYPTO_ONCE_STATIC_INIT;
static CRYPTO_RWLOCK *lock;
static void myinit(void)
{
lock = CRYPTO_THREAD_lock_new();
}
static int mylock(void)
{
if (!CRYPTO_THREAD_run_once(&once, void init) || lock == NULL)
return 0;
return CRYPTO_THREAD_write_lock(lock);
}
static int myunlock(void)
{
return CRYPTO_THREAD_unlock(lock);
}
int serialized(void)
{
int ret = 0;
if (mylock()) {
/* Your code here, do not return without releasing the lock! */
ret = ... ;
}
myunlock();
return ret;
}
Finalization of locks is an advanced topic, not covered in this example.
This can only be done at process exit or when a dynamically loaded library is
no longer in use and is unloaded.
The simplest solution is to just "leak" the lock in applications and not
repeatedly load/unload shared libraries that allocate locks.
=head1 NOTES
You can find out if OpenSSL was configured with thread support:
#include <openssl/opensslconf.h>
#if defined(OPENSSL_THREADS)
// thread support enabled
#else
// no thread support
#endif
=head1 SEE ALSO
L<crypto(7)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

165
doc/crypto/CRYPTO_get_ex_new_index.pod Normal file
View File

@@ -0,0 +1,165 @@
=pod
=head1 NAME
CRYPTO_EX_new, CRYPTO_EX_free, CRYPTO_EX_dup,
CRYPTO_free_ex_index, CRYPTO_get_ex_new_index, CRYPTO_set_ex_data,
CRYPTO_get_ex_data, CRYPTO_free_ex_data, CRYPTO_new_ex_data
- functions supporting application-specific data
=head1 SYNOPSIS
#include <openssl/crypto.h>
int CRYPTO_get_ex_new_index(int class_index,
long argl, void *argp,
CRYPTO_EX_new *new_func,
CRYPTO_EX_dup *dup_func,
CRYPTO_EX_free *free_func);
typedef int CRYPTO_EX_new(void *parent, void *ptr, CRYPTO_EX_DATA *ad,
int idx, long argl, void *argp);
typedef void CRYPTO_EX_free(void *parent, void *ptr, CRYPTO_EX_DATA *ad,
int idx, long argl, void *argp);
typedef int CRYPTO_EX_dup(CRYPTO_EX_DATA *to, const CRYPTO_EX_DATA *from,
void *from_d, int idx, long argl, void *argp);
int CRYPTO_new_ex_data(int class_index, void *obj, CRYPTO_EX_DATA *ad)
int CRYPTO_set_ex_data(CRYPTO_EX_DATA *r, int idx, void *arg);
void *CRYPTO_get_ex_data(CRYPTO_EX_DATA *r, int idx);
void CRYPTO_free_ex_data(int class_index, void *obj, CRYPTO_EX_DATA *r);
int CRYPTO_free_ex_index(int class_index, int idx);
=head1 DESCRIPTION
Several OpenSSL structures can have application-specific data attached to them,
known as "exdata."
The specific structures are:
SSL
SSL_CTX
SSL_SESSION
X509
X509_STORE
X509_STORE_CTX
DH
DSA
EC_KEY
RSA
ENGINE
UI
UI_METHOD
BIO
Each is identified by an B<CRYPTO_EX_INDEX_xxx> define in the B<crypto.h>
header file. In addition, B<CRYPTO_EX_INDEX_APP> is reserved for
applications to use this facility for their own structures.
The API described here is used by OpenSSL to manipulate exdata for specific
structures. Since the application data can be anything at all it is passed
and retrieved as a B<void *> type.
The B<CRYPTO_EX_DATA> type is opaque. To initialize the exdata part of
a structure, call CRYPTO_new_ex_data(). This is only necessary for
B<CRYPTO_EX_INDEX_APP> objects.
Exdata types are identified by an B<index>, an integer guaranteed to be
unique within structures for the lifetime of the program. Applications
using exdata typically call B<CRYPTO_get_ex_new_index> at startup, and
store the result in a global variable, or write a wrapper function to
provide lazy evaluation. The B<class_index> should be one of the
B<CRYPTO_EX_INDEX_xxx> values. The B<argl> and B<argp> parameters are saved
to be passed to the callbacks but are otherwise not used. In order to
transparently manipulate exdata, three callbacks must be provided. The
semantics of those callbacks are described below.
When copying or releasing objects with exdata, the callback functions
are called in increasing order of their B<index> value.
If a dynamic library can be unloaded, it should call CRYPTO_free_ex_index()
when this is done.
This will replace the callbacks with no-ops
so that applications don't crash. Any existing exdata will be leaked.
To set or get the exdata on an object, the appropriate type-specific
routine must be used. This is because the containing structure is opaque
and the B<CRYPTO_EX_DATA> field is not accessible. In both API's, the
B<idx> parameter should be an already-created index value.
When setting exdata, the pointer specified with a particular index is saved,
and returned on a subsequent "get" call. If the application is going to
release the data, it must make sure to set a B<NULL> value at the index,
to avoid likely double-free crashes.
The function B<CRYPTO_free_ex_data> is used to free all exdata attached
to a structure. The appropriate type-specific routine must be used.
The B<class_index> identifies the structure type, the B<obj> is
be the pointer to the actual structure, and B<r> is a pointer to the
structure's exdata field.
=head2 Callback Functions
This section describes how the callback functions are used. Applications
that are defining their own exdata using B<CYPRTO_EX_INDEX_APP> must
call them as described here.
When a structure is initially allocated (such as RSA_new()) then the
new_func() is called for every defined index. There is no requirement
that the entire parent, or containing, structure has been set up.
The new_func() is typically used only to allocate memory to store the
exdata, and perhaps an "initialized" flag within that memory.
The exdata value should be set by calling CRYPTO_set_ex_data().
When a structure is free'd (such as SSL_CTX_free()) then the
free_func() is called for every defined index. Again, the state of the
parent structure is not guaranteed. The free_func() may be called with a
NULL pointer.
Both new_func() and free_func() take the same parameters.
The B<parent> is the pointer to the structure that contains the exdata.
The B<ptr> is the current exdata item; for new_func() this will typically
be NULL. The B<r> parameter is a pointer to the exdata field of the object.
The B<idx> is the index and is the value returned when the callbacks were
initially registered via CRYPTO_get_ex_new_index() and can be used if
the same callback handles different types of exdata.
dup_func() is called when a structure is being copied. This is only done
for B<SSL> and B<SSL_SESSION> objects. The B<to> and B<from> parameters
are pointers to the destination and source B<CRYPTO_EX_DATA> structures,
respectively. The B<from_d> parameter needs to be cast to a B<void **pptr>
as the API has currently the wrong signature; that will be changed in a
future version. The B<*pptr> is a pointer to the source exdata.
When the dup_func() returns, the value in B<*pptr> is copied to the
destination ex_data. If the pointer contained in B<*pptr> is not modified
by the dup_func(), then both B<to> and B<from> will point to the same data.
The B<idx>, B<argl> and B<argp> parameters are as described for the other
two callbacks. If the dup_func() returns B<0> the whole CRYPTO_dup_ex_data()
will fail.
=head1 RETURN VALUES
CRYPTO_get_ex_new_index() returns a new index or -1 on failure; the
value B<0> is reserved for the legacy "app_data" API's.
CRYPTO_free_ex_index() and
CRYPTO_set_ex_data() return 1 on success or 0 on failure.
CRYPTO_get_ex_data() returns the application data or NULL on failure;
note that NULL may be a valid value.
dup_func() should return 0 for failure and 1 for success.
=head1 COPYRIGHT
Copyright 2015-2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

53
doc/crypto/CRYPTO_set_ex_data.pod
View File

@@ -1,53 +0,0 @@
=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

49
doc/crypto/CTLOG_STORE_get0_log_by_id.pod Normal file
View File

@@ -0,0 +1,49 @@
=pod
=head1 NAME
CTLOG_STORE_get0_log_by_id -
Get a Certificate Transparency log from a CTLOG_STORE
=head1 SYNOPSIS
#include <openssl/ct.h>
const CTLOG *CTLOG_STORE_get0_log_by_id(const CTLOG_STORE *store,
const uint8_t *log_id,
size_t log_id_len);
=head1 DESCRIPTION
A Signed Certificate Timestamp (SCT) identifies the Certificate Transparency
(CT) log that issued it using the log's LogID (see RFC 6962, Section 3.2).
Therefore, it is useful to be able to look up more information about a log
(e.g. its public key) using this LogID.
CTLOG_STORE_get0_log_by_id() provides a way to do this. It will find a CTLOG
in a CTLOG_STORE that has a given LogID.
=head1 RETURN VALUES
B<CTLOG_STORE_get0_log_by_id> returns a CTLOG with the given LogID, if it
exists in the given CTLOG_STORE, otherwise it returns NULL.
=head1 SEE ALSO
L<ct(3)>,
L<CTLOG_STORE_new(3)>
=head1 HISTORY
This function was added in OpenSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

79
doc/crypto/CTLOG_STORE_new.pod Normal file
View File

@@ -0,0 +1,79 @@
=pod
=head1 NAME
CTLOG_STORE_new, CTLOG_STORE_free,
CTLOG_STORE_load_default_file, CTLOG_STORE_load_file -
Create and populate a Certificate Transparency log list
=head1 SYNOPSIS
#include <openssl/ct.h>
CTLOG_STORE *CTLOG_STORE_new(void);
void CTLOG_STORE_free(CTLOG_STORE *store);
int CTLOG_STORE_load_default_file(CTLOG_STORE *store);
int CTLOG_STORE_load_file(CTLOG_STORE *store, const char *file);
=head1 DESCRIPTION
A CTLOG_STORE is a container for a list of CTLOGs (Certificate Transparency
logs). The list can be loaded from one or more files and then searched by LogID
(see RFC 6962, Section 3.2, for the definition of a LogID).
CTLOG_STORE_new() creates an empty list of CT logs. This is then populated
by CTLOG_STORE_load_default_file() or CTLOG_STORE_load_file().
CTLOG_STORE_load_default_file() loads from the default file, which is named
"ct_log_list.cnf" in OPENSSLDIR (see the output of L<version>). This can be
overridden using an environment variable named "CTLOG_FILE".
CTLOG_STORE_load_file() loads from a caller-specified file path instead.
Both of these functions append any loaded CT logs to the CTLOG_STORE.
The expected format of the file is:
enabled_logs=foo,bar
[foo]
description = Log 1
key = <base64-encoded DER SubjectPublicKeyInfo here>
[bar]
description = Log 2
key = <base64-encoded DER SubjectPublicKeyInfo here>
Once a CTLOG_STORE is no longer required, it should be passed to
CTLOG_STORE_free(). This will delete all of the CTLOGs stored within, along
with the CTLOG_STORE itself.
=head1 NOTES
If there are any invalid CT logs in a file, they are skipped and the remaining
valid logs will still be added to the CTLOG_STORE. A CT log will be considered
invalid if it is missing a "key" or "description" field.
=head1 RETURN VALUES
Both B<CTLOG_STORE_load_default_file> and B<CTLOG_STORE_load_file> return 1 if
all CT logs in the file are successfully parsed and loaded, 0 otherwise.
=head1 SEE ALSO
L<ct(3)>,
L<CTLOG_STORE_get0_log_by_id(3)>,
L<SSL_CTX_set_ctlog_list_file(3)>
=head1 HISTORY
These functions were added in OpenSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

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

@@ -0,0 +1,72 @@
=pod
=head1 NAME
CTLOG_new, CTLOG_new_from_base64, CTLOG_free,
CTLOG_get0_name, CTLOG_get0_log_id, CTLOG_get0_public_key -
encapsulates information about a Certificate Transparency log
=head1 SYNOPSIS
#include <openssl/ct.h>
CTLOG *CTLOG_new(EVP_PKEY *public_key, const char *name);
int CTLOG_new_from_base64(CTLOG ** ct_log,
const char *pkey_base64, const char *name);
void CTLOG_free(CTLOG *log);
const char *CTLOG_get0_name(const CTLOG *log);
void CTLOG_get0_log_id(const CTLOG *log, const uint8_t **log_id,
size_t *log_id_len);
EVP_PKEY *CTLOG_get0_public_key(const CTLOG *log);
=head1 DESCRIPTION
CTLOG_new() returns a new CTLOG that represents the Certificate Transparency
(CT) log with the given public key. A name must also be provided that can be
used to help users identify this log. Ownership of the public key is
transferred.
CTLOG_new_from_base64() also creates a new CTLOG, but takes the public key in
base64-encoded DER form and sets the ct_log pointer to point to the new CTLOG.
The base64 will be decoded and the public key parsed.
Regardless of whether CTLOG_new() or CTLOG_new_from_base64() is used, it is the
caller's responsibility to pass the CTLOG to CTLOG_free() once it is no longer
needed. This will delete it and, if created by CTLOG_new(), the EVP_PKEY that
was passed to it.
CTLOG_get0_name() returns the name of the log, as provided when the CTLOG was
created. Ownership of the string remains with the CTLOG.
CTLOG_get0_log_id() sets *log_id to point to a string containing that log's
LogID (see RFC 6962). It sets *log_id_len to the length of that LogID. For a
v1 CT log, the LogID will be a SHA-256 hash (i.e. 32 bytes long). Ownership of
the string remains with the CTLOG.
CTLOG_get0_public_key() returns the public key of the CT log. Ownership of the
EVP_PKEY remains with the CTLOG.
=head1 RETURN VALUES
CTLOG_new() will return NULL if an error occurs.
CTLOG_new_from_base64() will return 1 on success, 0 otherwise.
=head1 SEE ALSO
L<ct(3)>
=head1 HISTORY
These functions were added in OpenSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

111
doc/crypto/CT_POLICY_EVAL_CTX_new.pod Normal file
View File

@@ -0,0 +1,111 @@
=pod
=head1 NAME
CT_POLICY_EVAL_CTX_new, CT_POLICY_EVAL_CTX_free,
CT_POLICY_EVAL_CTX_get0_cert, CT_POLICY_EVAL_CTX_set1_cert,
CT_POLICY_EVAL_CTX_get0_issuer, CT_POLICY_EVAL_CTX_set1_issuer,
CT_POLICY_EVAL_CTX_get0_log_store, CT_POLICY_EVAL_CTX_set_shared_CTLOG_STORE,
CT_POLICY_EVAL_CTX_get_time, CT_POLICY_EVAL_CTX_set_time -
Encapsulates the data required to evaluate whether SCTs meet a Certificate Transparency policy
=head1 SYNOPSIS
#include <openssl/ct.h>
CT_POLICY_EVAL_CTX *CT_POLICY_EVAL_CTX_new(void);
void CT_POLICY_EVAL_CTX_free(CT_POLICY_EVAL_CTX *ctx);
X509* CT_POLICY_EVAL_CTX_get0_cert(const CT_POLICY_EVAL_CTX *ctx);
int CT_POLICY_EVAL_CTX_set1_cert(CT_POLICY_EVAL_CTX *ctx, X509 *cert);
X509* CT_POLICY_EVAL_CTX_get0_issuer(const CT_POLICY_EVAL_CTX *ctx);
int CT_POLICY_EVAL_CTX_set1_issuer(CT_POLICY_EVAL_CTX *ctx, X509 *issuer);
const CTLOG_STORE *CT_POLICY_EVAL_CTX_get0_log_store(const CT_POLICY_EVAL_CTX *ctx);
void CT_POLICY_EVAL_CTX_set_shared_CTLOG_STORE(CT_POLICY_EVAL_CTX *ctx, CTLOG_STORE *log_store);
uint64_t CT_POLICY_EVAL_CTX_get_time(const CT_POLICY_EVAL_CTX *ctx);
void CT_POLICY_EVAL_CTX_set_time(CT_POLICY_EVAL_CTX *ctx, uint64_t time_in_ms);
=head1 DESCRIPTION
A B<CT_POLICY_EVAL_CTX> is used by functions that evaluate whether Signed
Certificate Timestamps (SCTs) fulfil a Certificate Transparency (CT) policy.
This policy may be, for example, that at least one valid SCT is available. To
determine this, an SCT's timestamp and signature must be verified.
This requires:
=over 4
=item * the public key of the log that issued the SCT
=item * the certificate that the SCT was issued for
=item * the issuer certificate (if the SCT was issued for a pre-certificate)
=item * the current time
=back
The above requirements are met using the setters described below.
CT_POLICY_EVAL_CTX_new() creates an empty policy evaluation context. This
should then be populated using:
=over 4
=item * CT_POLICY_EVAL_CTX_set1_cert() to provide the certificate the SCTs were issued for
Increments the reference count of the certificate.
=item * CT_POLICY_EVAL_CTX_set1_issuer() to provide the issuer certificate
Increments the reference count of the certificate.
=item * CT_POLICY_EVAL_CTX_set_shared_CTLOG_STORE() to provide a list of logs that are trusted as sources of SCTs
Holds a pointer to the CTLOG_STORE, so the CTLOG_STORE must outlive the
CT_POLICY_EVAL_CTX.
=item * CT_POLICY_EVAL_CTX_set_time() to set the time SCTs should be compared with to determine if they are valid
The SCT timestamp will be compared to this time to check whether the SCT was
issued in the future. RFC6962 states that "TLS clients MUST reject SCTs whose
timestamp is in the future". By default, this will be set to 5 minutes in the
future (e.g. (time() + 300) * 1000), to allow for clock drift.
The time should be in milliseconds since the Unix epoch.
=back
Each setter has a matching getter for accessing the current value.
When no longer required, the B<CT_POLICY_EVAL_CTX> should be passed to
CT_POLICY_EVAL_CTX_free() to delete it.
=head1 NOTES
The issuer certificate only needs to be provided if at least one of the SCTs
was issued for a pre-certificate. This will be the case for SCTs embedded in a
certificate (i.e. those in an X.509 extension), but may not be the case for SCTs
found in the TLS SCT extension or OCSP response.
=head1 RETURN VALUES
CT_POLICY_EVAL_CTX_new() will return NULL if malloc fails.
=head1 SEE ALSO
L<ct(7)>
=head1 HISTORY
These functions were added in OpenSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

241
doc/crypto/DEFINE_STACK_OF.pod Normal file
View File

@@ -0,0 +1,241 @@
=pod
=head1 NAME
DEFINE_STACK_OF, DEFINE_STACK_OF_CONST, DEFINE_SPECIAL_STACK_OF,
DEFINE_SPECIAL_STACK_OF_CONST,
OPENSSL_sk_deep_copy, OPENSSL_sk_delete, OPENSSL_sk_delete_ptr,
OPENSSL_sk_dup, OPENSSL_sk_find, OPENSSL_sk_find_ex, OPENSSL_sk_free,
OPENSSL_sk_insert, OPENSSL_sk_is_sorted, OPENSSL_sk_new, OPENSSL_sk_new_null,
OPENSSL_sk_num, OPENSSL_sk_pop, OPENSSL_sk_pop_free, OPENSSL_sk_push,
OPENSSL_sk_set, OPENSSL_sk_set_cmp_func, OPENSSL_sk_shift, OPENSSL_sk_sort,
OPENSSL_sk_unshift, OPENSSL_sk_value, OPENSSL_sk_zero,
sk_TYPE_num, sk_TYPE_value, sk_TYPE_new, sk_TYPE_new_null, sk_TYPE_free,
sk_TYPE_zero, sk_TYPE_delete, sk_TYPE_delete_ptr, sk_TYPE_push,
sk_TYPE_unshift, sk_TYPE_pop, sk_TYPE_shift, sk_TYPE_pop_free,
sk_TYPE_insert, sk_TYPE_set, sk_TYPE_find, sk_TYPE_find_ex, sk_TYPE_sort,
sk_TYPE_is_sorted, sk_TYPE_dup, sk_TYPE_deep_copy, sk_TYPE_set_cmp_func -
stack container
=for comment generic
=head1 SYNOPSIS
#include <openssl/safestack.h>
STACK_OF(TYPE)
DEFINE_STACK_OF(TYPE)
DEFINE_STACK_OF_CONST(TYPE)
DEFINE_SPECIAL_STACK_OF(FUNCTYPE, TYPE)
DEFINE_SPECIAL_STACK_OF_CONST(FUNCTYPE, TYPE)
typedef int (*sk_TYPE_compfunc)(const TYPE *const *a, const TYPE *const *b);
typedef TYPE * (*sk_TYPE_copyfunc)(const TYPE *a);
typedef void (*sk_TYPE_freefunc)(TYPE *a);
int sk_TYPE_num(const STACK_OF(TYPE) *sk);
TYPE *sk_TYPE_value(const STACK_OF(TYPE) *sk, int idx);
STACK_OF(TYPE) *sk_TYPE_new(sk_TYPE_compfunc compare);
STACK_OF(TYPE) *sk_TYPE_new_null(void);
void sk_TYPE_free(const STACK_OF(TYPE) *sk);
void sk_TYPE_zero(const STACK_OF(TYPE) *sk);
TYPE *sk_TYPE_delete(STACK_OF(TYPE) *sk, int i);
TYPE *sk_TYPE_delete_ptr(STACK_OF(TYPE) *sk, TYPE *ptr);
int sk_TYPE_push(STACK_OF(TYPE) *sk, const TYPE *ptr);
int sk_TYPE_unshift(STACK_OF(TYPE) *sk, const TYPE *ptr);
TYPE *sk_TYPE_pop(STACK_OF(TYPE) *sk);
TYPE *sk_TYPE_shift(STACK_OF(TYPE) *sk);
void sk_TYPE_pop_free(STACK_OF(TYPE) *sk, sk_TYPE_freefunc freefunc);
int sk_TYPE_insert(STACK_OF(TYPE) *sk, TYPE *ptr, int idx);
TYPE *sk_TYPE_set(STACK_OF(TYPE) *sk, int idx, const TYPE *ptr);
int sk_TYPE_find(STACK_OF(TYPE) *sk, TYPE *ptr);
int sk_TYPE_find_ex(STACK_OF(TYPE) *sk, TYPE *ptr);
void sk_TYPE_sort(const STACK_OF(TYPE) *sk);
int sk_TYPE_is_sorted(const STACK_OF(TYPE) *sk);
STACK_OF(TYPE) *sk_TYPE_dup(const STACK_OF(TYPE) *sk);
STACK_OF(TYPE) *sk_TYPE_deep_copy(const STACK_OF(TYPE) *sk,
sk_TYPE_copyfunc copyfunc,
sk_TYPE_freefunc freefunc);
sk_TYPE_compfunc (*sk_TYPE_set_cmp_func(STACK_OF(TYPE) *sk, sk_TYPE_compfunc compare);
=head1 DESCRIPTION
Applications can create and use their own stacks by placing any of the macros
described below in a header file. These macros define typesafe inline
functions that wrap around the utility B<OPENSSL_sk_> API.
In the description here, I<TYPE> is used
as a placeholder for any of the OpenSSL datatypes, such as I<X509>.
STACK_OF() returns the name for a stack of the specified B<TYPE>.
DEFINE_STACK_OF() creates set of functions for a stack of B<TYPE>. This
will mean that type B<TYPE> is stored in each stack, the type is referenced by
STACK_OF(TYPE) and each function name begins with I<sk_TYPE_>. For example:
TYPE *sk_TYPE_value(STACK_OF(TYPE) *sk, int idx);
DEFINE_STACK_OF_CONST() is identical to DEFINE_STACK_OF() except
each element is constant. For example:
const TYPE *sk_TYPE_value(STACK_OF(TYPE) *sk, int idx);
DEFINE_SPECIAL_STACK_OF() defines a stack of B<TYPE> but
each function uses B<FUNCNAME> in the function name. For example:
TYPE *sk_FUNCNAME_value(STACK_OF(TYPE) *sk, int idx);
DEFINE_SPECIAL_STACK_OF_CONST() is similar except that each element is
constant:
const TYPE *sk_FUNCNAME_value(STACK_OF(TYPE) *sk, int idx);
sk_TYPE_num() returns the number of elements in B<sk> or -1 if B<sk> is
B<NULL>.
sk_TYPE_value() returns element B<idx> in B<sk>, where B<idx> starts at
zero. If B<idx> is out of range then B<NULL> is returned.
sk_TYPE_new() allocates a new empty stack using comparison function B<compar>.
If B<compar> is B<NULL> then no comparison function is used.
sk_TYPE_new_null() allocates a new empty stack with no comparison function.
sk_TYPE_set_cmp_func() sets the comparison function of B<sk> to B<compar>.
The previous comparison function is returned or B<NULL> if there was
no previous comparison function.
sk_TYPE_free() frees up the B<sk> structure. It does B<not> free up any
elements of B<sk>. After this call B<sk> is no longer valid.
sk_TYPE_zero() sets the number of elements in B<sk> to zero. It does not free
B<sk> so after this call B<sk> is still valid.
sk_TYPE_pop_free() frees up all elements of B<sk> and B<sk> itself. The
free function freefunc() is called on each element to free it.
sk_TYPE_delete() deletes element B<i> from B<sk>. It returns the deleted
element or B<NULL> if B<i> is out of range.
sk_TYPE_delete_ptr() deletes element matching B<ptr> from B<sk>. It returns
the deleted element or B<NULL> if no element matching B<ptr> was found.
sk_TYPE_insert() inserts B<ptr> into B<sk> at position B<idx>. Any existing
elements at or after B<idx> are moved downwards. If B<idx> is out of range
the new element is appended to B<sk>. sk_TYPE_insert() either returns the
number of elements in B<sk> after the new element is inserted or zero if
an error (such as memory allocation failure) occurred.
sk_TYPE_push() appends B<ptr> to B<sk> it is equivalent to:
sk_TYPE_insert(sk, ptr, -1);
sk_TYPE_unshift() inserts B<ptr> at the start of B<sk> it is equivalent to:
sk_TYPE_insert(sk, ptr, 0);
sk_TYPE_pop() returns and removes the last element from B<sk>.
sk_TYPE_shift() returns and removes the first element from B<sk>.
sk_TYPE_set() sets element B<idx> of B<sk> to B<ptr> replacing the current
element. The new element value is returned or B<NULL> if an error occurred:
this will only happen if B<sk> is B<NULL> or B<idx> is out of range.
sk_TYPE_find() searches B<sk> for the element B<ptr>. In the case
where no comparison function has been specified, the function performs
a linear search for a pointer equal to B<ptr>. The index of the first
matching element is returned or B<-1> if there is no match. In the case
where a comparison function has been specified, B<sk> is sorted then
sk_TYPE_find() returns the index of a matching element or B<-1> if there
is no match. Note that, in this case, the matching element returned is
not guaranteed to be the first; the comparison function will usually
compare the values pointed to rather than the pointers themselves and
the order of elements in B<sk> could change.
sk_TYPE_find_ex() operates like sk_TYPE_find() except when a comparison
function has been specified and no matching element is found. Instead
of returning B<-1>, sk_TYPE_find_ex() returns the index of the element
either before or after the location where B<ptr> would be if it were
present in B<sk>.
sk_TYPE_sort() sorts B<sk> using the supplied comparison function.
sk_TYPE_is_sorted() returns B<1> if B<sk> is sorted and B<0> otherwise.
sk_TYPE_dup() returns a copy of B<sk>. Note the pointers in the copy
are identical to the original.
sk_TYPE_deep_copy() returns a new stack where each element has been copied.
Copying is performed by the supplied copyfunc() and freeing by freefunc(). The
function freefunc() is only called if an error occurs.
=head1 NOTES
Care should be taken when accessing stacks in multi-threaded environments.
Any operation which increases the size of a stack such as sk_TYPE_insert() or
sk_push() can "grow" the size of an internal array and cause race conditions
if the same stack is accessed in a different thread. Operations such as
sk_find() and sk_sort() can also reorder the stack.
Any comparison function supplied should use a metric suitable
for use in a binary search operation. That is it should return zero, a
positive or negative value if B<a> is equal to, greater than
or less than B<b> respectively.
Care should be taken when checking the return values of the functions
sk_TYPE_find() and sk_TYPE_find_ex(). They return an index to the
matching element. In particular B<0> indicates a matching first element.
A failed search is indicated by a B<-1> return value.
STACK_OF(), DEFINE_STACK_OF(), DEFINE_STACK_OF_CONST(), and
DEFINE_SPECIAL_STACK_OF() are implemented as macros.
=head1 RETURN VALUES
sk_TYPE_num() returns the number of elements in the stack or B<-1> if the
passed stack is B<NULL>.
sk_TYPE_value() returns a pointer to a stack element or B<NULL> if the
index is out of range.
sk_TYPE_new() and sk_TYPE_new_null() return an empty stack or B<NULL> if
an error occurs.
sk_TYPE_set_cmp_func() returns the old comparison function or B<NULL> if
there was no old comparison function.
sk_TYPE_free(), sk_TYPE_zero(), sk_TYPE_pop_free() and sk_TYPE_sort() do
not return values.
sk_TYPE_pop(), sk_TYPE_shift(), sk_TYPE_delete() and sk_TYPE_delete_ptr()
return a pointer to the deleted element or B<NULL> on error.
sk_TYPE_insert(), sk_TYPE_push() and sk_TYPE_unshift() return the total
number of elements in the stack and 0 if an error occurred.
sk_TYPE_set() returns a pointer to the replacement element or B<NULL> on
error.
sk_TYPE_find() and sk_TYPE_find_ex() return an index to the found element
or B<-1> on error.
sk_TYPE_is_sorted() returns B<1> if the stack is sorted and B<0> if it is
not.
sk_TYPE_dup() and sk_TYPE_deep_copy() return a pointer to the copy of the
stack.
=head1 HISTORY
Before OpenSSL 1.1.0, this was implemented via macros and not inline functions
and was not a public API.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

137
doc/crypto/des.pod → doc/crypto/DES_random_key.pod
View File

@@ -8,9 +8,9 @@ DES_ecb_encrypt, DES_ecb2_encrypt, DES_ecb3_encrypt, DES_ncbc_encrypt,
DES_cfb_encrypt, DES_ofb_encrypt, DES_pcbc_encrypt, DES_cfb64_encrypt,
DES_ofb64_encrypt, DES_xcbc_encrypt, DES_ede2_cbc_encrypt,
DES_ede2_cfb64_encrypt, DES_ede2_ofb64_encrypt, DES_ede3_cbc_encrypt,
DES_ede3_cbcm_encrypt, DES_ede3_cfb64_encrypt, DES_ede3_ofb64_encrypt,
DES_ede3_cfb64_encrypt, DES_ede3_ofb64_encrypt,
DES_cbc_cksum, DES_quad_cksum, DES_string_to_key, DES_string_to_2keys,
DES_fcrypt, DES_crypt, DES_enc_read, DES_enc_write - DES encryption
DES_fcrypt, DES_crypt - DES encryption
=head1 SYNOPSIS
@@ -28,16 +28,16 @@ DES_fcrypt, DES_crypt, DES_enc_read, DES_enc_write - DES encryption
void DES_set_odd_parity(DES_cblock *key);
int DES_is_weak_key(const_DES_cblock *key);
void DES_ecb_encrypt(const_DES_cblock *input, DES_cblock *output,
void DES_ecb_encrypt(const_DES_cblock *input, DES_cblock *output,
DES_key_schedule *ks, int enc);
void DES_ecb2_encrypt(const_DES_cblock *input, DES_cblock *output,
void DES_ecb2_encrypt(const_DES_cblock *input, DES_cblock *output,
DES_key_schedule *ks1, DES_key_schedule *ks2, int enc);
void DES_ecb3_encrypt(const_DES_cblock *input, DES_cblock *output,
DES_key_schedule *ks1, DES_key_schedule *ks2,
void DES_ecb3_encrypt(const_DES_cblock *input, DES_cblock *output,
DES_key_schedule *ks1, DES_key_schedule *ks2,
DES_key_schedule *ks3, int enc);
void DES_ncbc_encrypt(const unsigned char *input, unsigned char *output,
long length, DES_key_schedule *schedule, DES_cblock *ivec,
void DES_ncbc_encrypt(const unsigned char *input, unsigned char *output,
long length, DES_key_schedule *schedule, DES_cblock *ivec,
int enc);
void DES_cfb_encrypt(const unsigned char *in, unsigned char *out,
int numbits, long length, DES_key_schedule *schedule,
@@ -45,8 +45,8 @@ DES_fcrypt, DES_crypt, DES_enc_read, DES_enc_write - DES encryption
void DES_ofb_encrypt(const unsigned char *in, unsigned char *out,
int numbits, long length, DES_key_schedule *schedule,
DES_cblock *ivec);
void DES_pcbc_encrypt(const unsigned char *input, unsigned char *output,
long length, DES_key_schedule *schedule, DES_cblock *ivec,
void DES_pcbc_encrypt(const unsigned char *input, unsigned char *output,
long length, DES_key_schedule *schedule, DES_cblock *ivec,
int enc);
void DES_cfb64_encrypt(const unsigned char *in, unsigned char *out,
long length, DES_key_schedule *schedule, DES_cblock *ivec,
@@ -55,8 +55,8 @@ DES_fcrypt, DES_crypt, DES_enc_read, DES_enc_write - DES encryption
long length, DES_key_schedule *schedule, DES_cblock *ivec,
int *num);
void DES_xcbc_encrypt(const unsigned char *input, unsigned char *output,
long length, DES_key_schedule *schedule, DES_cblock *ivec,
void DES_xcbc_encrypt(const unsigned char *input, unsigned char *output,
long length, DES_key_schedule *schedule, DES_cblock *ivec,
const_DES_cblock *inw, const_DES_cblock *outw, int enc);
void DES_ede2_cbc_encrypt(const unsigned char *input,
@@ -73,22 +73,18 @@ DES_fcrypt, DES_crypt, DES_enc_read, DES_enc_write - DES encryption
unsigned char *output, long length, DES_key_schedule *ks1,
DES_key_schedule *ks2, DES_key_schedule *ks3, DES_cblock *ivec,
int enc);
void DES_ede3_cbcm_encrypt(const unsigned char *in, unsigned char *out,
long length, DES_key_schedule *ks1, DES_key_schedule *ks2,
DES_key_schedule *ks3, DES_cblock *ivec1, DES_cblock *ivec2,
int enc);
void DES_ede3_cfb64_encrypt(const unsigned char *in, unsigned char *out,
void DES_ede3_cfb64_encrypt(const unsigned char *in, unsigned char *out,
long length, DES_key_schedule *ks1, DES_key_schedule *ks2,
DES_key_schedule *ks3, DES_cblock *ivec, int *num, int enc);
void DES_ede3_ofb64_encrypt(const unsigned char *in, unsigned char *out,
long length, DES_key_schedule *ks1,
DES_key_schedule *ks2, DES_key_schedule *ks3,
void DES_ede3_ofb64_encrypt(const unsigned char *in, unsigned char *out,
long length, DES_key_schedule *ks1,
DES_key_schedule *ks2, DES_key_schedule *ks3,
DES_cblock *ivec, int *num);
DES_LONG DES_cbc_cksum(const unsigned char *input, DES_cblock *output,
long length, DES_key_schedule *schedule,
DES_LONG DES_cbc_cksum(const unsigned char *input, DES_cblock *output,
long length, DES_key_schedule *schedule,
const_DES_cblock *ivec);
DES_LONG DES_quad_cksum(const unsigned char *input, DES_cblock output[],
DES_LONG DES_quad_cksum(const unsigned char *input, DES_cblock output[],
long length, int out_count, DES_cblock *seed);
void DES_string_to_key(const char *str, DES_cblock *key);
void DES_string_to_2keys(const char *str, DES_cblock *key1,
@@ -97,11 +93,6 @@ DES_fcrypt, DES_crypt, DES_enc_read, DES_enc_write - DES encryption
char *DES_fcrypt(const char *buf, const char *salt, char *ret);
char *DES_crypt(const char *buf, const char *salt);
int DES_enc_read(int fd, void *buf, int len, DES_key_schedule *sched,
DES_cblock *iv);
int DES_enc_write(int fd, const void *buf, int len,
DES_key_schedule *sched, DES_cblock *iv);
=head1 DESCRIPTION
This library contains a fast implementation of the DES encryption
@@ -115,7 +106,7 @@ each byte is the parity bit. The key schedule is an expanded form of
the key; it is used to speed the encryption process.
DES_random_key() generates a random key. The PRNG must be seeded
prior to using this function (see L<rand(3)|rand(3)>). If the PRNG
prior to using this function (see L<rand(3)>). If the PRNG
could not generate a secure key, 0 is returned.
Before a DES key can be used, it must be converted into the
@@ -123,7 +114,7 @@ architecture dependent I<DES_key_schedule> via the
DES_set_key_checked() or DES_set_key_unchecked() function.
DES_set_key_checked() will check that the key passed is of odd parity
and is not a week or semi-weak key. If the parity is wrong, then -1
and is not a weak or semi-weak key. If the parity is wrong, then -1
is returned. If the key is a weak key, then -2 is returned. If an
error is returned, the key schedule is not generated.
@@ -136,7 +127,7 @@ depend on a global variable.
DES_set_odd_parity() sets the parity of the passed I<key> to odd.
DES_is_weak_key() returns 1 if the passed key is a weak key, 0 if it
is ok.
is ok.
The following routines mostly operate on an input and output stream of
I<DES_cblock>s.
@@ -230,7 +221,7 @@ DES_cbc_cksum() produces an 8 byte checksum based on the input stream
(via CBC encryption). The last 4 bytes of the checksum are returned
and the complete 8 bytes are placed in I<output>. This function is
used by Kerberos v4. Other applications should use
L<EVP_DigestInit(3)|EVP_DigestInit(3)> etc. instead.
L<EVP_DigestInit(3)> etc. instead.
DES_quad_cksum() is a Kerberos v4 function. It returns a 4 byte
checksum from the input bytes. The algorithm can be iterated over the
@@ -249,8 +240,9 @@ is thread safe, unlike the normal crypt.
DES_crypt() is a faster replacement for the normal system crypt().
This function calls DES_fcrypt() with a static array passed as the
third parameter. This emulates the normal non-thread safe semantics
third parameter. This mostly emulates the normal non-thread-safe semantics
of crypt(3).
The B<salt> must be two ASCII characters.
DES_enc_write() writes I<len> bytes to file descriptor I<fd> from
buffer I<buf>. The data is encrypted via I<pcbc_encrypt> (default)
@@ -260,32 +252,6 @@ containing the length of the following encrypted data. The encrypted
data then follows, padded with random data out to a multiple of 8
bytes.
DES_enc_read() is used to read I<len> bytes from file descriptor
I<fd> into buffer I<buf>. The data being read from I<fd> is assumed to
have come from DES_enc_write() and is decrypted using I<sched> for
the key schedule and I<iv> for the initial vector.
B<Warning:> The data format used by DES_enc_write() and DES_enc_read()
has a cryptographic weakness: When asked to write more than MAXWRITE
bytes, DES_enc_write() will split the data into several chunks that
are all encrypted using the same IV. So don't use these functions
unless you are sure you know what you do (in which case you might not
want to use them anyway). They cannot handle non-blocking sockets.
DES_enc_read() uses an internal state and thus cannot be used on
multiple files.
I<DES_rw_mode> is used to specify the encryption mode to use with
DES_enc_read() and DES_end_write(). If set to I<DES_PCBC_MODE> (the
default), DES_pcbc_encrypt is used. If set to I<DES_CBC_MODE>
DES_cbc_encrypt is used.
=head1 NOTES
Single-key DES is insecure due to its short key size. ECB mode is
not suitable for most applications; see L<des_modes(7)|des_modes(7)>.
The L<evp(3)|evp(3)> library provides higher-level encryption functions.
=head1 BUGS
DES_3cbc_encrypt() is flawed and must not be used in applications.
@@ -307,51 +273,38 @@ DES_string_to_key() is available for backward compatibility with the
MIT library. New applications should use a cryptographic hash function.
The same applies for DES_string_to_2key().
=head1 CONFORMING TO
ANSI X3.106
=head1 NOTES
The B<des> library was written to be source code compatible with
the MIT Kerberos library.
=head1 SEE ALSO
Applications should use the higher level functions
L<EVP_EncryptInit(3)> etc. instead of calling these
functions directly.
crypt(3), L<des_modes(7)|des_modes(7)>, L<evp(3)|evp(3)>, L<rand(3)|rand(3)>
Single-key DES is insecure due to its short key size. ECB mode is
not suitable for most applications; see L<des_modes(7)>.
=head1 HISTORY
In OpenSSL 0.9.7, all des_ functions were renamed to DES_ to avoid
clashes with older versions of libdes. Compatibility des_ functions
are provided for a short while, as well as crypt().
Declarations for these are in <openssl/des_old.h>. There is no DES_
variant for des_random_seed().
This will happen to other functions
as well if they are deemed redundant (des_random_seed() just calls
RAND_seed() and is present for backward compatibility only), buggy or
already scheduled for removal.
The requirement that the B<salt> parameter to DES_crypt() and DES_fcrypt()
be two ASCII characters was first enforced in
OpenSSL 1.1.0. Previous versions tried to use the letter uppercase B<A>
if both character were not present, and could crash when given non-ASCII
on some platforms.
des_cbc_cksum(), des_cbc_encrypt(), des_ecb_encrypt(),
des_is_weak_key(), des_key_sched(), des_pcbc_encrypt(),
des_quad_cksum(), des_random_key() and des_string_to_key()
are available in the MIT Kerberos library;
des_check_key_parity(), des_fixup_key_parity() and des_is_weak_key()
are available in newer versions of that library.
=head1 SEE ALSO
des_set_key_checked() and des_set_key_unchecked() were added in
OpenSSL 0.9.5.
L<des_modes(7)>,
L<EVP_EncryptInit(3)>
des_generate_random_block(), des_init_random_number_generator(),
des_new_random_key(), des_set_random_generator_seed() and
des_set_sequence_number() and des_rand_data() are used in newer
versions of Kerberos but are not implemented here.
=head1 COPYRIGHT
des_random_key() generated cryptographically weak random data in
SSLeay and in OpenSSL prior version 0.9.5, as well as in the original
MIT library.
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
=head1 AUTHOR
Eric Young (eay@cryptsoft.com). Modified for the OpenSSL project
(http://www.openssl.org).
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

14
doc/crypto/DH_generate_key.pod
View File

@@ -36,15 +36,19 @@ 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)>.
The error codes can be obtained by L<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)>
L<dh(3)>, L<ERR_get_error(3)>, L<rand(3)>, L<DH_size(3)>
=head1 HISTORY
=head1 COPYRIGHT
DH_generate_key() and DH_compute_key() are available in all versions
of SSLeay and OpenSSL.
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

106
doc/crypto/DH_generate_parameters.pod
View File

@@ -2,22 +2,25 @@
=head1 NAME
DH_generate_parameters_ex, DH_generate_parameters,
DH_check - generate and check Diffie-Hellman parameters
DH_check, DH_check_params - 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_generate_parameters_ex(DH *dh, int prime_len, int generator, BN_GENCB *cb);
int DH_check(DH *dh, int *codes);
int DH_check_params(DH *dh, int *codes);
Deprecated:
#if OPENSSL_API_COMPAT < 0x00908000L
DH *DH_generate_parameters(int prime_len, int generator,
void (*callback)(int, int, void *), void *cb_arg);
#endif
=head1 DESCRIPTION
@@ -27,31 +30,84 @@ 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.
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
called as described in L<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
is called. See L<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.
DH_check_params() confirms that the B<p> and B<g> are likely enough to
be valid.
This is a lightweight check, if a more thorough check is needed, use
DH_check().
The value of B<*codes> is updated with any problems found.
If B<*codes> is zero then no problems were found, otherwise the
following bits may be set:
=over 4
=item DH_CHECK_P_NOT_PRIME
The parameter B<p> has been determined to not being an odd prime.
Note that the lack of this bit doesn't guarantee that B<p> is a
prime.
=item DH_NOT_SUITABLE_GENERATOR
The generator B<g> is not suitable.
Note that the lack of this bit doesn't guarantee that B<g> is
suitable, unless B<p> is known to be a strong prime.
=back
DH_check() confirms that the Diffie-Hellman parameters B<dh> are valid. The
value of B<*codes> is updated with any problems found. If B<*codes> is zero then
no problems were found, otherwise the following bits may be set:
=over 4
=item DH_CHECK_P_NOT_PRIME
The parameter B<p> is not prime.
=item DH_CHECK_P_NOT_SAFE_PRIME
The parameter B<p> is not a safe prime and no B<q> value is present.
=item DH_UNABLE_TO_CHECK_GENERATOR
The generator B<g> cannot be checked for suitability.
=item DH_NOT_SUITABLE_GENERATOR
The generator B<g> is not suitable.
=item DH_CHECK_Q_NOT_PRIME
The parameter B<q> is not prime.
=item DH_CHECK_INVALID_Q_VALUE
The parameter B<q> is invalid.
=item DH_CHECK_INVALID_J_VALUE
The parameter B<j> is invalid.
=back
=head1 RETURN VALUES
DH_generate_parameters_ex() and DH_check() return 1 if the check could be
performed, 0 otherwise.
DH_generate_parameters_ex(), DH_check() and DH_check_params() 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)>.
The error codes can be obtained by L<ERR_get_error(3)>.
=head1 NOTES
@@ -61,22 +117,18 @@ 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)>
L<DH_new(3)>, L<ERR_get_error(3)>, L<RAND_bytes(3)>,
L<DH_free(3)>
=head1 HISTORY
=head1 COPYRIGHT
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.
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
In versions before OpenSSL 0.9.5, DH_CHECK_P_NOT_STRONG_PRIME is used
instead of DH_CHECK_P_NOT_SAFE_PRIME.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

112
doc/crypto/DH_get0_pqg.pod Normal file
View File

@@ -0,0 +1,112 @@
=pod
=head1 NAME
DH_get0_pqg, DH_set0_pqg, DH_get0_key, DH_set0_key, DH_clear_flags,
DH_test_flags, DH_set_flags, DH_get0_engine, DH_get_length,
DH_set_length - Routines for getting and setting data in a DH object
=head1 SYNOPSIS
#include <openssl/dh.h>
void DH_get0_pqg(const DH *dh,
const BIGNUM **p, const BIGNUM **q, const BIGNUM **g);
int DH_set0_pqg(DH *dh, BIGNUM *p, BIGNUM *q, BIGNUM *g);
void DH_get0_key(const DH *dh,
const BIGNUM **pub_key, const BIGNUM **priv_key);
int DH_set0_key(DH *dh, BIGNUM *pub_key, BIGNUM *priv_key);
void DH_clear_flags(DH *dh, int flags);
int DH_test_flags(const DH *dh, int flags);
void DH_set_flags(DH *dh, int flags);
ENGINE *DH_get0_engine(DH *d);
long DH_get_length(const DH *dh);
int DH_set_length(DH *dh, long length);
=head1 DESCRIPTION
A DH object contains the parameters B<p>, B<q> and B<g>. Note that the B<q>
parameter is optional. It also contains a public key (B<pub_key>) and
(optionally) a private key (B<priv_key>).
The B<p>, B<q> and B<g> parameters can be obtained by calling DH_get0_pqg().
If the parameters have not yet been set then B<*p>, B<*q> and B<*g> will be set
to NULL. Otherwise they are set to pointers to their respective values. These
point directly to the internal representations of the values and therefore
should not be freed directly.
The B<p>, B<q> and B<g> values can be set by calling DH_set0_pqg() and passing
the new values for B<p>, B<q> and B<g> as parameters to the function. Calling
this function transfers the memory management of the values to the DH object,
and therefore the values that have been passed in should not be freed directly
after this function has been called. The B<q> parameter may be NULL.
To get the public and private key values use the DH_get0_key() function. A
pointer to the public key will be stored in B<*pub_key>, and a pointer to the
private key will be stored in B<*priv_key>. Either may be NULL if they have not
been set yet, although if the private key has been set then the public key must
be. The values point to the internal representation of the public key and
private key values. This memory should not be freed directly.
The public and private key values can be set using DH_set0_key(). The public
key must be non-NULL the first time this function is called on a given DH
object. The private key may be NULL. On subsequent calls, either may be NULL,
which means the corresponding DH field is left untouched. As for DH_set0_pqg()
this function transfers the memory management of the key values to the DH
object, and therefore they should not be freed directly after this function has
been called.
DH_set_flags() sets the flags in the B<flags> parameter on the DH object.
Multiple flags can be passed in one go (bitwise ORed together). Any flags that
are already set are left set. DH_test_flags() tests to see whether the flags
passed in the B<flags> parameter are currently set in the DH object. Multiple
flags can be tested in one go. All flags that are currently set are returned, or
zero if none of the flags are set. DH_clear_flags() clears the specified flags
within the DH object.
DH_get0_engine() returns a handle to the ENGINE that has been set for this DH
object, or NULL if no such ENGINE has been set.
The DH_get_length() and DH_set_length() functions get and set the optional
length parameter associated with this DH object. If the length is non-zero then
it is used, otherwise it is ignored. The B<length> parameter indicates the
length of the secret exponent (private key) in bits.
=head1 NOTES
Values retrieved with DH_get0_key() are owned by the DH object used
in the call and may therefore I<not> be passed to DH_set0_key(). If
needed, duplicate the received value using BN_dup() and pass the
duplicate. The same applies to DH_get0_pqg() and DH_set0_pqg().
=head1 RETURN VALUES
DH_set0_pqg() and DH_set0_key() return 1 on success or 0 on failure.
DH_test_flags() returns the current state of the flags in the DH object.
DH_get0_engine() returns the ENGINE set for the DH object or NULL if no ENGINE
has been set.
DH_get_length() returns the length of the secret exponent (private key) in bits,
or zero if no such length has been explicitly set.
=head1 SEE ALSO
L<dh(3)>, L<DH_new(3)>, L<DH_generate_parameters(3)>, L<DH_generate_key(3)>,
L<DH_set_method(3)>, L<DH_size(3)>, L<DH_meth_new(3)>
=head1 HISTORY
The functions described here were added in OpenSSL version 1.1.0.
=head1 COPYRIGHT
Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

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

@@ -0,0 +1,74 @@
=pod
=head1 NAME
DH_get_1024_160,
DH_get_2048_224,
DH_get_2048_256,
BN_get0_nist_prime_192,
BN_get0_nist_prime_224,
BN_get0_nist_prime_256,
BN_get0_nist_prime_384,
BN_get0_nist_prime_521,
BN_get_rfc2409_prime_768,
BN_get_rfc2409_prime_1024,
BN_get_rfc3526_prime_1536,
BN_get_rfc3526_prime_2048,
BN_get_rfc3526_prime_3072,
BN_get_rfc3526_prime_4096,
BN_get_rfc3526_prime_6144,
BN_get_rfc3526_prime_8192
- Create standardized public primes or DH pairs
=head1 SYNOPSIS
#include <openssl/dh.h>
DH *DH_get_1024_160(void)
DH *DH_get_2048_224(void)
DH *DH_get_2048_256(void)
const BIGNUM *BN_get0_nist_prime_192(void)
const BIGNUM *BN_get0_nist_prime_224(void)
const BIGNUM *BN_get0_nist_prime_256(void)
const BIGNUM *BN_get0_nist_prime_384(void)
const BIGNUM *BN_get0_nist_prime_521(void)
BIGNUM *BN_get_rfc2409_prime_768(BIGNUM *bn)
BIGNUM *BN_get_rfc2409_prime_1024(BIGNUM *bn)
BIGNUM *BN_get_rfc3526_prime_1536(BIGNUM *bn)
BIGNUM *BN_get_rfc3526_prime_2048(BIGNUM *bn)
BIGNUM *BN_get_rfc3526_prime_3072(BIGNUM *bn)
BIGNUM *BN_get_rfc3526_prime_4096(BIGNUM *bn)
BIGNUM *BN_get_rfc3526_prime_6144(BIGNUM *bn)
BIGNUM *BN_get_rfc3526_prime_8192(BIGNUM *bn)
=head1 DESCRIPTION
DH_get_1024_160(), DH_get_2048_224(), and DH_get_2048_256() each return
a DH object for the IETF RFC 5114 value.
BN_get0_nist_prime_192(), BN_get0_nist_prime_224(), BN_get0_nist_prime_256(),
BN_get0_nist_prime_384(), and BN_get0_nist_prime_521() functions return
a BIGNUM for the specific NIST prime curve (e.g., P-256).
BN_get_rfc2409_prime_768(), BN_get_rfc2409_prime_1024(),
BN_get_rfc3526_prime_1536(), BN_get_rfc3526_prime_2048(),
BN_get_rfc3526_prime_3072(), BN_get_rfc3526_prime_4096(),
BN_get_rfc3526_prime_6144(), and BN_get_rfc3526_prime_8192() functions
return a BIGNUM for the specified size from IETF RFC 2409. If B<bn>
is not NULL, the BIGNUM will be set into that location as well.
=head1 RETURN VALUES
Defined above.
=head1 COPYRIGHT
Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

36
doc/crypto/DH_get_ex_new_index.pod
View File

@@ -1,36 +0,0 @@
=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

156
doc/crypto/DH_meth_new.pod Normal file
View File

@@ -0,0 +1,156 @@
=pod
=head1 NAME
DH_meth_new, DH_meth_free, DH_meth_dup, DH_meth_get0_name, DH_meth_set1_name,
DH_meth_get_flags, DH_meth_set_flags, DH_meth_get0_app_data,
DH_meth_set0_app_data, DH_meth_get_generate_key, DH_meth_set_generate_key,
DH_meth_get_compute_key, DH_meth_set_compute_key, DH_meth_get_bn_mod_exp,
DH_meth_set_bn_mod_exp, DH_meth_get_init, DH_meth_set_init, DH_meth_get_finish,
DH_meth_set_finish, DH_meth_get_generate_params,
DH_meth_set_generate_params - Routines to build up DH methods
=head1 SYNOPSIS
#include <openssl/dh.h>
DH_METHOD *DH_meth_new(const char *name, int flags);
void DH_meth_free(DH_METHOD *dhm);
DH_METHOD *DH_meth_dup(const DH_METHOD *dhm);
const char *DH_meth_get0_name(const DH_METHOD *dhm);
int DH_meth_set1_name(DH_METHOD *dhm, const char *name);
int DH_meth_get_flags(DH_METHOD *dhm);
int DH_meth_set_flags(DH_METHOD *dhm, int flags);
void *DH_meth_get0_app_data(const DH_METHOD *dhm);
int DH_meth_set0_app_data(DH_METHOD *dhm, void *app_data);
int (*DH_meth_get_generate_key(const DH_METHOD *dhm)) (DH *);
int DH_meth_set_generate_key(DH_METHOD *dhm, int (*generate_key) (DH *));
int (*DH_meth_get_compute_key(const DH_METHOD *dhm))
(unsigned char *key, const BIGNUM *pub_key, DH *dh);
int DH_meth_set_compute_key(DH_METHOD *dhm,
int (*compute_key) (unsigned char *key, const BIGNUM *pub_key, DH *dh));
int (*DH_meth_get_bn_mod_exp(const DH_METHOD *dhm))
(const DH *dh, BIGNUM *r, const BIGNUM *a, const BIGNUM *p,
const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx);
int DH_meth_set_bn_mod_exp(DH_METHOD *dhm,
int (*bn_mod_exp) (const DH *dh, BIGNUM *r, const BIGNUM *a,
const BIGNUM *p, const BIGNUM *m, BN_CTX *ctx,
BN_MONT_CTX *m_ctx));
int (*DH_meth_get_init(const DH_METHOD *dhm))(DH *);
int DH_meth_set_init(DH_METHOD *dhm, int (*init)(DH *));
int (*DH_meth_get_finish(const DH_METHOD *dhm)) (DH *);
int DH_meth_set_finish(DH_METHOD *dhm, int (*finish) (DH *));
int (*DH_meth_get_generate_params(const DH_METHOD *dhm))
(DH *, int, int, BN_GENCB *);
int DH_meth_set_generate_params(DH_METHOD *dhm,
int (*generate_params) (DH *, int, int, BN_GENCB *));
=head1 DESCRIPTION
The B<DH_METHOD> type is a structure used for the provision of custom DH
implementations. It provides a set of of functions used by OpenSSL for the
implementation of the various DH capabilities.
DH_meth_new() creates a new B<DH_METHOD> structure. It should be given a
unique B<name> and a set of B<flags>. The B<name> should be a NULL terminated
string, which will be duplicated and stored in the B<DH_METHOD> object. It is
the callers responsibility to free the original string. The flags will be used
during the construction of a new B<DH> object based on this B<DH_METHOD>. Any
new B<DH> object will have those flags set by default.
DH_meth_dup() creates a duplicate copy of the B<DH_METHOD> object passed as a
parameter. This might be useful for creating a new B<DH_METHOD> based on an
existing one, but with some differences.
DH_meth_free() destroys a B<DH_METHOD> structure and frees up any memory
associated with it.
DH_meth_get0_name() will return a pointer to the name of this DH_METHOD. This
is a pointer to the internal name string and so should not be freed by the
caller. DH_meth_set1_name() sets the name of the DH_METHOD to B<name>. The
string is duplicated and the copy is stored in the DH_METHOD structure, so the
caller remains responsible for freeing the memory associated with the name.
DH_meth_get_flags() returns the current value of the flags associated with this
DH_METHOD. DH_meth_set_flags() provides the ability to set these flags.
The functions DH_meth_get0_app_data() and DH_meth_set0_app_data() provide the
ability to associate implementation specific data with the DH_METHOD. It is
the application's responsibility to free this data before the DH_METHOD is
freed via a call to DH_meth_free().
DH_meth_get_generate_key() and DH_meth_set_generate_key() get and set the
function used for generating a new DH key pair respectively. This function will
be called in response to the application calling DH_generate_key(). The
parameter for the function has the same meaning as for DH_generate_key().
DH_meth_get_compute_key() and DH_meth_set_compute_key() get and set the
function used for computing a new DH shared secret respectively. This function
will be called in response to the application calling DH_compute_key(). The
parameters for the function have the same meaning as for DH_compute_key().
DH_meth_get_bn_mod_exp() and DH_meth_set_bn_mod_exp() get and set the function
used for computing the following value:
r = a ^ p mod m
This function will be called by the default OpenSSL function for
DH_generate_key(). The result is stored in the B<r> parameter. This function
may be NULL unless using the default generate key function, in which case it
must be present.
DH_meth_get_init() and DH_meth_set_init() get and set the function used
for creating a new DH instance respectively. This function will be
called in response to the application calling DH_new() (if the current default
DH_METHOD is this one) or DH_new_method(). The DH_new() and DH_new_method()
functions will allocate the memory for the new DH object, and a pointer to this
newly allocated structure will be passed as a parameter to the function. This
function may be NULL.
DH_meth_get_finish() and DH_meth_set_finish() get and set the function used
for destroying an instance of a DH object respectively. This function will be
called in response to the application calling DH_free(). A pointer to the DH
to be destroyed is passed as a parameter. The destroy function should be used
for DH implementation specific clean up. The memory for the DH itself should
not be freed by this function. This function may be NULL.
DH_meth_get_generate_params() and DH_meth_set_generate_params() get and set the
function used for generating DH parameters respectively. This function will be
called in response to the application calling DH_generate_parameters_ex() (or
DH_generate_parameters()). The parameters for the function have the same
meaning as for DH_generate_parameters_ex(). This function may be NULL.
=head1 RETURN VALUES
DH_meth_new() and DH_meth_dup() return the newly allocated DH_METHOD object
or NULL on failure.
DH_meth_get0_name() and DH_meth_get_flags() return the name and flags
associated with the DH_METHOD respectively.
All other DH_meth_get_*() functions return the appropriate function pointer
that has been set in the DH_METHOD, or NULL if no such pointer has yet been
set.
DH_meth_set1_name() and all DH_meth_set_*() functions return 1 on success or
0 on failure.
=head1 SEE ALSO
L<dh(3)>, L<DH_new(3)>, L<DH_generate_parameters(3)>, L<DH_generate_key(3)>,
L<DH_set_method(3)>, L<DH_size(3)>, L<DH_get0_pqg(3)>
=head1 HISTORY
The functions described here were added in OpenSSL version 1.1.0.
=head1 COPYRIGHT
Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

18
doc/crypto/DH_new.pod
View File

@@ -18,23 +18,29 @@ 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.
If B<dh> is NULL nothing is done.
=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
code that can be obtained by L<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)>
L<dh(3)>, L<ERR_get_error(3)>,
L<DH_generate_parameters(3)>,
L<DH_generate_key(3)>
=head1 HISTORY
=head1 COPYRIGHT
DH_new() and DH_free() are available in all versions of SSLeay and OpenSSL.
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

64
doc/crypto/DH_set_method.pod
View File

@@ -8,7 +8,6 @@ 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);
@@ -52,35 +51,8 @@ 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;
A new DH_METHOD object may be constructed using DH_meth_new() (see
L<DH_meth_new(3)>).
=head1 RETURN VALUES
@@ -94,36 +66,20 @@ 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
L<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)>
L<dh(3)>, L<DH_new(3)>, L<DH_meth_new(3)>
=head1 HISTORY
=head1 COPYRIGHT
DH_set_default_method(), DH_get_default_method(), DH_set_method(),
DH_new_method() and DH_OpenSSL() were added in OpenSSL 0.9.4.
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
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.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

30
doc/crypto/DH_size.pod
View File

@@ -2,32 +2,46 @@
=head1 NAME
DH_size - get Diffie-Hellman prime size
DH_size, DH_bits - get Diffie-Hellman prime size
=head1 SYNOPSIS
#include <openssl/dh.h>
#include <openssl/dh.h>
int DH_size(DH *dh);
int DH_size(const DH *dh);
int DH_bits(const DH *dh);
=head1 DESCRIPTION
This function returns the Diffie-Hellman size in bytes. It can be used
DH_size() returns the Diffie-Hellman prime 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>.
DH_bits() returns the number of significant bits.
B<dh> and B<dh-E<gt>p> must not be B<NULL>.
=head1 RETURN VALUE
The size in bytes.
The size.
=head1 SEE ALSO
L<dh(3)|dh(3)>, L<DH_generate_key(3)|DH_generate_key(3)>
L<dh(3)>, L<DH_generate_key(3)>,
L<BN_num_bits(3)>
=head1 HISTORY
DH_size() is available in all versions of SSLeay and OpenSSL.
DH_bits() was added in OpenSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

34
doc/crypto/DSA_SIG_new.pod
View File

@@ -2,6 +2,7 @@
=head1 NAME
DSA_SIG_get0, DSA_SIG_set0,
DSA_SIG_new, DSA_SIG_free - allocate and free DSA signature objects
=head1 SYNOPSIS
@@ -9,32 +10,49 @@ DSA_SIG_new, DSA_SIG_free - allocate and free DSA signature objects
#include <openssl/dsa.h>
DSA_SIG *DSA_SIG_new(void);
void DSA_SIG_free(DSA_SIG *a);
void DSA_SIG_free(DSA_SIG *a);
void DSA_SIG_get0(const DSA_SIG *sig, const BIGNUM **pr, const BIGNUM **ps);
int DSA_SIG_set0(DSA_SIG *sig, BIGNUM *r, BIGNUM *s);
=head1 DESCRIPTION
DSA_SIG_new() allocates and initializes a B<DSA_SIG> structure.
DSA_SIG_new() allocates an empty 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.
DSA_SIG_get0() returns internal pointers to the B<r> and B<s> values contained
in B<sig>.
The B<r> and B<s> values can be set by calling DSA_SIG_set0() and passing the
new values for B<r> and B<s> as parameters to the function. Calling this
function transfers the memory management of the values to the DSA_SIG object,
and therefore the values that have been passed in should not be freed directly
after this function has been called.
=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
L<ERR_get_error(3)>. Otherwise it returns a pointer
to the newly allocated structure.
DSA_SIG_free() returns no value.
DSA_SIG_set0() returns 1 on success or 0 on failure.
=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)>
L<dsa(3)>, L<ERR_get_error(3)>,
L<DSA_do_sign(3)>
=head1 HISTORY
=head1 COPYRIGHT
DSA_SIG_new() and DSA_SIG_free() were added in OpenSSL 0.9.3.
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

21
doc/crypto/DSA_do_sign.pod
View File

@@ -11,7 +11,7 @@ DSA_do_sign, DSA_do_verify - raw DSA signature operations
DSA_SIG *DSA_do_sign(const unsigned char *dgst, int dlen, DSA *dsa);
int DSA_do_verify(const unsigned char *dgst, int dgst_len,
DSA_SIG *sig, DSA *dsa);
DSA_SIG *sig, DSA *dsa);
=head1 DESCRIPTION
@@ -19,7 +19,7 @@ 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
L<DSA_sign_setup(3)> may be used to precompute part
of the signing operation in case signature generation is
time-critical.
@@ -32,16 +32,21 @@ key.
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)>.
L<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)>
L<dsa(3)>, L<ERR_get_error(3)>, L<rand(3)>,
L<DSA_SIG_new(3)>,
L<DSA_sign(3)>
=head1 HISTORY
=head1 COPYRIGHT
DSA_do_sign() and DSA_do_verify() were added in OpenSSL 0.9.3.
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

13
doc/crypto/DSA_dup_DH.pod
View File

@@ -19,7 +19,7 @@ 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)>.
error codes can be obtained by L<ERR_get_error(3)>.
=head1 NOTE
@@ -27,10 +27,15 @@ 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)>
L<dh(3)>, L<dsa(3)>, L<ERR_get_error(3)>
=head1 HISTORY
=head1 COPYRIGHT
DSA_dup_DH() was added in OpenSSL 0.9.4.
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

15
doc/crypto/DSA_generate_key.pod
View File

@@ -20,15 +20,20 @@ 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)>.
The error codes can be obtained by L<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)>
L<dsa(3)>, L<ERR_get_error(3)>, L<rand(3)>,
L<DSA_generate_parameters(3)>
=head1 HISTORY
=head1 COPYRIGHT
DSA_generate_key() is available since SSLeay 0.8.
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

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