Hakase/openssl-custom
1
0 Fork 0
Code Issues Pull Requests Releases Wiki Activity

Latest update.

Browse Source
This commit is contained in:
Hakase
2019-10-17 23:54:38 +09:00
parent 41a23ae6f6
commit ee84d0dd84
1357 changed files with 41111 additions and 9603 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/man3/ASN1_INTEGER_get_int64.pod
+14 -14
View File
@@ -37,7 +37,7 @@ 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
If successful it returns 1 and sets I<*pr> to the value of I<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.
@@ -45,26 +45,26 @@ 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
ASN1_INTEGER_get() also returns the value of I<a> but it returns 0 if I<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_int64() sets the value of B<ASN1_INTEGER> I<a> to the
B<int64_t> value I<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_uint64() sets the value of B<ASN1_INTEGER> I<a> to the
B<uint64_t> value I<r>.
ASN1_INTEGER_set() sets the value of B<ASN1_INTEGER> B<a> to the B<long> value
B<v>.
ASN1_INTEGER_set() sets the value of B<ASN1_INTEGER> I<a> to the I<long> value
I<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
BN_to_ASN1_INTEGER() converts B<BIGNUM> I<bn> to an B<ASN1_INTEGER>. If I<ai>
is NULL a new B<ASN1_INTEGER> structure is returned. If I<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
ASN1_INTEGER_to_BN() converts ASN1_INTEGER I<ai> into a B<BIGNUM>. If I<bn> is
NULL a new B<BIGNUM> structure is returned. If I<bn> is not NULL then the
existing structure will be used instead.
ASN1_ENUMERATED_get_int64(), ASN1_ENUMERATED_set_int64(),
@@ -72,8 +72,8 @@ 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
ASN1_ENUMERATED_get() returns the value of I<a> in a similar way to
ASN1_INTEGER_get() but it returns B<0xffffffffL> if the value of I<a> will not
fit in a long type. New applications should use ASN1_ENUMERATED_get_int64()
instead.
doc/man3/ASN1_ITEM_lookup.pod
+4 -4
View File
@@ -13,15 +13,15 @@ ASN1_ITEM_lookup, ASN1_ITEM_get - lookup ASN.1 structures
=head1 DESCRIPTION
ASN1_ITEM_lookup() returns the B<ASN1_ITEM name>.
ASN1_ITEM_lookup() returns the B<ASN1_ITEM> named I<name>.
ASN1_ITEM_get() returns the B<ASN1_ITEM> with index B<i>. This function
returns B<NULL> if the index B<i> is out of range.
ASN1_ITEM_get() returns the B<ASN1_ITEM> with index I<i>. This function
returns NULL if the index I<i> is out of range.
=head1 RETURN VALUES
ASN1_ITEM_lookup() and ASN1_ITEM_get() return a valid B<ASN1_ITEM> structure
or B<NULL> if an error occurred.
or NULL if an error occurred.
=head1 SEE ALSO
doc/man3/ASN1_OBJECT_new.pod
+7 -7
View File
@@ -13,23 +13,23 @@ ASN1_OBJECT_new, ASN1_OBJECT_free - object allocation functions
=head1 DESCRIPTION
The ASN1_OBJECT allocation routines, allocate and free an
ASN1_OBJECT structure, which represents an ASN1 OBJECT IDENTIFIER.
The B<ASN1_OBJECT> allocation routines, allocate and free an
B<ASN1_OBJECT> structure, which represents an ASN1 OBJECT IDENTIFIER.
ASN1_OBJECT_new() allocates and initializes an ASN1_OBJECT structure.
ASN1_OBJECT_new() allocates and initializes an B<ASN1_OBJECT> structure.
ASN1_OBJECT_free() frees up the B<ASN1_OBJECT> structure B<a>.
If B<a> is NULL, nothing is done.
ASN1_OBJECT_free() frees up the B<ASN1_OBJECT> structure I<a>.
If I<a> is NULL, nothing is done.
=head1 NOTES
Although ASN1_OBJECT_new() allocates a new ASN1_OBJECT structure it
Although ASN1_OBJECT_new() allocates a new B<ASN1_OBJECT> structure it
is almost never used in applications. The ASN1 object utility functions
such as OBJ_nid2obj() are used instead.
=head1 RETURN VALUES
If the allocation fails, ASN1_OBJECT_new() returns B<NULL> and sets an error
If the allocation fails, ASN1_OBJECT_new() returns NULL and sets an error
code that can be obtained by L<ERR_get_error(3)>.
Otherwise it returns a pointer to the newly allocated structure.
doc/man3/ASN1_STRING_TABLE_add.pod
+5 -5
View File
@@ -26,16 +26,16 @@ B<ASN1_STRING_TABLE> is a table which holds string information
=head2 Functions
ASN1_STRING_TABLE_add() adds a new B<ASN1_STRING_TABLE> item into the
local ASN1 string table based on the B<nid> along with other parameters.
local ASN1 string table based on the I<nid> along with other parameters.
If the item is already in the table, fields of B<ASN1_STRING_TABLE> are
updated (depending on the values of those parameters, e.g., B<minsize>
and B<maxsize> >= 0, B<mask> and B<flags> != 0). If the B<nid> is standard,
updated (depending on the values of those parameters, e.g., I<minsize>
and I<maxsize> >= 0, I<mask> and I<flags> != 0). If the I<nid> is standard,
a copy of the standard B<ASN1_STRING_TABLE> is created and updated with
other parameters.
ASN1_STRING_TABLE_get() searches for an B<ASN1_STRING_TABLE> item based
on B<nid>. It will search the local table first, then the standard one.
on I<nid>. It will search the local table first, then the standard one.
ASN1_STRING_TABLE_cleanup() frees all B<ASN1_STRING_TABLE> items added
by ASN1_STRING_TABLE_add().
@@ -45,7 +45,7 @@ by ASN1_STRING_TABLE_add().
ASN1_STRING_TABLE_add() returns 1 on success, 0 if an error occurred.
ASN1_STRING_TABLE_get() returns a valid B<ASN1_STRING_TABLE> structure
or B<NULL> if nothing is found.
or NULL if nothing is found.
ASN1_STRING_TABLE_cleanup() does not return a value.
doc/man3/ASN1_STRING_length.pod
+16 -16
View File
@@ -28,9 +28,9 @@ ASN1_STRING_to_UTF8 - ASN1_STRING utility functions
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_length() returns the length of the content of I<x>.
ASN1_STRING_get0_data() returns an internal pointer to the data of B<x>.
ASN1_STRING_get0_data() returns an internal pointer to the data of I<x>.
Since this is an internal pointer it should B<not> be freed or
modified in any way.
@@ -38,21 +38,21 @@ 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_dup() returns a copy of the structure I<a>.
ASN1_STRING_cmp() compares B<a> and B<b> returning 0 if the two
ASN1_STRING_cmp() compares I<a> and I<b> returning 0 if the two
are identical. The string types and content are compared.
ASN1_STRING_set() sets the data of string B<str> to the buffer
B<data> or length B<len>. The supplied data is copied. If B<len>
ASN1_STRING_set() sets the data of string I<str> to the buffer
I<data> or length I<len>. The supplied data is copied. If I<len>
is -1 then the length is determined by strlen(data).
ASN1_STRING_type() returns the type of B<x>, using standard constants
ASN1_STRING_type() returns the type of I<x>, using standard constants
such as B<V_ASN1_OCTET_STRING>.
ASN1_STRING_to_UTF8() converts the string B<in> to UTF8 format, the
converted data is allocated in a buffer in B<*out>. The length of
B<out> is returned or a negative error code. The buffer B<*out>
ASN1_STRING_to_UTF8() converts the string I<in> to UTF8 format, the
converted data is allocated in a buffer in I<*out>. The length of
I<out> is returned or a negative error code. The buffer I<*out>
should be freed using OPENSSL_free().
=head1 NOTES
@@ -79,22 +79,22 @@ when calling ASN1_STRING_set().
=head1 RETURN VALUES
ASN1_STRING_length() returns the length of the content of B<x>.
ASN1_STRING_length() returns the length of the content of I<x>.
ASN1_STRING_get0_data() and ASN1_STRING_data() return an internal pointer to
the data of B<x>.
the data of I<x>.
ASN1_STRING_dup() returns a valid B<ASN1_STRING> structure or B<NULL> if an
ASN1_STRING_dup() returns a valid B<ASN1_STRING> structure or NULL if an
error occurred.
ASN1_STRING_cmp() returns an integer greater than, equal to, or less than 0,
according to whether B<a> is greater than, equal to, or less than B<b>.
according to whether I<a> is greater than, equal to, or less than I<b>.
ASN1_STRING_set() returns 1 on success or 0 on error.
ASN1_STRING_type() returns the type of B<x>.
ASN1_STRING_type() returns the type of I<x>.
ASN1_STRING_to_UTF8() returns the number of bytes in output string B<out> or a
ASN1_STRING_to_UTF8() returns the number of bytes in output string I<out> or a
negative value if an error occurred.
=head1 SEE ALSO
doc/man3/ASN1_STRING_new.pod
+4 -4
View File
@@ -19,10 +19,10 @@ ASN1_STRING_new() returns an allocated B<ASN1_STRING> structure. Its type
is undefined.
ASN1_STRING_type_new() returns an allocated B<ASN1_STRING> structure of
type B<type>.
type I<type>.
ASN1_STRING_free() frees up B<a>.
If B<a> is NULL nothing is done.
ASN1_STRING_free() frees up I<a>.
If I<a> is NULL nothing is done.
=head1 NOTES
@@ -32,7 +32,7 @@ ASN1_OCTET_STRING_new() calls ASN1_STRING_type(V_ASN1_OCTET_STRING).
=head1 RETURN VALUES
ASN1_STRING_new() and ASN1_STRING_type_new() return a valid
ASN1_STRING structure or B<NULL> if an error occurred.
B<ASN1_STRING> structure or NULL if an error occurred.
ASN1_STRING_free() does not return a value.
doc/man3/ASN1_STRING_print_ex.pod
+7 -7
View File
@@ -20,15 +20,15 @@ ASN1_tag2str, ASN1_STRING_print_ex, ASN1_STRING_print_ex_fp, ASN1_STRING_print
These functions output an B<ASN1_STRING> structure. B<ASN1_STRING> is used to
represent all the ASN1 string types.
ASN1_STRING_print_ex() outputs B<str> to B<out>, the format is determined by
the options B<flags>. ASN1_STRING_print_ex_fp() is identical except it outputs
to B<fp> instead.
ASN1_STRING_print_ex() outputs I<str> to I<out>, the format is determined by
the options I<flags>. ASN1_STRING_print_ex_fp() is identical except it outputs
to I<fp> instead.
ASN1_STRING_print() prints B<str> to B<out> but using a different format to
ASN1_STRING_print() prints I<str> to I<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>.
ASN1_tag2str() returns a human-readable name of the specified ASN.1 I<tag>.
=head1 NOTES
@@ -38,7 +38,7 @@ ASN1_STRING_print_ex() instead.
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.
The complete set of supported options for I<flags> is listed below.
Various characters can be escaped. If B<ASN1_STRFLGS_ESC_2253> is set the characters
determined by RFC2253 are escaped. If B<ASN1_STRFLGS_ESC_CTRL> is set control
@@ -96,7 +96,7 @@ characters written or -1 if an error occurred.
ASN1_STRING_print() returns 1 on success or 0 on error.
ASN1_tag2str() returns a human-readable name of the specified ASN.1 B<tag>.
ASN1_tag2str() returns a human-readable name of the specified ASN.1 I<tag>.
=head1 SEE ALSO
doc/man3/ASN1_TIME_set.pod
+73 -69
View File
@@ -61,113 +61,115 @@ ASN1_TIME_to_generalizedtime - ASN.1 Time functions
=head1 DESCRIPTION
The ASN1_TIME_set(), ASN1_UTCTIME_set() and ASN1_GENERALIZEDTIME_set()
functions set the structure B<s> to the time represented by the time_t
value B<t>. If B<s> is NULL a new time structure is allocated and returned.
functions set the structure I<s> to the time represented by the time_t
value I<t>. If I<s> is NULL a new time structure is allocated and returned.
The ASN1_TIME_adj(), ASN1_UTCTIME_adj() and ASN1_GENERALIZEDTIME_adj()
functions set the time structure B<s> to the time represented
by the time B<offset_day> and B<offset_sec> after the time_t value B<t>.
The values of B<offset_day> or B<offset_sec> can be negative to set a
time before B<t>. The B<offset_sec> value can also exceed the number of
seconds in a day. If B<s> is NULL a new structure is allocated
functions set the time structure I<s> to the time represented
by the time I<offset_day> and I<offset_sec> after the time_t value I<t>.
The values of I<offset_day> or I<offset_sec> can be negative to set a
time before I<t>. The I<offset_sec> value can also exceed the number of
seconds in a day. If I<s> is NULL a new structure is allocated
and returned.
The ASN1_TIME_set_string(), ASN1_UTCTIME_set_string() and
ASN1_GENERALIZEDTIME_set_string() functions set the time structure B<s>
to the time represented by string B<str> which must be in appropriate ASN.1
time format (for example YYMMDDHHMMSSZ or YYYYMMDDHHMMSSZ). If B<s> is NULL
this function performs a format check on B<str> only. The string B<str>
is copied into B<s>.
ASN1_GENERALIZEDTIME_set_string() functions set the time structure I<s>
to the time represented by string I<str> which must be in appropriate ASN.1
time format (for example YYMMDDHHMMSSZ or YYYYMMDDHHMMSSZ). If I<s> is NULL
this function performs a format check on I<str> only. The string I<str>
is copied into I<s>.
ASN1_TIME_set_string_X509() sets ASN1_TIME structure B<s> to the time
represented by string B<str> which must be in appropriate time format
ASN1_TIME_set_string_X509() sets B<ASN1_TIME> structure I<s> to the time
represented by string I<str> which must be in appropriate time format
that RFC 5280 requires, which means it only allows YYMMDDHHMMSSZ and
YYYYMMDDHHMMSSZ (leap second is rejected), all other ASN.1 time format
are not allowed. If B<s> is NULL this function performs a format check
on B<str> only.
are not allowed. If I<s> is NULL this function performs a format check
on I<str> only.
The ASN1_TIME_normalize() function converts an ASN1_GENERALIZEDTIME or
ASN1_UTCTIME into a time value that can be used in a certificate. It
The ASN1_TIME_normalize() function converts an B<ASN1_GENERALIZEDTIME> or
B<ASN1_UTCTIME> into a time value that can be used in a certificate. It
should be used after the ASN1_TIME_set_string() functions and before
ASN1_TIME_print() functions to get consistent (i.e. GMT) results.
The ASN1_TIME_check(), ASN1_UTCTIME_check() and ASN1_GENERALIZEDTIME_check()
functions check the syntax of the time structure B<s>.
functions check the syntax of the time structure I<s>.
The ASN1_TIME_print(), ASN1_UTCTIME_print() and ASN1_GENERALIZEDTIME_print()
functions print the time structure B<s> to BIO B<b> in human readable
functions print the time structure I<s> to BIO I<b> in human readable
format. It will be of the format MMM DD HH:MM:SS YYYY [GMT], for example
"Feb 3 00:55:52 2015 GMT" it does not include a newline. If the time
structure has invalid format it prints out "Bad time value" and returns
an error. The output for generalized time may include a fractional part
following the second.
ASN1_TIME_to_tm() converts the time B<s> to the standard B<tm> structure.
If B<s> is NULL, then the current time is converted. The output time is GMT.
The B<tm_sec>, B<tm_min>, B<tm_hour>, B<tm_mday>, B<tm_wday>, B<tm_yday>,
B<tm_mon> and B<tm_year> fields of B<tm> structure are set to proper values,
whereas all other fields are set to 0. If B<tm> is NULL this function performs
a format check on B<s> only. If B<s> is in Generalized format with fractional
ASN1_TIME_to_tm() converts the time I<s> to the standard I<tm> structure.
If I<s> is NULL, then the current time is converted. The output time is GMT.
The I<tm_sec>, I<tm_min>, I<tm_hour>, I<tm_mday>, I<tm_wday>, I<tm_yday>,
I<tm_mon> and I<tm_year> fields of I<tm> structure are set to proper values,
whereas all other fields are set to 0. If I<tm> is NULL this function performs
a format check on I<s> only. If I<s> is in Generalized format with fractional
seconds, e.g. YYYYMMDDHHMMSS.SSSZ, the fractional seconds will be lost while
converting B<s> to B<tm> structure.
converting I<s> to I<tm> structure.
ASN1_TIME_diff() sets B<*pday> and B<*psec> to the time difference between
B<from> and B<to>. If B<to> represents a time later than B<from> then
one or both (depending on the time difference) of B<*pday> and B<*psec>
will be positive. If B<to> represents a time earlier than B<from> then
one or both of B<*pday> and B<*psec> will be negative. If B<to> and B<from>
represent the same time then B<*pday> and B<*psec> will both be zero.
If both B<*pday> and B<*psec> are non-zero they will always have the same
sign. The value of B<*psec> will always be less than the number of seconds
in a day. If B<from> or B<to> is NULL the current time is used.
ASN1_TIME_diff() sets I<*pday> and I<*psec> to the time difference between
I<from> and I<to>. If I<to> represents a time later than I<from> then
one or both (depending on the time difference) of I<*pday> and I<*psec>
will be positive. If I<to> represents a time earlier than I<from> then
one or both of I<*pday> and I<*psec> will be negative. If I<to> and I<from>
represent the same time then I<*pday> and I<*psec> will both be zero.
If both I<*pday> and I<*psec> are nonzero they will always have the same
sign. The value of I<*psec> will always be less than the number of seconds
in a day. If I<from> or I<to> is NULL the current time is used.
The ASN1_TIME_cmp_time_t() and ASN1_UTCTIME_cmp_time_t() functions compare
the two times represented by the time structure B<s> and the time_t B<t>.
the two times represented by the time structure I<s> and the time_t I<t>.
The ASN1_TIME_compare() function compares the two times represented by the
time structures B<a> and B<b>.
time structures I<a> and I<b>.
The ASN1_TIME_to_generalizedtime() function converts an ASN1_TIME to an
ASN1_GENERALIZEDTIME, regardless of year. If either B<out> or
B<*out> are NULL, then a new object is allocated and must be freed after use.
The ASN1_TIME_to_generalizedtime() function converts an B<ASN1_TIME> to an
B<ASN1_GENERALIZEDTIME>, regardless of year. If either I<out> or
I<*out> are NULL, then a new object is allocated and must be freed after use.
=head1 NOTES
The ASN1_TIME structure corresponds to the ASN.1 structure B<Time>
The B<ASN1_TIME> structure corresponds to the ASN.1 structure B<Time>
defined in RFC5280 et al. The time setting functions obey the rules outlined
in RFC5280: if the date can be represented by UTCTime it is used, else
GeneralizedTime is used.
The ASN1_TIME, ASN1_UTCTIME and ASN1_GENERALIZEDTIME structures are represented
as an ASN1_STRING internally and can be freed up using ASN1_STRING_free().
The B<ASN1_TIME>, B<ASN1_UTCTIME> and B<ASN1_GENERALIZEDTIME> structures are
represented as an B<ASN1_STRING> internally and can be freed up using
ASN1_STRING_free().
The ASN1_TIME structure can represent years from 0000 to 9999 but no attempt
The B<ASN1_TIME> structure can represent years from 0000 to 9999 but no attempt
is made to correct ancient calendar changes (for example from Julian to
Gregorian calendars).
ASN1_UTCTIME is limited to a year range of 1950 through 2049.
B<ASN1_UTCTIME> is limited to a year range of 1950 through 2049.
Some applications add offset times directly to a time_t value and pass the
results to ASN1_TIME_set() (or equivalent). This can cause problems as the
time_t value can overflow on some systems resulting in unexpected results.
New applications should use ASN1_TIME_adj() instead and pass the offset value
in the B<offset_sec> and B<offset_day> parameters instead of directly
in the I<offset_sec> and I<offset_day> parameters instead of directly
manipulating a time_t value.
ASN1_TIME_adj() may change the type from ASN1_GENERALIZEDTIME to ASN1_UTCTIME,
or vice versa, based on the resulting year. The ASN1_GENERALIZEDTIME_adj() and
ASN1_UTCTIME_adj() functions will not modify the type of the return structure.
ASN1_TIME_adj() may change the type from B<ASN1_GENERALIZEDTIME> to
B<ASN1_UTCTIME>, or vice versa, based on the resulting year.
ASN1_GENERALIZEDTIME_adj() and ASN1_UTCTIME_adj() will not modify the type
of the return structure.
It is recommended that functions starting with ASN1_TIME be used instead of
those starting with ASN1_UTCTIME or ASN1_GENERALIZEDTIME. The functions
starting with ASN1_UTCTIME and ASN1_GENERALIZEDTIME act only on that specific
time format. The functions starting with ASN1_TIME will operate on either
format.
It is recommended that functions starting with B<ASN1_TIME> be used instead of
those starting with B<ASN1_UTCTIME> or B<ASN1_GENERALIZEDTIME>. The functions
starting with B<ASN1_UTCTIME> and B<ASN1_GENERALIZEDTIME> act only on that
specific time format. The functions starting with B<ASN1_TIME> will operate on
either format.
=head1 BUGS
ASN1_TIME_print(), ASN1_UTCTIME_print() and ASN1_GENERALIZEDTIME_print()
do not print out the time zone: it either prints out "GMT" or nothing. But all
do not print out the timezone: it either prints out "GMT" or nothing. But all
certificates complying with RFC5280 et al use GMT anyway.
Use the ASN1_TIME_normalize() function to normalize the time value before
@@ -175,21 +177,22 @@ printing to get GMT results.
=head1 RETURN VALUES
ASN1_TIME_set(), ASN1_UTCTIME_set(), ASN1_GENERALIZEDTIME_set(), ASN1_TIME_adj(),
ASN1_UTCTIME_adj and ASN1_GENERALIZEDTIME_set return a pointer to a time structure
or NULL if an error occurred.
ASN1_TIME_set(), ASN1_UTCTIME_set(), ASN1_GENERALIZEDTIME_set(),
ASN1_TIME_adj(), ASN1_UTCTIME_adj() and ASN1_GENERALIZEDTIME_set() return
a pointer to a time structure or NULL if an error occurred.
ASN1_TIME_set_string(), ASN1_UTCTIME_set_string(), ASN1_GENERALIZEDTIME_set_string()
ASN1_TIME_set_string_X509() return 1 if the time value is successfully set and 0 otherwise.
ASN1_TIME_set_string(), ASN1_UTCTIME_set_string(),
ASN1_GENERALIZEDTIME_set_string() and ASN1_TIME_set_string_X509() return
1 if the time value is successfully set and 0 otherwise.
ASN1_TIME_normalize() returns 1 on success, and 0 on error.
ASN1_TIME_check(), ASN1_UTCTIME_check and ASN1_GENERALIZEDTIME_check() return 1
if the structure is syntactically correct and 0 otherwise.
ASN1_TIME_print(), ASN1_UTCTIME_print() and ASN1_GENERALIZEDTIME_print() return 1
if the time is successfully printed out and 0 if an error occurred (I/O error or
invalid time format).
ASN1_TIME_print(), ASN1_UTCTIME_print() and ASN1_GENERALIZEDTIME_print() return
1 if the time is successfully printed out and 0 if an error occurred (I/O error
or invalid time format).
ASN1_TIME_to_tm() returns 1 if the time is successfully parsed and 0 if an
error occurred (invalid time format).
@@ -197,14 +200,15 @@ error occurred (invalid time format).
ASN1_TIME_diff() returns 1 for success and 0 for failure. It can fail if the
passed-in time structure has invalid syntax, for example.
ASN1_TIME_cmp_time_t() and ASN1_UTCTIME_cmp_time_t() return -1 if B<s> is
before B<t>, 0 if B<s> equals B<t>, or 1 if B<s> is after B<t>. -2 is returned
ASN1_TIME_cmp_time_t() and ASN1_UTCTIME_cmp_time_t() return -1 if I<s> is
before I<t>, 0 if I<s> equals I<t>, or 1 if I<s> is after I<t>. -2 is returned
on error.
ASN1_TIME_compare() returns -1 if B<a> is before B<b>, 0 if B<a> equals B<b>, or 1 if B<a> is after B<b>. -2 is returned on error.
ASN1_TIME_compare() returns -1 if I<a> is before I<b>, 0 if I<a> equals I<b>,
or 1 if I<a> is after I<b>. -2 is returned on error.
ASN1_TIME_to_generalizedtime() returns a pointer to
the appropriate time structure on success or NULL if an error occurred.
ASN1_TIME_to_generalizedtime() returns a pointer to the appropriate time
structure on success or NULL if an error occurred.
=head1 EXAMPLES
doc/man3/ASN1_TYPE_get.pod
+31 -30
View File
@@ -20,53 +20,54 @@ functions
=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
These functions allow an B<ASN1_TYPE> structure to be manipulated. The
B<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_get() returns the type of I<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
ASN1_TYPE_set() sets the value of I<a> to I<type> and I<value>. This
function uses the pointer I<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_set1() sets the value of I<a> to I<type> a copy of I<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_cmp() compares ASN.1 types I<a> and I<b> and returns 0 if
they are identical and nonzero 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
I<t> using the ASN.1 structure I<it>. If successful it returns a pointer
to the ASN.1 structure corresponding to I<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>.
ASN1_TYPE_pack_sequence() attempts to encode the ASN.1 structure I<s>
corresponding to I<it> into an B<ASN1_TYPE>. If successful the encoded
B<ASN1_TYPE> is returned. If I<t> and I<*t> are not NULL the encoded type
is written to I<t> overwriting any existing data. If I<t> is not NULL
but I<*t> is NULL the returned B<ASN1_TYPE> is written to I<*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
The type and meaning of the I<value> parameter for ASN1_TYPE_set() and
ASN1_TYPE_set1() is determined by the I<type> parameter.
If I<type> is B<V_ASN1_NULL> I<value> is ignored. If I<type> is
B<V_ASN1_BOOLEAN>
then the boolean is set to TRUE if I<value> is not NULL. If I<type> is
B<V_ASN1_OBJECT> then value is an B<ASN1_OBJECT> structure. Otherwise I<type>
is and B<ASN1_STRING> structure. If I<type> corresponds to a primitive type
(or a string type) then the contents of the B<ASN1_STRING> contain the content
octets of the type. If I<type> corresponds to a constructed type or
a tagged type (B<V_ASN1_SEQUENCE>, B<V_ASN1_SET> or B<V_ASN1_OTHER>) then the
B<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
value under BER can have any nonzero 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
return value is nonzero. 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
@@ -74,18 +75,18 @@ 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_get() returns the type of the B<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_cmp() returns 0 if the types are identical and nonzero 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
ASN1_TYPE_pack_sequence() return an B<ASN1_TYPE> structure if it succeeds or
NULL on failure.
=head1 COPYRIGHT
doc/man3/ASN1_generate_nconf.pod
+20 -20
View File
@@ -16,29 +16,29 @@ ASN1_generate_nconf, ASN1_generate_v3 - ASN1 generation functions
These functions generate the ASN1 encoding of a string
in an B<ASN1_TYPE> structure.
B<str> contains the string to encode B<nconf> or B<cnf> contains
I<str> contains the string to encode I<nconf> or I<cnf> contains
the optional configuration information where additional strings
will be read from. B<nconf> will typically come from a config
file whereas B<cnf> is obtained from an B<X509V3_CTX> structure
will be read from. I<nconf> will typically come from a config
file whereas I<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
functions. I<cnf> or I<nconf> can be set to NULL if no additional
configuration will be used.
=head1 GENERATION STRING FORMAT
The actual data encoded is determined by the string B<str> and
The actual data encoded is determined by the string I<str> and
the configuration information. The general format of the string
is:
=over 4
=item B<[modifier,]type[:value]>
=item [I<modifier>,]I<type>[:I<value>]
=back
That is zero or more comma separated modifiers followed by a type
followed by an optional colon and a value. The formats of B<type>,
B<value> and B<modifier> are explained below.
followed by an optional colon and a value. The formats of I<type>,
I<value> and I<modifier> are explained below.
=head2 Supported Types
@@ -49,18 +49,18 @@ only the B<ASCII> format is permissible.
=item B<BOOLEAN>, B<BOOL>
This encodes a boolean type. The B<value> string is mandatory and
This encodes a boolean type. The I<value> string is mandatory and
should be B<TRUE> or B<FALSE>. Additionally B<TRUE>, B<true>, B<Y>,
B<y>, B<YES>, B<yes>, B<FALSE>, B<false>, B<N>, B<n>, B<NO> and B<no>
are acceptable.
=item B<NULL>
Encode the B<NULL> type, the B<value> string must not be present.
Encode the B<NULL> type, the I<value> string must not be present.
=item B<INTEGER>, B<INT>
Encodes an ASN1 B<INTEGER> type. The B<value> string represents
Encodes an ASN1 B<INTEGER> type. The I<value> string represents
the value of the integer, it can be prefaced by a minus sign and
is normally interpreted as a decimal value unless the prefix B<0x>
is included.
@@ -72,7 +72,7 @@ B<INTEGER>.
=item B<OBJECT>, B<OID>
Encodes an ASN1 B<OBJECT IDENTIFIER>, the B<value> string can be
Encodes an ASN1 B<OBJECT IDENTIFIER>, the I<value> string can be
a short name, a long name or numerical format.
=item B<UTCTIME>, B<UTC>
@@ -87,15 +87,15 @@ the format B<YYYYMMDDHHMMSSZ>.
=item B<OCTETSTRING>, B<OCT>
Encodes an ASN1 B<OCTET STRING>. B<value> represents the contents
Encodes an ASN1 B<OCTET STRING>. I<value> represents the contents
of this structure, the format strings B<ASCII> and B<HEX> can be
used to specify the format of B<value>.
used to specify the format of I<value>.
=item B<BITSTRING>, B<BITSTR>
Encodes an ASN1 B<BIT STRING>. B<value> represents the contents
Encodes an ASN1 B<BIT STRING>. I<value> represents the contents
of this structure, the format strings B<ASCII>, B<HEX> and B<BITLIST>
can be used to specify the format of B<value>.
can be used to specify the format of I<value>.
If the format is anything other than B<BITLIST> the number of unused
bits is set to zero.
@@ -106,15 +106,15 @@ B<VISIBLE>, B<PRINTABLESTRING>, B<PRINTABLE>, B<T61>,
B<T61STRING>, B<TELETEXSTRING>, B<GeneralString>, B<NUMERICSTRING>,
B<NUMERIC>
These encode the corresponding string types. B<value> represents the
These encode the corresponding string types. I<value> represents the
contents of this structure. The format can be B<ASCII> or B<UTF8>.
=item B<SEQUENCE>, B<SEQ>, B<SET>
Formats the result as an ASN1 B<SEQUENCE> or B<SET> type. B<value>
Formats the result as an ASN1 B<SEQUENCE> or B<SET> type. I<value>
should be a section name which will contain the contents. The
field names in the section are ignored and the values are in the
generated string format. If B<value> is absent then an empty SEQUENCE
generated string format. If I<value> is absent then an empty SEQUENCE
will be encoded.
=back
@@ -165,7 +165,7 @@ bits are zero.
=head1 RETURN VALUES
ASN1_generate_nconf() and ASN1_generate_v3() return the encoded
data as an B<ASN1_TYPE> structure or B<NULL> if an error occurred.
data as an B<ASN1_TYPE> structure or NULL if an error occurred.
The error codes that can be obtained by L<ERR_get_error(3)>.
doc/man3/ASYNC_WAIT_CTX_new.pod
+69 -52
View File
@@ -48,45 +48,45 @@ ASYNC_STATUS_EAGAIN
=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
L<ASYNC_start_job(3)>. An B<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()
Application code must create an B<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().
the job is started it is associated with the B<ASYNC_WAIT_CTX> for the duration
of that job. An B<ASYNC_WAIT_CTX> should only be used for one B<ASYNC_JOB> at
any one time, but can be reused after an B<ASYNC_JOB> has finished for a
subsequent B<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.
B<ASYNC_WAIT_CTX>s can have "wait" file descriptors associated with them.
Calling ASYNC_WAIT_CTX_get_all_fds() and passing in a pointer to an
B<ASYNC_WAIT_CTX> in the I<ctx> parameter will return the wait file descriptors
associated with that job in I<*fd>. The number of file descriptors returned will
be stored in I<*numfds>. It is the caller's responsibility to ensure that
sufficient memory has been allocated in I<*fd> to receive all the file
descriptors. Calling ASYNC_WAIT_CTX_get_all_fds() with a NULL I<fd> value will
return no file descriptors but will still populate I<*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>
have changed since the last call time ASYNC_start_job() returned B<ASYNC_PAUSE>
(or since the B<ASYNC_WAIT_CTX> was created if no B<ASYNC_PAUSE> result has
been received). The I<numaddfds> and I<numdelfds> parameters will be populated
with the number of fds added or deleted respectively. I<*addfd> and I<*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.
stable fd for the lifetime of the B<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
@@ -94,21 +94,21 @@ 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 aware code (e.g. engines) can get the current B<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
these functions requires a I<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
B<ENGINE *> for the engine. The I<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().
the B<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
@@ -121,7 +121,7 @@ code that the job should be resumed by making the wait file descriptor
file descriptor.
As well as a file descriptor, user code may also be notified via a callback. The
callback and data pointers are stored within the ASYNC_WAIT_CTX along with an
callback and data pointers are stored within the B<ASYNC_WAIT_CTX> along with an
additional status field that can be used for the notification of retries from an
engine. This additional method can be used when the user thinks that a file
descriptor is too costly in terms of CPU cycles or in some context where a file
@@ -133,24 +133,41 @@ cryptography operation. It is a requirement that the callback function is small
and non-blocking as it will be run in the context of a polling mechanism or an
interrupt.
ASYNC_WAIT_CTX_get_callback() returns the callback set in the ASYNC_WAIT_CTX
ASYNC_WAIT_CTX_get_callback() returns the callback set in the B<ASYNC_WAIT_CTX>
structure.
ASYNC_WAIT_CTX_set_status() allows an engine to set the current engine status.
The possible status values are the following:
ASYNC_STATUS_UNSUPPORTED: The engine does not support the callback mechanism.
This is the default value. The engine must call ASYNC_WAIT_CTX_set_status() to
set the status to some value other than ASYNC_STATUS_UNSUPPORTED if it intends
to enable the callback mechanism.
ASYNC_STATUS_ERR: The engine has a fatal problem with this request. The user
code should clean up this session.
ASYNC_STATUS_OK: The request has been successfully submitted.
ASYNC_STATUS_EAGAIN: The engine has some problem which will be recovered soon,
such as a buffer is full, so user code should resume the job.
=over 4
=item B<ASYNC_STATUS_UNSUPPORTED>
The engine does not support the callback mechanism. This is the default value.
The engine must call ASYNC_WAIT_CTX_set_status() to set the status to some value
other than B<ASYNC_STATUS_UNSUPPORTED> if it intends to enable the callback
mechanism.
=item B<ASYNC_STATUS_ERR>
The engine has a fatal problem with this request. The user code should clean up
this session.
=item B<ASYNC_STATUS_OK>
The request has been successfully submitted.
=item B<ASYNC_STATUS_EAGAIN>
The engine has some problem which will be recovered soon, such as a buffer is
full, so user code should resume the job.
=back
ASYNC_WAIT_CTX_get_status() allows user code to obtain the current status value.
If the status is any value other than ASYNC_STATUS_OK then the user code should
not expect to receive a callback from the engine even if one has been set.
If the status is any value other than B<ASYNC_STATUS_OK> then the user code
should not expect to receive a callback from the engine even if one has been
set.
An example of the usage of the callback method might be the following. User
code would initiate cryptographic operations, and the engine code would dispatch
@@ -163,8 +180,8 @@ then the registered callback will be called.
=head1 RETURN VALUES
ASYNC_WAIT_CTX_new() returns a pointer to the newly allocated ASYNC_WAIT_CTX or
NULL on error.
ASYNC_WAIT_CTX_new() returns a pointer to the newly allocated B<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, ASYNC_WAIT_CTX_clear_fd,
doc/man3/ASYNC_start_job.pod
+45 -45
View File
@@ -27,40 +27,40 @@ ASYNC_get_current_job, ASYNC_block_pause, ASYNC_unblock_pause, ASYNC_is_capable
=head1 DESCRIPTION
OpenSSL implements asynchronous capabilities through an ASYNC_JOB. This
OpenSSL implements asynchronous capabilities through an B<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
The creation of an B<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).
The I<max_size> argument limits the number of B<ASYNC_JOB>s that will be held in
the pool. If I<max_size> is set to 0 then no upper limit is set. When an
B<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 B<ASYNC_JOB>s managed by
the pool does not exceed I<max_size>. When the pool is first initialised
I<init_size> B<ASYNC_JOB>s 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 I<max_size> of 0 (no upper limit) and an I<init_size> of 0 (no
B<ASYNC_JOB>s 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
Initially I<*job> should be NULL. I<ctx> should point to an B<ASYNC_WAIT_CTX>
object created through the L<ASYNC_WAIT_CTX_new(3)> function. I<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.
be stored on completion of the job. I<func> represents the function that should
be started asynchronously. The data pointed to by I<args> and of size I<size>
will be copied and then passed as an argument to I<func> when the job starts.
ASYNC_start_job will return one of the following values:
=over 4
@@ -78,47 +78,47 @@ 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
ASYNC_pause_job() below). A handle to the job is placed in I<*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.
a job call ASYNC_start_job() again passing the job handle in I<*job>. The
I<func>, I<args> and I<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>.
The job completed. I<*job> will be NULL and the return value from I<func> will
be placed in I<*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.
a pointer to the currently executing B<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
application with B<ASYNC_PAUSE> returned from the ASYNC_start_job() call. A
subsequent call to ASYNC_start_job passing in the relevant B<ASYNC_JOB> in the
I<*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 contain two different ways to notify
ASYNC_get_wait_ctx() can be used to get a pointer to the B<ASYNC_WAIT_CTX>
for the I<job>. B<ASYNC_WAIT_CTX>s contain two different ways to notify
applications that a job is ready to be resumed. One is a "wait" file
descriptor, and the other is a "callback" mechanism.
The "wait" file descriptor associated with ASYNC_WAIT_CTX is used for
The "wait" file descriptor associated with B<ASYNC_WAIT_CTX> is used for
applications to 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_WAIT_CTXs also have a "callback" mechanism to notify applications. The
B<ASYNC_WAIT_CTX>s also have a "callback" mechanism to notify applications. The
callback is set by an application, and it will be automatically called when an
engine completes a cryptography operation, so that the application can resume
the paused work flow without polling. An engine could be written to look whether
@@ -134,10 +134,10 @@ 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
to avoid deadlock scenarios. For example during the execution of an B<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
the B<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
@@ -150,17 +150,17 @@ can be used to detect whether the current platform is async capable or not.
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_start_job returns one of B<ASYNC_ERR>, B<ASYNC_NO_JOBS>, B<ASYNC_PAUSE> or
B<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.
not within the context of an B<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_current_job returns a pointer to the currently executing B<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_get_wait_ctx() returns a pointer to the B<ASYNC_WAIT_CTX> for the job.
ASYNC_is_capable() returns 1 if the current platform is async capable or 0
otherwise.
doc/man3/BIO_ADDR.pod
+2 -2
View File
@@ -50,7 +50,7 @@ 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>.
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
@@ -67,7 +67,7 @@ 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>.
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.
doc/man3/BIO_f_base64.pod
+1 -1
View File
@@ -6,7 +6,7 @@ BIO_f_base64 - base64 BIO filter
=head1 SYNOPSIS
=for comment multiple includes
=for openssl multiple includes
#include <openssl/bio.h>
#include <openssl/evp.h>
doc/man3/BIO_f_cipher.pod
+1 -1
View File
@@ -6,7 +6,7 @@ BIO_f_cipher, BIO_set_cipher, BIO_get_cipher_status, BIO_get_cipher_ctx - cipher
=head1 SYNOPSIS
=for comment multiple includes
=for openssl multiple includes
#include <openssl/bio.h>
#include <openssl/evp.h>
doc/man3/BIO_f_md.pod
+1 -1
View File
@@ -6,7 +6,7 @@ BIO_f_md, BIO_set_md, BIO_get_md, BIO_get_md_ctx - message digest BIO filter
=head1 SYNOPSIS
=for comment multiple includes
=for openssl multiple includes
#include <openssl/bio.h>
#include <openssl/evp.h>
doc/man3/BIO_f_ssl.pod
+1 -1
View File
@@ -11,7 +11,7 @@ BIO_ssl_shutdown - SSL BIO
=head1 SYNOPSIS
=for comment multiple includes
=for openssl multiple includes
#include <openssl/bio.h>
#include <openssl/ssl.h>
doc/man3/BIO_get_data.pod
+1 -1
View File
@@ -25,7 +25,7 @@ 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
whether initialisation has been completed for this BIO or not. A nonzero 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
doc/man3/BIO_get_ex_new_index.pod
+1 -1
View File
@@ -17,7 +17,7 @@ RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data
=head1 SYNOPSIS
=for comment generic
=for openssl generic
#include <openssl/x509.h>
doc/man3/BIO_parse_hostserv.pod
+2 -2
View File
@@ -19,10 +19,10 @@ BIO_parse_hostserv
=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
create strings with the hostname 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
be interpreted primarily as a hostname or a service name in ambiguous
cases.
The syntax the BIO_parse_hostserv() recognises is:
doc/man3/BIO_s_connect.pod
+1 -1
View File
@@ -106,7 +106,7 @@ If blocking I/O is set then a non positive return value from any
I/O call is caused by an error condition, although a zero return
will normally mean that the connection was closed.
If the port name is supplied as part of the host name then this will
If the port name is supplied as part of the hostname then this will
override any value set with BIO_set_conn_port(). This may be undesirable
if the application does not wish to allow connection to arbitrary
ports. This can be avoided by checking for the presence of the ':'
doc/man3/BIO_s_file.pod
+1 -1
View File
@@ -78,7 +78,7 @@ in stdio behaviour will be mirrored by the corresponding BIO.
On Windows BIO_new_files reserves for the filename argument to be
UTF-8 encoded. In other words if you have to make it work in multi-
lingual environment, encode file names in UTF-8.
lingual environment, encode filenames in UTF-8.
=head1 RETURN VALUES
doc/man3/BN_bn2bin.pod
+1 -1
View File
@@ -40,7 +40,7 @@ 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
B<to>. The result is padded with zeros 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
doc/man3/BN_generate_prime.pod
+53 -35
View File
@@ -2,7 +2,7 @@
=head1 NAME
BN_generate_prime_ex2, BN_generate_prime_ex, BN_is_prime_ex,
BN_generate_prime_ex2, BN_generate_prime_ex, BN_is_prime_ex, BN_check_prime,
BN_is_prime_fasttest_ex, BN_GENCB_call, 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
@@ -18,10 +18,7 @@ BN_is_prime, BN_is_prime_fasttest - generate primes and test for primality
int BN_generate_prime_ex(BIGNUM *ret, int bits, int safe, const BIGNUM *add,
const BIGNUM *rem, BN_GENCB *cb);
int BN_is_prime_ex(const BIGNUM *p, int nchecks, BN_CTX *ctx, BN_GENCB *cb);
int BN_is_prime_fasttest_ex(const BIGNUM *p, int nchecks, BN_CTX *ctx,
int do_trial_division, BN_GENCB *cb);
int BN_check_prime(const BIGNUM *p, BN_CTX *ctx, BN_GENCB *cb);
int BN_GENCB_call(BN_GENCB *cb, int a, int b);
@@ -45,19 +42,32 @@ L<openssl_user_macros(7)>:
BIGNUM *rem, void (*callback)(int, int, void *),
void *cb_arg);
int BN_is_prime(const BIGNUM *a, int checks,
int BN_is_prime(const BIGNUM *p, int nchecks,
void (*callback)(int, int, void *), BN_CTX *ctx, void *cb_arg);
int BN_is_prime_fasttest(const BIGNUM *a, int checks,
int BN_is_prime_fasttest(const BIGNUM *p, int nchecks,
void (*callback)(int, int, void *), BN_CTX *ctx,
void *cb_arg, int do_trial_division);
Deprecated since OpenSSL 3.0:
int BN_is_prime_ex(const BIGNUM *p, int nchecks, BN_CTX *ctx, BN_GENCB *cb);
int BN_is_prime_fasttest_ex(const BIGNUM *p, int nchecks, BN_CTX *ctx,
int do_trial_division, BN_GENCB *cb);
=head1 DESCRIPTION
BN_generate_prime_ex2() generates a pseudo-random prime number of
at least bit length B<bits> using the BN_CTX provided in B<ctx>. The value of
B<ctx> must not be NULL.
The returned number is probably prime with a negligible error.
The maximum error rate is 2^-128.
It's 2^-287 for a 512 bit prime, 2^-435 for a 1024 bit prime,
2^-648 for a 2048 bit prime, and lower than 2^-882 for primes larger
than 2048 bit.
If B<add> is B<NULL> the returned prime number will have exact bit
length B<bits> with the top most two bits set.
@@ -111,37 +121,43 @@ B<ctx> parameter is passed.
In this case the random number generator associated with the default OPENSSL_CTX
will be used.
BN_is_prime_ex() and BN_is_prime_fasttest_ex() test if the number B<p> is
prime. The following tests are performed until one of them shows that
B<p> is composite; if B<p> passes all these tests, it is considered
prime.
BN_check_prime(), BN_is_prime_ex(), BN_is_prime_fasttest_ex(), BN_is_prime()
and BN_is_prime_fasttest() test if the number B<p> is prime.
The functions tests until one of the tests shows that B<p> is composite,
or all the tests passed.
If B<p> passes all these tests, it is considered a probable prime.
BN_is_prime_fasttest_ex(), when called with B<do_trial_division == 1>,
first attempts trial division by a number of small primes;
if no divisors are found by this test and B<cb> is not B<NULL>,
B<BN_GENCB_call(cb, 1, -1)> is called.
If B<do_trial_division == 0>, this test is skipped.
The test performed on B<p> are trial division by a number of small primes
and rounds of the of the Miller-Rabin probabilistic primality test.
Both BN_is_prime_ex() and BN_is_prime_fasttest_ex() perform a Miller-Rabin
probabilistic primality test with B<nchecks> iterations. If
B<nchecks == BN_prime_checks>, a number of iterations is used that
yields a false positive rate of at most 2^-64 for random input.
The error rate depends on the size of the prime and goes down for bigger primes.
The rate is 2^-80 starting at 308 bits, 2^-112 at 852 bits, 2^-128 at 1080 bits,
2^-192 at 3747 bits and 2^-256 at 6394 bits.
The functions do at least 64 rounds of the Miller-Rabin test giving a maximum
false positive rate of 2^-128.
If the size of B<p> is more than 2048 bits, they do at least 128 rounds
giving a maximum false positive rate of 2^-256.
When the source of the prime is not random or not trusted, the number
of checks needs to be much higher to reach the same level of assurance:
It should equal half of the targeted security level in bits (rounded up to the
next integer if necessary).
For instance, to reach the 128 bit security level, B<nchecks> should be set to
64.
If B<nchecks> is larger than the minimum above (64 or 128), B<nchecks>
rounds of the Miller-Rabin test will be done.
If B<cb> is not B<NULL>, B<BN_GENCB_call(cb, 1, j)> is called
after the j-th iteration (j = 0, 1, ...). B<ctx> is a
pre-allocated B<BN_CTX> (to save the overhead of allocating and
If B<do_trial_division> set to B<0>, the trial division will be skipped.
BN_is_prime_ex() and BN_is_prime() always skip the trial division.
BN_is_prime_ex(), BN_is_prime_fasttest_ex(), BN_is_prime()
and BN_is_prime_fasttest() are deprecated.
BN_is_prime_fasttest() and BN_is_prime() behave just like
BN_is_prime_fasttest_ex() and BN_is_prime_ex() respectively, but with the old
style call back.
B<ctx> is a pre-allocated B<BN_CTX> (to save the overhead of allocating and
freeing the structure in a loop), or B<NULL>.
If the trial division is done, and no divisors are found and B<cb>
is not B<NULL>, B<BN_GENCB_call(cb, 1, -1)> is called.
After each round of the Miller-Rabin probabilistic primality test,
if B<cb> is not B<NULL>, B<BN_GENCB_call(cb, 1, j)> is called
with B<j> the iteration (j = 0, 1, ...).
BN_GENCB_call() calls the callback function held in the B<BN_GENCB> structure
and passes the ints B<a> and B<b> as arguments. There are two types of
B<BN_GENCB> structure that are supported: "new" style and "old" style. New
@@ -176,9 +192,9 @@ BN_is_prime_fasttest_ex(), respectively.
BN_generate_prime_ex() return 1 on success or 0 on error.
BN_is_prime_ex(), BN_is_prime_fasttest_ex(), BN_is_prime() and
BN_is_prime_fasttest() return 0 if the number is composite, 1 if it is
prime with an error probability of less than 0.25^B<nchecks>, and
BN_is_prime_ex(), BN_is_prime_fasttest_ex(), BN_is_prime(),
BN_is_prime_fasttest() and BN_check_prime return 0 if the number is composite,
1 if it is prime with an error probability of less than 0.25^B<nchecks>, and
-1 on error.
BN_generate_prime() returns the prime number on success, B<NULL> otherwise.
@@ -220,6 +236,8 @@ L<RAND(7)>
The BN_GENCB_new(), BN_GENCB_free(),
and BN_GENCB_get_arg() functions were added in OpenSSL 1.1.0.
BN_check_prime() was added in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
doc/man3/CONF_modules_free.pod
+1 -1
View File
@@ -30,7 +30,7 @@ to free up any configuration that module may have performed.
CONF_modules_unload() finishes and unloads configuration modules. If
B<all> is set to B<0> only modules loaded from DSOs will be unloads. If
B<all> is B<1> all modules, including builtin modules will be unloaded.
B<all> is B<1> all modules, including built-in modules will be unloaded.
=head1 RETURN VALUES
doc/man3/CRYPTO_memcmp.pod
+2 -2
View File
@@ -19,13 +19,13 @@ contents of the memory regions pointed to by B<a> and B<b>.
=head1 RETURN VALUES
CRYPTO_memcmp() returns 0 if the memory regions are equal and non-zero
CRYPTO_memcmp() returns 0 if the memory regions are equal and nonzero
otherwise.
=head1 NOTES
Unlike memcmp(2), this function cannot be used to order the two memory regions
as the return value when they differ is undefined, other than being non-zero.
as the return value when they differ is undefined, other than being nonzero.
=head1 COPYRIGHT
doc/man3/CT_POLICY_EVAL_CTX_new.pod
+1 -1
View File
@@ -88,7 +88,7 @@ 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.
The time should be in milliseconds since the Unix Epoch.
=back
doc/man3/DEFINE_STACK_OF.pod
+102 -97
View File
@@ -14,7 +14,7 @@ sk_TYPE_dup, sk_TYPE_deep_copy, sk_TYPE_set_cmp_func, sk_TYPE_new_reserve
=head1 SYNOPSIS
=for comment generic
=for openssl generic
#include <openssl/safestack.h>
@@ -61,13 +61,14 @@ sk_TYPE_dup, sk_TYPE_deep_copy, sk_TYPE_set_cmp_func, sk_TYPE_new_reserve
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>.
In the description here, B<I<TYPE>> is used
as a placeholder for any of the OpenSSL datatypes, such as B<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:
STACK_OF() returns the name for a stack of the specified B<I<TYPE>>.
DEFINE_STACK_OF() creates set of functions for a stack of B<I<TYPE>>. This
will mean that type B<I<TYPE>> is stored in each stack, the type is referenced by
B<STACK_OF>(B<I<TYPE>>) and each function name begins with B<sk_I<TYPE>_>.
For example:
TYPE *sk_TYPE_value(STACK_OF(TYPE) *sk, int idx);
@@ -76,7 +77,7 @@ 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
DEFINE_SPECIAL_STACK_OF() defines a stack of B<I<TYPE>> but
each function uses B<FUNCNAME> in the function name. For example:
TYPE *sk_FUNCNAME_value(STACK_OF(TYPE) *sk, int idx);
@@ -86,117 +87,119 @@ 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>.
B<sk_I<TYPE>_num>() returns the number of elements in I<sk> or -1 if I<sk> is
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.
B<sk_I<TYPE>_value>() returns element I<idx> in I<sk>, where I<idx> starts at
zero. If I<idx> is out of range then NULL is returned.
sk_TYPE_new() allocates a new empty stack using comparison function B<compare>.
If B<compare> is B<NULL> then no comparison function is used. This function is
equivalent to sk_TYPE_new_reserve(compare, 0).
B<sk_I<TYPE>_new>() allocates a new empty stack using comparison function
I<compare>. If I<compare> is NULL then no comparison function is used. This
function is equivalent to B<sk_I<TYPE>_new_reserve>(I<compare>, 0).
sk_TYPE_new_null() allocates a new empty stack with no comparison function. This
function is equivalent to sk_TYPE_new_reserve(NULL, 0).
B<sk_I<TYPE>_new_null>() allocates a new empty stack with no comparison
function. This function is equivalent to B<sk_I<TYPE>_new_reserve>(NULL, 0).
sk_TYPE_reserve() allocates additional memory in the B<sk> structure
such that the next B<n> calls to sk_TYPE_insert(), sk_TYPE_push()
or sk_TYPE_unshift() will not fail or cause memory to be allocated
or reallocated. If B<n> is zero, any excess space allocated in the
B<sk> structure is freed. On error B<sk> is unchanged.
B<sk_I<TYPE>_reserve>() allocates additional memory in the I<sk> structure
such that the next I<n> calls to B<sk_I<TYPE>_insert>(), B<sk_I<TYPE>_push>()
or B<sk_I<TYPE>_unshift>() will not fail or cause memory to be allocated
or reallocated. If I<n> is zero, any excess space allocated in the
I<sk> structure is freed. On error I<sk> is unchanged.
sk_TYPE_new_reserve() allocates a new stack. The new stack will have additional
memory allocated to hold B<n> elements if B<n> is positive. The next B<n> calls
to sk_TYPE_insert(), sk_TYPE_push() or sk_TYPE_unshift() will not fail or cause
memory to be allocated or reallocated. If B<n> is zero or less than zero, no
memory is allocated. sk_TYPE_new_reserve() also sets the comparison function
B<compare> to the newly created stack. If B<compare> is B<NULL> then no
comparison function is used.
B<sk_I<TYPE>_new_reserve>() allocates a new stack. The new stack will have
additional memory allocated to hold I<n> elements if I<n> is positive.
The next I<n> calls to B<sk_I<TYPE>_insert>(), B<sk_I<TYPE>_push>() or
B<sk_I<TYPE>_unshift>() will not fail or cause memory to be allocated or
reallocated. If I<n> is zero or less than zero, no memory is allocated.
B<sk_I<TYPE>_new_reserve>() also sets the comparison function I<compare>
to the newly created stack. If I<compare> is NULL then no comparison
function is used.
sk_TYPE_set_cmp_func() sets the comparison function of B<sk> to B<compare>.
The previous comparison function is returned or B<NULL> if there was
no previous comparison function.
B<sk_I<TYPE>_set_cmp_func>() sets the comparison function of I<sk> to
I<compare>. The previous comparison function is returned or 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.
B<sk_I<TYPE>_free>() frees up the I<sk> structure. It does I<not> free up any
elements of I<sk>. After this call I<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.
B<sk_I<TYPE>_zero>() sets the number of elements in I<sk> to zero. It does not
free I<sk> so after this call I<sk> is still valid.
sk_TYPE_pop_free() frees up all elements of B<sk> and B<sk> itself. The
B<sk_I<TYPE>_pop_free>() frees up all elements of I<sk> and I<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.
B<sk_I<TYPE>_delete>() deletes element I<i> from I<sk>. It returns the deleted
element or NULL if I<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.
B<sk_I<TYPE>_delete_ptr>() deletes element matching I<ptr> from I<sk>. It
returns the deleted element or NULL if no element matching I<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.
B<sk_I<TYPE>_insert>() inserts I<ptr> into I<sk> at position I<idx>. Any
existing elements at or after I<idx> are moved downwards. If I<idx> is out
of range the new element is appended to I<sk>. B<sk_I<TYPE>_insert>() either
returns the number of elements in I<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:
B<sk_I<TYPE>_push>() appends I<ptr> to I<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:
B<sk_I<TYPE>_unshift>() inserts I<ptr> at the start of I<sk> it is equivalent
to:
sk_TYPE_insert(sk, ptr, 0);
sk_TYPE_pop() returns and removes the last element from B<sk>.
B<sk_I<TYPE>_pop>() returns and removes the last element from I<sk>.
sk_TYPE_shift() returns and removes the first element from B<sk>.
B<sk_I<TYPE>_shift>() returns and removes the first element from I<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.
B<sk_I<TYPE>_set>() sets element I<idx> of I<sk> to I<ptr> replacing the current
element. The new element value is returned or NULL if an error occurred:
this will only happen if I<sk> is NULL or I<idx> is out of range.
sk_TYPE_find() searches B<sk> for the element B<ptr>. In the case
B<sk_I<TYPE>_find>() searches I<sk> for the element I<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
a linear search for a pointer equal to I<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
where a comparison function has been specified, I<sk> is sorted then
B<sk_I<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.
the order of elements in I<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>.
B<sk_I<TYPE>_find_ex>() operates like B<sk_I<TYPE>_find>() except when a
comparison function has been specified and no matching element is found.
Instead of returning B<-1>, B<sk_I<TYPE>_find_ex>() returns the index of the
element either before or after the location where I<ptr> would be if it were
present in I<sk>.
sk_TYPE_sort() sorts B<sk> using the supplied comparison function.
B<sk_I<TYPE>_sort>() sorts I<sk> using the supplied comparison function.
sk_TYPE_is_sorted() returns B<1> if B<sk> is sorted and B<0> otherwise.
B<sk_I<TYPE>_is_sorted>() returns B<1> if I<sk> is sorted and B<0> otherwise.
sk_TYPE_dup() returns a copy of B<sk>. Note the pointers in the copy
B<sk_I<TYPE>_dup>() returns a copy of I<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.
B<sk_I<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 operation which increases the size of a stack such as B<sk_I<TYPE>_insert>()
or B<sk_I<TYPE>_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 B<sk_I<TYPE>_find>() and B<sk_I<TYPE>_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.
positive or negative value if I<a> is equal to, greater than
or less than I<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
B<sk_I<TYPE>_find>() and B<sk_I<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.
@@ -216,48 +219,50 @@ OPENSSL_sk_zero().
=head1 RETURN VALUES
sk_TYPE_num() returns the number of elements in the stack or B<-1> if the
passed stack is B<NULL>.
B<sk_I<TYPE>_num>() returns the number of elements in the stack or B<-1> if the
passed stack is NULL.
sk_TYPE_value() returns a pointer to a stack element or B<NULL> if the
B<sk_I<TYPE>_value>() returns a pointer to a stack element or NULL if the
index is out of range.
sk_TYPE_new(), sk_TYPE_new_null() and sk_TYPE_new_reserve() return an empty
stack or B<NULL> if an error occurs.
B<sk_I<TYPE>_new>(), B<sk_I<TYPE>_new_null>() and B<sk_I<TYPE>_new_reserve>()
return an empty stack or NULL if an error occurs.
sk_TYPE_reserve() returns B<1> on successful allocation of the required memory
or B<0> on error.
B<sk_I<TYPE>_reserve>() returns B<1> on successful allocation of the required
memory or B<0> on error.
sk_TYPE_set_cmp_func() returns the old comparison function or B<NULL> if
B<sk_I<TYPE>_set_cmp_func>() returns the old comparison function or 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.
B<sk_I<TYPE>_free>(), B<sk_I<TYPE>_zero>(), B<sk_I<TYPE>_pop_free>() and
B<sk_I<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.
B<sk_I<TYPE>_pop>(), B<sk_I<TYPE>_shift>(), B<sk_I<TYPE>_delete>() and
B<sk_I<TYPE>_delete_ptr>() return a pointer to the deleted element or 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.
B<sk_I<TYPE>_insert>(), B<sk_I<TYPE>_push>() and B<sk_I<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
B<sk_I<TYPE>_set>() returns a pointer to the replacement element or NULL on
error.
sk_TYPE_find() and sk_TYPE_find_ex() return an index to the found element
or B<-1> on error.
B<sk_I<TYPE>_find>() and B<sk_I<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
B<sk_I<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.
B<sk_I<TYPE>_dup>() and B<sk_I<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.
sk_TYPE_reserve() and sk_TYPE_new_reserve() were added in OpenSSL 1.1.1.
B<sk_I<TYPE>_reserve>() and B<sk_I<TYPE>_new_reserve>() were added in OpenSSL
1.1.1.
=head1 COPYRIGHT
doc/man3/DES_random_key.pod
+2 -2
View File
@@ -134,7 +134,7 @@ DES_ecb_encrypt() is the basic DES encryption routine that encrypts or
decrypts a single 8-byte I<DES_cblock> in I<electronic code book>
(ECB) mode. It always transforms the input data, pointed to by
I<input>, into the output data, pointed to by the I<output> argument.
If the I<encrypt> argument is non-zero (DES_ENCRYPT), the I<input>
If the I<encrypt> argument is nonzero (DES_ENCRYPT), the I<input>
(cleartext) is encrypted in to the I<output> (ciphertext) using the
key_schedule specified by the I<schedule> argument, previously set via
I<DES_set_key>. If I<encrypt> is zero (DES_DECRYPT), the I<input> (now
@@ -153,7 +153,7 @@ The macro DES_ecb2_encrypt() is provided to perform two-key Triple-DES
encryption by using I<ks1> for the final encryption.
DES_ncbc_encrypt() encrypts/decrypts using the I<cipher-block-chaining>
(CBC) mode of DES. If the I<encrypt> argument is non-zero, the
(CBC) mode of DES. If the I<encrypt> argument is nonzero, the
routine cipher-block-chain encrypts the cleartext data pointed to by
the I<input> argument into the ciphertext pointed to by the I<output>
argument, using the key schedule provided by the I<schedule> argument,
doc/man3/DH_get0_pqg.pod
+1 -1
View File
@@ -81,7 +81,7 @@ 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
length parameter associated with this DH object. If the length is nonzero then
it is used, otherwise it is ignored. The B<length> parameter indicates the
length of the secret exponent (private key) in bits.
doc/man3/DH_set_method.pod
+1 -1
View File
@@ -64,7 +64,7 @@ B<DH_METHOD>s.
DH_set_default_method() returns no value.
DH_set_method() returns non-zero if the provided B<meth> was successfully set as
DH_set_method() returns nonzero if the provided B<meth> was successfully set as
the method for B<dh> (including unloading the ENGINE handle if the previous
method was supplied by an ENGINE).
doc/man3/DSA_set_method.pod
+1 -1
View File
@@ -64,7 +64,7 @@ B<DSA_METHOD>s.
DSA_set_default_method() returns no value.
DSA_set_method() returns non-zero if the provided B<meth> was successfully set as
DSA_set_method() returns nonzero if the provided B<meth> was successfully set as
the method for B<dsa> (including unloading the ENGINE handle if the previous
method was supplied by an ENGINE).
doc/man3/DTLSv1_listen.pod
+7 -5
View File
@@ -66,9 +66,9 @@ the peer and continue the handshake in a connected state.
Prior to calling DTLSv1_listen() user code must ensure that cookie generation
and verification callbacks have been set up using
SSL_CTX_set_cookie_generate_cb() and SSL_CTX_set_cookie_verify_cb()
respectively. For SSL_stateless(), SSL_CTX_set_stateless_cookie_generate_cb()
and SSL_CTX_set_stateless_cookie_verify_cb() must be used instead.
L<SSL_CTX_set_cookie_generate_cb(3)> and L<SSL_CTX_set_cookie_verify_cb(3)>
respectively. For SSL_stateless(), L<SSL_CTX_set_stateless_cookie_generate_cb(3)>
and L<SSL_CTX_set_stateless_cookie_verify_cb(3)> must be used instead.
Since DTLSv1_listen() operates entirely statelessly whilst processing incoming
ClientHellos it is unable to process fragmented messages (since this would
@@ -112,8 +112,10 @@ errors as non-fatal), whilst return codes >0 indicate success.
=head1 SEE ALSO
L<SSL_get_error(3)>, L<SSL_accept(3)>,
L<ssl(7)>, L<bio(7)>
L<SSL_CTX_set_cookie_generate_cb(3)>, L<SSL_CTX_set_cookie_verify_cb(3)>,
L<SSL_CTX_set_stateless_cookie_generate_cb(3)>,
L<SSL_CTX_set_stateless_cookie_verify_cb(3)>, L<SSL_get_error(3)>,
L<SSL_accept(3)>, L<ssl(7)>, L<bio(7)>
=head1 HISTORY
doc/man3/EC_GROUP_new.pod
+4 -4
View File
@@ -105,8 +105,8 @@ EC_GROUP_set_curve function. An appropriate default implementation method will b
Whilst the library can be used to create any curve using the functions described above, there are also a number of
predefined curves that are available. In order to obtain a list of all of the predefined curves, call the function
EC_get_builtin_curves. The parameter B<r> should be an array of EC_builtin_curve structures of size B<nitems>. The function
will populate the B<r> array with information about the builtin curves. If B<nitems> is less than the total number of
EC_get_builtin_curves(). The parameter B<r> should be an array of EC_builtin_curve structures of size B<nitems>. The function
will populate the B<r> array with information about the built-in curves. If B<nitems> is less than the total number of
curves available, then the first B<nitems> curves will be returned. Otherwise the total number of curves will be
provided. The return value is the total number of curves available (whether that number has been populated in B<r> or
not). Passing a NULL B<r>, or setting B<nitems> to 0 will do nothing other than return the total number of curves available.
@@ -119,7 +119,7 @@ The EC_builtin_curve structure is defined as follows:
Each EC_builtin_curve item has a unique integer id (B<nid>), and a human readable comment string describing the curve.
In order to construct a builtin curve use the function EC_GROUP_new_by_curve_name_ex and provide the B<nid> of the curve to
In order to construct a built-in curve use the function EC_GROUP_new_by_curve_name_ex and provide the B<nid> of the curve to
be constructed and the associated library context to be used in B<ctx> (see L<OPENSSL_CTX(3)>).
The B<ctx> value may be NULL in which case the default library context is used.
@@ -136,7 +136,7 @@ If B<group> is NULL nothing is done.
All EC_GROUP_new* functions return a pointer to the newly constructed group, or NULL on error.
EC_get_builtin_curves returns the number of builtin curves that are available.
EC_get_builtin_curves returns the number of built-in curves that are available.
EC_GROUP_set_curve_GFp, EC_GROUP_get_curve_GFp, EC_GROUP_set_curve_GF2m, EC_GROUP_get_curve_GF2m return 1 on success or 0 on error.
doc/man3/ENGINE_add.pod
+6 -6
View File
@@ -254,7 +254,7 @@ To obtain a functional reference from an existing structural reference,
call the ENGINE_init() function. This returns zero if the ENGINE was not
already operational and couldn't be successfully initialised (eg. lack of
system drivers, no special hardware attached, etc), otherwise it will
return non-zero to indicate that the ENGINE is now operational and will
return nonzero to indicate that the ENGINE is now operational and will
have allocated a new B<functional> reference to the ENGINE. All functional
references are released by calling ENGINE_finish() (which removes the
implicit structural reference as well).
@@ -333,7 +333,7 @@ acceleration hardware attached to the machine or some such thing. There are
probably numerous other ways in which applications may prefer to handle
things, so we will simply illustrate the consequences as they apply to a
couple of simple cases and leave developers to consider these and the
source code to openssl's builtin utilities as guides.
source code to openssl's built-in utilities as guides.
If no ENGINE API functions are called within an application, then OpenSSL
will not allocate any internal resources. Prior to OpenSSL 1.1.0, however,
@@ -346,7 +346,7 @@ Here we'll assume an application has been configured by its user or admin
to want to use the "ACME" ENGINE if it is available in the version of
OpenSSL the application was compiled with. If it is available, it should be
used by default for all RSA, DSA, and symmetric cipher operations, otherwise
OpenSSL should use its builtin software as per usual. The following code
OpenSSL should use its built-in software as per usual. The following code
illustrates how to approach this;
ENGINE *e;
@@ -374,7 +374,7 @@ illustrates how to approach this;
/* Release the structural reference from ENGINE_by_id() */
ENGINE_free(e);
I<Automatically using builtin ENGINE implementations>
I<Automatically using built-in ENGINE implementations>
Here we'll assume we want to load and register all ENGINE implementations
bundled with OpenSSL, such that for any cryptographic algorithm required by
@@ -422,7 +422,7 @@ calling ENGINE_init(). The other class of commands consist of settings or
operations that tweak certain behaviour or cause certain operations to take
place, and these commands may work either before or after ENGINE_init(), or
in some cases both. ENGINE implementations should provide indications of
this in the descriptions attached to builtin control commands and/or in
this in the descriptions attached to built-in control commands and/or in
external product documentation.
I<Issuing control commands to an ENGINE>
@@ -477,7 +477,7 @@ boolean success or failure.
}
Note that ENGINE_ctrl_cmd_string() accepts a boolean argument that can
relax the semantics of the function - if set non-zero it will only return
relax the semantics of the function - if set nonzero it will only return
failure if the ENGINE supported the given command name but failed while
executing it, if the ENGINE doesn't support the command name it will simply
return success without doing anything. In this case we assume the user is
doc/man3/ERR_get_error.pod
+19 -12
View File
@@ -61,28 +61,35 @@ error queue without modifying it.
ERR_peek_last_error() returns the latest error code from the thread's
error queue without modifying it.
See L<ERR_GET_LIB(3)> for obtaining information about
location and reason of the error, and
L<ERR_error_string(3)> for human-readable error
messages.
See L<ERR_GET_LIB(3)> for obtaining further specific information
such as the reason of the error,
and L<ERR_error_string(3)> for human-readable error messages.
ERR_get_error_line(), ERR_peek_error_line() and
ERR_peek_last_error_line() are the same as ERR_get_error(),
ERR_peek_error() and ERR_peek_last_error(), but they
additionally store the file name and line number where
the error occurred in *B<file> and *B<line>, unless these are B<NULL>.
ERR_peek_error() and ERR_peek_last_error(), but on success they
additionally store the filename and line number where
the error occurred in *B<file> and *B<line>, as far as they are not B<NULL>.
An unset filename is indicated as B<"">, i.e., an empty string.
An unset line number is indicated as B<0>.
A pointer returned this way by these functions and the ones below
is valid until the respective entry is removed from the error queue.
ERR_get_error_func(), ERR_peek_error_func() and
ERR_peek_last_error_func() are the same as ERR_get_error(),
ERR_peek_error() and ERR_peek_last_error(), but they
additionally store the name of the function where the error in *B<func>,
unless it is B<NULL>.
ERR_peek_error() and ERR_peek_last_error(), but on success they
additionally store the name of the function where the error occurred
in *B<func>, unless it is B<NULL>.
An unset function name is indicated as B<"">.
ERR_get_error_data(), ERR_peek_error_data() and
ERR_peek_last_error_data() are the same as ERR_get_error(),
ERR_peek_error() and ERR_peek_last_error(), but they
ERR_peek_error() and ERR_peek_last_error(), but on success they
additionally store additional data and flags associated with the error
code in *B<data> and *B<flags>, unless these are B<NULL>.
code in *B<data> and *B<flags>, as far as they are not B<NULL>.
Unset data is indicated as B<"">.
In this case the value given for the flag is irrelevant (and equals B<0>).
*B<data> contains a string if *B<flags>&B<ERR_TXT_STRING> is true.
ERR_get_error_all(), ERR_peek_error_all() and
doc/man3/ERR_load_strings.pod
+1 -1
View File
@@ -34,7 +34,7 @@ ERR_PACK() is a macro.
The last entry in the array is {0,0}.
ERR_get_next_error_library() can be used to assign library numbers
to user libraries at runtime.
to user libraries at run time.
=head1 RETURN VALUES
doc/man3/ERR_new.pod
+1 -1
View File
@@ -25,7 +25,7 @@ ERR_new() allocates a new slot in the thread's error queue.
ERR_set_debug() sets the debug information related to the current
error in the thread's error queue.
The values that can be given are the file name I<file>, line in the
The values that can be given are the filename I<file>, line in the
file I<line> and the name of the function I<func> where the error
occured.
The names must be constant, this function will only save away the
doc/man3/ERR_print_errors.pod
+1 -1
View File
@@ -29,7 +29,7 @@ B<u> as the callback parameters.
The error strings will have the following format:
[pid]:error:[error code]:[library name]:[function name]:[reason string]:[file name]:[line]:[optional text message]
[pid]:error:[error code]:[library name]:[function name]:[reason string]:[filename]:[line]:[optional text message]
I<error code> is an 8 digit hexadecimal number. I<library name>,
I<function name> and I<reason string> are ASCII text, as is I<optional
doc/man3/ERR_put_error.pod
+2 -2
View File
@@ -59,14 +59,14 @@ descriptions. For example, the function ssl3_read_bytes() reports a
SSLerr(SSL_F_SSL3_READ_BYTES, SSL_R_SSL_HANDSHAKE_FAILURE);
Function and reason codes should consist of upper case characters,
Function and reason codes should consist of uppercase characters,
numbers and underscores only. The error file generation script translates
function codes into function names by looking in the header files
for an appropriate function name, if none is found it just uses
the capitalized form such as "SSL3_READ_BYTES" in the above example.
The trailing section of a reason code (after the "_R_") is translated
into lower case and underscores changed to spaces.
into lowercase and underscores changed to spaces.
Although a library will normally report errors using its own specific
XXXerr macro, another library's macro can be used. This is normally
doc/man3/EVP_DigestInit.pod
+46 -16
View File
@@ -7,11 +7,12 @@ EVP_MD_get_params, EVP_MD_gettable_params,
EVP_MD_CTX_new, EVP_MD_CTX_reset, EVP_MD_CTX_free, EVP_MD_CTX_copy,
EVP_MD_CTX_copy_ex, EVP_MD_CTX_ctrl,
EVP_MD_CTX_set_params, EVP_MD_CTX_get_params,
EVP_MD_settable_ctx_params, EVP_MD_gettable_ctx_params,
EVP_MD_CTX_settable_params, EVP_MD_CTX_gettable_params,
EVP_MD_CTX_set_flags, EVP_MD_CTX_clear_flags, EVP_MD_CTX_test_flags,
EVP_Digest, EVP_DigestInit_ex, EVP_DigestInit, EVP_DigestUpdate,
EVP_DigestFinal_ex, EVP_DigestFinalXOF, EVP_DigestFinal,
EVP_MD_name, EVP_MD_provider,
EVP_MD_is_a, EVP_MD_name, EVP_MD_number, EVP_MD_names_do_all, EVP_MD_provider,
EVP_MD_type, EVP_MD_pkey_type, EVP_MD_size, EVP_MD_block_size, EVP_MD_flags,
EVP_MD_CTX_name,
EVP_MD_CTX_md, EVP_MD_CTX_type, EVP_MD_CTX_size, EVP_MD_CTX_block_size,
@@ -19,7 +20,7 @@ EVP_MD_CTX_md_data, EVP_MD_CTX_update_fn, EVP_MD_CTX_set_update_fn,
EVP_md_null,
EVP_get_digestbyname, EVP_get_digestbynid, EVP_get_digestbyobj,
EVP_MD_CTX_pkey_ctx, EVP_MD_CTX_set_pkey_ctx,
EVP_MD_do_all_ex
EVP_MD_do_all_provided
- EVP digest routines
=head1 SYNOPSIS
@@ -38,8 +39,10 @@ EVP_MD_do_all_ex
void EVP_MD_CTX_ctrl(EVP_MD_CTX *ctx, int cmd, int p1, void* p2);
int EVP_MD_CTX_get_params(EVP_MD_CTX *ctx, OSSL_PARAM params[]);
int EVP_MD_CTX_set_params(EVP_MD_CTX *ctx, const OSSL_PARAM params[]);
const OSSL_PARAM *EVP_MD_CTX_settable_params(const EVP_MD *digest);
const OSSL_PARAM *EVP_MD_CTX_gettable_params(const EVP_MD *digest);
const OSSL_PARAM *EVP_MD_settable_ctx_params(const EVP_MD *md);
const OSSL_PARAM *EVP_MD_gettable_ctx_params(const EVP_MD *md);
const OSSL_PARAM *EVP_MD_CTX_settable_params(EVP_MD_CTX *ctx);
const OSSL_PARAM *EVP_MD_CTX_gettable_params(EVP_MD_CTX *ctx);
void EVP_MD_CTX_set_flags(EVP_MD_CTX *ctx, int flags);
void EVP_MD_CTX_clear_flags(EVP_MD_CTX *ctx, int flags);
int EVP_MD_CTX_test_flags(const EVP_MD_CTX *ctx, int flags);
@@ -59,6 +62,11 @@ EVP_MD_do_all_ex
int EVP_MD_CTX_copy(EVP_MD_CTX *out, EVP_MD_CTX *in);
const char *EVP_MD_name(const EVP_MD *md);
int EVP_MD_number(const EVP_MD *md);
int EVP_MD_is_a(const EVP_MD *md, const char *name);
void EVP_MD_names_do_all(const EVP_MD *md,
void (*fn)(const char *name, void *data),
void *data);
const OSSL_PROVIDER *EVP_MD_provider(const EVP_MD *md);
int EVP_MD_type(const EVP_MD *md);
int EVP_MD_pkey_type(const EVP_MD *md);
@@ -87,9 +95,9 @@ EVP_MD_do_all_ex
EVP_PKEY_CTX *EVP_MD_CTX_pkey_ctx(const EVP_MD_CTX *ctx);
void EVP_MD_CTX_set_pkey_ctx(EVP_MD_CTX *ctx, EVP_PKEY_CTX *pctx);
void EVP_MD_do_all_ex(OPENSSL_CTX *libctx,
void (*fn)(EVP_MD *mac, void *arg),
void *arg);
void EVP_MD_do_all_provided(OPENSSL_CTX *libctx,
void (*fn)(EVP_MD *mac, void *arg),
void *arg);
=head1 DESCRIPTION
@@ -158,12 +166,17 @@ See L</PARAMETERS> below for more information.
Sets the list of B<params> into a MD context B<ctx>.
See L</PARAMETERS> below for more information.
=item EVP_MD_gettable_params(), EVP_MD_CTX_gettable_params(),
=item EVP_MD_gettable_params(), EVP_MD_gettable_ctx_params(),
EVP_MD_settable_ctx_params(), EVP_MD_CTX_gettable_params(),
EVP_MD_CTX_settable_params()
Get a B<OSSL_PARAM> array that describes the retrievable and settable
parameters, i.e. parameters that can be used with EVP_MD_get_params(),
EVP_MD_CTX_get_params() and EVP_MD_CTX_set_params(), respectively.
parameters. EVP_MD_gettable_params() returns parameters that can be used with
EVP_MD_get_params(). EVP_MD_gettable_ctx_params() and
EVP_MD_CTX_gettable_params() return parameters that can be used with
EVP_MD_CTX_get_params(). EVP_MD_settable_ctx_params() and
EVP_MD_CTX_settable_params() return parameters that can be used with
EVP_MD_CTX_set_params().
See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor.
=item EVP_MD_CTX_set_flags(), EVP_MD_CTX_clear_flags(), EVP_MD_CTX_test_flags()
@@ -218,7 +231,7 @@ few bytes.
=item EVP_DigestInit()
Behaves in the same way as EVP_DigestInit_ex() except it always uses the
default digest implementation.
default digest implementation and calls EVP_MD_CTX_reset().
=item EVP_DigestFinal()
@@ -230,10 +243,27 @@ automatically cleaned up.
Similar to EVP_MD_CTX_copy_ex() except the destination B<out> does not have to
be initialized.
=item EVP_MD_is_a()
Returns 1 if I<md> is an implementation of an algorithm that's
identifiable with I<name>, otherwise 0.
=item EVP_MD_number()
Returns the internal dynamic number assigned to the I<md>. This is
only useful with fetched B<EVP_MD>s.
=item EVP_MD_name(),
EVP_MD_CTX_name()
Return the name of the given message digest.
Return the name of the given message digest. For fetched message
digests with multiple names, only one of them is returned; it's
recommended to use EVP_MD_names_do_all() instead.
=item EVP_MD_names_do_all()
Traverses all names for the I<md>, and calls I<fn> with each name and
I<data>. This is only useful with fetched B<EVP_MD>s.
=item EVP_MD_provider()
@@ -322,7 +352,7 @@ by the caller. A NULL B<pctx> pointer is also allowed to clear the B<EVP_PKEY_CT
assigned to B<ctx>. In such case, freeing the cleared B<EVP_PKEY_CTX> or not
depends on how the B<EVP_PKEY_CTX> is created.
=item EVP_MD_do_all_ex()
=item EVP_MD_do_all_provided()
Traverses all messages digests implemented by all activated providers
in the given library context I<libctx>, and for each of the implementations,
@@ -339,13 +369,13 @@ EVP_MD_CTX_set_params() can be used with the following OSSL_PARAM keys:
=over 4
=item OSSL_PARAM_DIGEST_KEY_XOFLEN <unsigned integer>
=item "xoflen" (B<OSSL_PARAM_DIGEST_KEY_XOFLEN>) <unsigned integer>
Sets the digest length for extendable output functions.
It is used by the SHAKE algorithm and should not exceed what can be given
using a B<size_t>.
=item OSSL_PARAM_DIGEST_KEY_PAD_TYPE <integer>
=item "pad_type" (B<OSSL_PARAM_DIGEST_KEY_PAD_TYPE>) <integer>
Sets the pad type.
It is used by the MDC2 algorithm.
@@ -356,7 +386,7 @@ EVP_MD_CTX_get_params() can be used with the following OSSL_PARAM keys:
=over 4
=item OSSL_PARAM_DIGEST_KEY_MICALG <UTF8 string>.
=item "micalg" (B<OSSL_PARAM_DIGEST_KEY_MICALG>) <UTF8 string>.
Gets the digest Message Integrity Check algorithm string. This is used when
creating S/MIME multipart/signed messages, as specified in RFC 3851.
doc/man3/EVP_DigestSignInit.pod
+50 -17
View File
@@ -2,13 +2,16 @@
=head1 NAME
EVP_DigestSignInit, EVP_DigestSignUpdate, EVP_DigestSignFinal,
EVP_DigestSign - EVP signing functions
EVP_DigestSignInit_ex, EVP_DigestSignInit, EVP_DigestSignUpdate,
EVP_DigestSignFinal, EVP_DigestSign - EVP signing functions
=head1 SYNOPSIS
#include <openssl/evp.h>
int EVP_DigestSignInit_ex(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx,
const char *mdname, const char *props,
EVP_PKEY *pkey, EVP_SIGNATURE *signature);
int EVP_DigestSignInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx,
const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey);
int EVP_DigestSignUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt);
@@ -21,22 +24,44 @@ EVP_DigestSign - EVP signing functions
=head1 DESCRIPTION
The EVP signature routines are a high level interface to digital signatures.
Input data is digested first before the signing takes place.
EVP_DigestSignInit() sets up signing context B<ctx> to use digest B<type> from
ENGINE B<e> and private key B<pkey>. B<ctx> must be created with
EVP_MD_CTX_new() before calling this function. If B<pctx> is not NULL, the
EVP_PKEY_CTX of the signing operation will be written to B<*pctx>: this can
be used to set alternative signing options. Note that any existing value in
B<*pctx> is overwritten. The EVP_PKEY_CTX value returned must not be freed
directly by the application if B<ctx> is not assigned an EVP_PKEY_CTX value before
being passed to EVP_DigestSignInit() (which means the EVP_PKEY_CTX is created
inside EVP_DigestSignInit() and it will be freed automatically when the
EVP_MD_CTX is freed).
EVP_DigestSignInit_ex() sets up signing context B<ctx> to use a digest with the
name B<mdname> and private key B<pkey>. The signature algorithm B<signature>
will be used for the actual signing which must be compatible with the private
key. The name of the digest to be used is passed to the provider of the
signature algorithm in use. How that provider interprets the digest name is
provider specific. The provider may implement that digest directly itself or it
may (optionally) choose to fetch it (which could result in a digest from a
different provider being selected). If the provider supports fetching the digest
then it may use the B<props> argument for the properties to be used during the
fetch.
The digest B<type> may be NULL if the signing algorithm supports it.
The B<signature> parameter may be NULL in which case a suitable signature
algorithm implementation will be implicitly fetched based on the type of key in
use. See L<provider(7)> for further information about providers and fetching
algorithms.
No B<EVP_PKEY_CTX> will be created by EVP_DigestSignInit() if the passed B<ctx>
has already been assigned one via L<EVP_MD_CTX_set_ctx(3)>. See also L<SM2(7)>.
The OpenSSL default and legacy providers support fetching digests and can fetch
those digests from any available provider. The OpenSSL fips provider also
supports fetching digests but will only fetch digests that are themselves
implemented inside the fips provider.
B<ctx> must be created with EVP_MD_CTX_new() before calling this function. If
B<pctx> is not NULL, the EVP_PKEY_CTX of the signing operation will be written
to B<*pctx>: this can be used to set alternative signing options. Note that any
existing value in B<*pctx> is overwritten. The EVP_PKEY_CTX value returned must
not be freed directly by the application if B<ctx> is not assigned an
EVP_PKEY_CTX value before being passed to EVP_DigestSignInit_ex() (which means
the EVP_PKEY_CTX is created inside EVP_DigestSignInit_ex() and it will be freed
automatically when the EVP_MD_CTX is freed).
The digest B<mdname> may be NULL if the signing algorithm supports it. The
B<props> argument can always be NULL.
No B<EVP_PKEY_CTX> will be created by EVP_DigestSignInit_ex() if the passed
B<ctx> has already been assigned one via L<EVP_MD_CTX_set_ctx(3)>. See also
L<SM2(7)>.
Only EVP_PKEY types that support signing can be used with these functions. This
includes MAC algorithms where the MAC generation is considered as a form of
@@ -84,10 +109,14 @@ Will ignore any digest provided.
If RSA-PSS is used and restrictions apply then the digest must match.
EVP_DigestSignInit() works in the same way as EVP_DigestSignInit_ex() except
that the B<mdname> parameter will be inferred from the supplied digest B<type>,
and B<props> will be NULL. Where supplied the ENGINE B<e> will be used for the
signing and digest algorithm implementations. B<e> may be NULL.
EVP_DigestSignUpdate() hashes B<cnt> bytes of data at B<d> into the
signature context B<ctx>. This function can be called several times on the
same B<ctx> to include additional data. This function is currently implemented
using a macro.
same B<ctx> to include additional data.
EVP_DigestSignFinal() signs the data in B<ctx> and places the signature in B<sig>.
If B<sig> is B<NULL> then the maximum size of the output buffer is written to
@@ -156,6 +185,10 @@ L<RAND(7)>
EVP_DigestSignInit(), EVP_DigestSignUpdate() and EVP_DigestSignFinal()
were added in OpenSSL 1.0.0.
EVP_DigestSignInit_ex() was added in OpenSSL 3.0.
EVP_DigestSignUpdate() was converted from a macro to a function in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2006-2018 The OpenSSL Project Authors. All Rights Reserved.
doc/man3/EVP_DigestVerifyInit.pod
+90 -16
View File
@@ -2,13 +2,16 @@
=head1 NAME
EVP_DigestVerifyInit, EVP_DigestVerifyUpdate, EVP_DigestVerifyFinal,
EVP_DigestVerify - EVP signature verification functions
EVP_DigestVerifyInit_ex, EVP_DigestVerifyInit, EVP_DigestVerifyUpdate,
EVP_DigestVerifyFinal, EVP_DigestVerify - EVP signature verification functions
=head1 SYNOPSIS
#include <openssl/evp.h>
int EVP_DigestVerifyInit_ex(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx,
const char *mdname, const char *props,
EVP_PKEY *pkey, EVP_SIGNATURE *signature);
int EVP_DigestVerifyInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx,
const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey);
int EVP_DigestVerifyUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt);
@@ -20,25 +23,91 @@ EVP_DigestVerify - EVP signature verification functions
=head1 DESCRIPTION
The EVP signature routines are a high level interface to digital signatures.
Input data is digested first before the signature verification takes place.
EVP_DigestVerifyInit() sets up verification context B<ctx> to use digest
B<type> from ENGINE B<e> and public key B<pkey>. B<ctx> must be created
with EVP_MD_CTX_new() before calling this function. If B<pctx> is not NULL, the
EVP_PKEY_CTX of the verification operation will be written to B<*pctx>: this
can be used to set alternative verification options. Note that any existing
value in B<*pctx> is overwritten. The EVP_PKEY_CTX value returned must not be freed
directly by the application if B<ctx> is not assigned an EVP_PKEY_CTX value before
being passed to EVP_DigestVerifyInit() (which means the EVP_PKEY_CTX is created
inside EVP_DigestVerifyInit() and it will be freed automatically when the
EVP_MD_CTX is freed).
EVP_DigestVerifyInit_ex() sets up verification context B<ctx> to use a digest
with the name B<mdname> and public key B<pkey>. The signature algorithm
B<signature> will be used for the actual signature verification which must be
compatible with the public key. The name of the digest to be used is passed to
the provider of the signature algorithm in use. How that provider interprets the
digest name is provider specific. The provider may implement that digest
directly itself or it may (optionally) choose to fetch it (which could result in
a digest from a different provider being selected). If the provider supports
fetching the digest then it may use the B<props> argument for the properties to
be used during the fetch.
No B<EVP_PKEY_CTX> will be created by EVP_DigestSignInit() if the passed B<ctx>
has already been assigned one via L<EVP_MD_CTX_set_ctx(3)>. See also L<SM2(7)>.
The B<signature> parameter may be NULL in which case a suitable signature
algorithm implementation will be implicitly fetched based on the type of key in
use. See L<provider(7)> for further information about providers and fetching
algorithms.
The OpenSSL default and legacy providers support fetching digests and can fetch
those digests from any available provider. The OpenSSL fips provider also
supports fetching digests but will only fetch digests that are themselves
implemented inside the fips provider.
B<ctx> must be created with EVP_MD_CTX_new() before calling this function. If
B<pctx> is not NULL, the EVP_PKEY_CTX of the verification operation will be
written to B<*pctx>: this can be used to set alternative verification options.
Note that any existing value in B<*pctx> is overwritten. The EVP_PKEY_CTX value
returned must not be freed directly by the application if B<ctx> is not assigned
an EVP_PKEY_CTX value before being passed to EVP_DigestVerifyInit_ex() (which
means the EVP_PKEY_CTX is created inside EVP_DigestVerifyInit_ex() and it will
be freed automatically when the EVP_MD_CTX is freed).
No B<EVP_PKEY_CTX> will be created by EVP_DigestSignInit_ex() if the passed
B<ctx> has already been assigned one via L<EVP_MD_CTX_set_ctx(3)>. See also
L<SM2(7)>.
Not all digests can be used for all key types. The following combinations apply.
=over 4
=item DSA
Supports SHA1, SHA224, SHA256, SHA384 and SHA512
=item ECDSA
Supports SHA1, SHA224, SHA256, SHA384, SHA512 and SM3
=item RSA with no padding
Supports no digests (the digest B<type> must be NULL)
=item RSA with X931 padding
Supports SHA1, SHA256, SHA384 and SHA512
=item All other RSA padding types
Support SHA1, SHA224, SHA256, SHA384, SHA512, MD5, MD5_SHA1, MD2, MD4, MDC2,
SHA3-224, SHA3-256, SHA3-384, SHA3-512
=item Ed25519 and Ed448
Support no digests (the digest B<type> must be NULL)
=item HMAC
Supports any digest
=item CMAC, Poly1305 and SipHash
Will ignore any digest provided.
=back
If RSA-PSS is used and restrictions apply then the digest must match.
EVP_DigestVerifyInit() works in the same way as EVP_DigestVerifyInit_ex() except
that the B<mdname> parameter will be inferred from the supplied digest B<type>,
and B<props> will be NULL. Where supplied the ENGINE B<e> will be used for the
signature verification and digest algorithm implementations. B<e> may be NULL.
EVP_DigestVerifyUpdate() hashes B<cnt> bytes of data at B<d> into the
verification context B<ctx>. This function can be called several times on the
same B<ctx> to include additional data. This function is currently implemented
using a macro.
same B<ctx> to include additional data.
EVP_DigestVerifyFinal() verifies the data in B<ctx> against the signature in
B<sig> of length B<siglen>.
@@ -102,6 +171,11 @@ L<RAND(7)>
EVP_DigestVerifyInit(), EVP_DigestVerifyUpdate() and EVP_DigestVerifyFinal()
were added in OpenSSL 1.0.0.
EVP_DigestVerifyInit_ex() was added in OpenSSL 3.0.
EVP_DigestVerifyUpdate() was converted from a macro to a function in OpenSSL
3.0.
=head1 COPYRIGHT
Copyright 2006-2018 The OpenSSL Project Authors. All Rights Reserved.
doc/man3/EVP_EncryptInit.pod
+47 -14
View File
@@ -25,11 +25,14 @@ EVP_DecryptInit,
EVP_DecryptFinal,
EVP_CipherInit,
EVP_CipherFinal,
EVP_Cipher,
EVP_get_cipherbyname,
EVP_get_cipherbynid,
EVP_get_cipherbyobj,
EVP_CIPHER_is_a,
EVP_CIPHER_name,
EVP_CIPHER_number,
EVP_CIPHER_names_do_all,
EVP_CIPHER_provider,
EVP_CIPHER_nid,
EVP_CIPHER_get_params,
@@ -44,9 +47,9 @@ EVP_CIPHER_CTX_cipher,
EVP_CIPHER_CTX_name,
EVP_CIPHER_CTX_nid,
EVP_CIPHER_CTX_get_params,
EVP_CIPHER_CTX_gettable_params,
EVP_CIPHER_gettable_ctx_params,
EVP_CIPHER_CTX_set_params,
EVP_CIPHER_CTX_settable_params,
EVP_CIPHER_settable_ctx_params,
EVP_CIPHER_CTX_block_size,
EVP_CIPHER_CTX_key_length,
EVP_CIPHER_CTX_iv_length,
@@ -60,12 +63,12 @@ EVP_CIPHER_param_to_asn1,
EVP_CIPHER_asn1_to_param,
EVP_CIPHER_CTX_set_padding,
EVP_enc_null,
EVP_CIPHER_do_all_ex
EVP_CIPHER_do_all_provided
- EVP cipher routines
=head1 SYNOPSIS
=for comment generic
=for openssl generic
#include <openssl/evp.h>
@@ -107,6 +110,9 @@ EVP_CIPHER_do_all_ex
const unsigned char *key, const unsigned char *iv, int enc);
int EVP_CipherFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl);
int EVP_Cipher(EVP_CIPHER_CTX *ctx, unsigned char *out,
const unsigned char *in, unsigned int inl);
int EVP_CIPHER_CTX_set_padding(EVP_CIPHER_CTX *x, int padding);
int EVP_CIPHER_CTX_set_key_length(EVP_CIPHER_CTX *x, int keylen);
int EVP_CIPHER_CTX_ctrl(EVP_CIPHER_CTX *ctx, int type, int arg, void *ptr);
@@ -117,7 +123,11 @@ EVP_CIPHER_do_all_ex
const EVP_CIPHER *EVP_get_cipherbyobj(const ASN1_OBJECT *a);
int EVP_CIPHER_nid(const EVP_CIPHER *e);
int EVP_CIPHER_number(const EVP_CIPHER *e);
int EVP_CIPHER_is_a(const EVP_CIPHER *cipher, const char *name);
void EVP_CIPHER_names_do_all(const EVP_CIPHER *cipher,
void (*fn)(const char *name, void *data),
void *data);
const char *EVP_CIPHER_name(const EVP_CIPHER *cipher);
const OSSL_PROVIDER *EVP_CIPHER_provider(const EVP_CIPHER *cipher);
int EVP_CIPHER_block_size(const EVP_CIPHER *e);
@@ -135,8 +145,8 @@ EVP_CIPHER_do_all_ex
int EVP_CIPHER_CTX_set_params(EVP_CIPHER_CTX *ctx, const OSSL_PARAM params[]);
int EVP_CIPHER_CTX_get_params(EVP_CIPHER_CTX *ctx, OSSL_PARAM params[]);
const OSSL_PARAM *EVP_CIPHER_gettable_params(const EVP_CIPHER *cipher);
const OSSL_PARAM *EVP_CIPHER_CTX_settable_params(const EVP_CIPHER *cipher);
const OSSL_PARAM *EVP_CIPHER_CTX_gettable_params(const EVP_CIPHER *cipher);
const OSSL_PARAM *EVP_CIPHER_settable_ctx_params(const EVP_CIPHER *cipher);
const OSSL_PARAM *EVP_CIPHER_gettable_ctx_params(const EVP_CIPHER *cipher);
int EVP_CIPHER_CTX_block_size(const EVP_CIPHER_CTX *ctx);
int EVP_CIPHER_CTX_key_length(const EVP_CIPHER_CTX *ctx);
int EVP_CIPHER_CTX_iv_length(const EVP_CIPHER_CTX *ctx);
@@ -149,9 +159,9 @@ EVP_CIPHER_do_all_ex
int EVP_CIPHER_param_to_asn1(EVP_CIPHER_CTX *c, ASN1_TYPE *type);
int EVP_CIPHER_asn1_to_param(EVP_CIPHER_CTX *c, ASN1_TYPE *type);
void EVP_CIPHER_do_all_ex(OPENSSL_CTX *libctx,
void (*fn)(EVP_CIPHER *cipher, void *arg),
void *arg);
void EVP_CIPHER_do_all_provided(OPENSSL_CTX *libctx,
void (*fn)(EVP_CIPHER *cipher, void *arg),
void *arg);
=head1 DESCRIPTION
@@ -251,6 +261,15 @@ EVP_CipherFinal_ex(). In previous releases they also cleaned up
the B<ctx>, but this is no longer done and EVP_CIPHER_CTX_clean()
must be called to free any context resources.
EVP_Cipher() encrypts or decrypts a maximum I<inl> amount of bytes from
I<in> and leaves the result in I<out>.
If the cipher doesn't have the flag B<EVP_CIPH_FLAG_CUSTOM_CIPHER> set,
then I<inl> must be a multiple of EVP_CIPHER_block_size(). If it isn't,
the result is undefined. If the cipher has that flag set, then I<inl>
can be any size.
This function is historic and shouldn't be used in an application, please
consider using EVP_CipherUpdate() and EVP_CipherFinal_ex instead.
EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj()
return an EVP_CIPHER structure when passed a cipher name, a NID or an
ASN1_OBJECT structure.
@@ -278,8 +297,8 @@ context B<ctx>.
EVP_CIPHER_CTX_get_params() retrieves the requested list of operation
B<params> from CIPHER context B<ctx>.
EVP_CIPHER_gettable_params(), EVP_CIPHER_CTX_gettable_params(), and
EVP_CIPHER_CTX_settable_params() get a constant B<OSSL_PARAM> array
EVP_CIPHER_gettable_params(), EVP_CIPHER_gettable_ctx_params(), and
EVP_CIPHER_settable_ctx_params() get a constant B<OSSL_PARAM> array
that decribes the retrievable and settable parameters, i.e. parameters
that can be used with EVP_CIPHER_get_params(), EVP_CIPHER_CTX_get_params()
and EVP_CIPHER_CTX_set_params(), respectively.
@@ -317,11 +336,20 @@ IDENTIFIER as such it ignores the cipher parameters and 40 bit RC2 and
identifier or does not have ASN1 support this function will return
B<NID_undef>.
EVP_CIPHER_is_a() returns 1 if the given I<cipher> is an implementation of an
EVP_CIPHER_is_a() returns 1 if I<cipher> is an implementation of an
algorithm that's identifiable with I<name>, otherwise 0.
EVP_CIPHER_number() returns the internal dynamic number assigned to
the I<cipher>. This is only useful with fetched B<EVP_CIPHER>s.
EVP_CIPHER_name() and EVP_CIPHER_CTX_name() return the name of the passed
cipher or context.
cipher or context. For fetched ciphers with multiple names, only one
of them is returned; it's recommended to use EVP_CIPHER_names_do_all()
instead.
EVP_CIPHER_names_do_all() traverses all names for the I<cipher>, and
calls I<fn> with each name and I<data>. This is only useful with
fetched B<EVP_CIPHER>s.
EVP_CIPHER_provider() returns an B<OSSL_PROVIDER> pointer to the provider
that implements the given B<EVP_CIPHER>.
@@ -364,7 +392,7 @@ based on the cipher context. The EVP_CIPHER can provide its own random key
generation routine to support keys of a specific form. B<Key> must point to a
buffer at least as big as the value returned by EVP_CIPHER_CTX_key_length().
EVP_CIPHER_do_all_ex() traverses all ciphers implemented by all activated
EVP_CIPHER_do_all_provided() traverses all ciphers implemented by all activated
providers in the given library context I<libctx>, and for each of the
implementations, calls the given function I<fn> with the implementation method
and the given I<arg> as argument.
@@ -388,6 +416,11 @@ EVP_DecryptFinal_ex() returns 0 if the decrypt failed or 1 for success.
EVP_CipherInit_ex() and EVP_CipherUpdate() return 1 for success and 0 for failure.
EVP_CipherFinal_ex() returns 0 for a decryption failure or 1 for success.
EVP_Cipher() returns the amount of encrypted / decrypted bytes, or -1
on failure, if the flag B<EVP_CIPH_FLAG_CUSTOM_CIPHER> is set for the
cipher. EVP_Cipher() returns 1 on success or 0 on failure, if the flag
B<EVP_CIPH_FLAG_CUSTOM_CIPHER> is not set for the cipher.
EVP_CIPHER_CTX_reset() returns 1 for success and 0 for failure.
EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj()
doc/man3/EVP_KDF.pod
+48 -42
View File
@@ -2,12 +2,13 @@
=head1 NAME
EVP_KDF, EVP_KDF_fetch, EVP_KDF_free, EVP_KDF_provider, EVP_KDF_up_ref,
EVP_KDF_name,
EVP_KDF_CTX, EVP_KDF_CTX_new, EVP_KDF_CTX_free, EVP_KDF_CTX_kdf,
EVP_KDF_reset, EVP_KDF_size, EVP_KDF_derive, EVP_KDF_CTX_dup,
EVP_KDF_CTX_get_params, EVP_KDF_CTX_set_params, EVP_KDF_do_all_ex,
EVP_KDF_get_params, EVP_KDF_CTX_gettable_params, EVP_KDF_CTX_settable_params,
EVP_KDF, EVP_KDF_fetch, EVP_KDF_free, EVP_KDF_up_ref,
EVP_KDF_CTX, EVP_KDF_CTX_new, EVP_KDF_CTX_free, EVP_KDF_CTX_dup,
EVP_KDF_reset, EVP_KDF_derive,
EVP_KDF_size, EVP_KDF_provider, EVP_KDF_CTX_kdf, EVP_KDF_is_a,
EVP_KDF_number, EVP_KDF_names_do_all,
EVP_KDF_CTX_get_params, EVP_KDF_CTX_set_params, EVP_KDF_do_all_provided,
EVP_KDF_get_params, EVP_KDF_gettable_ctx_params, EVP_KDF_settable_ctx_params,
EVP_KDF_gettable_params - EVP KDF routines
=head1 SYNOPSIS
@@ -24,20 +25,25 @@ EVP_KDF_gettable_params - EVP KDF routines
void EVP_KDF_reset(EVP_KDF_CTX *ctx);
size_t EVP_KDF_size(EVP_KDF_CTX *ctx);
int EVP_KDF_derive(EVP_KDF_CTX *ctx, unsigned char *key, size_t keylen);
const char *EVP_KDF_name(const EVP_KDF *kdf);
int EVP_KDF_up_ref(EVP_KDF *kdf);
void EVP_KDF_free(EVP_KDF *kdf);
EVP_KDF *EVP_KDF_fetch(OPENSSL_CTX *libctx, const char *algorithm,
const char *properties);
void EVP_KDF_do_all_ex(OPENSSL_CTX *libctx,
void (*fn)(EVP_KDF *kdf, void *arg),
void *arg);
int EVP_KDF_number(const EVP_KDF *kdf);
int EVP_KDF_is_a(const EVP_KDF *kdf, const char *name);
const OSSL_PROVIDER *EVP_KDF_provider(const EVP_KDF *kdf);
void EVP_KDF_do_all_provided(OPENSSL_CTX *libctx,
void (*fn)(EVP_KDF *kdf, void *arg),
void *arg);
void EVP_KDF_names_do_all(const EVP_KDF *kdf,
void (*fn)(const char *name, void *data),
void *data);
int EVP_KDF_get_params(EVP_KDF *kdf, OSSL_PARAM params[]);
int EVP_KDF_CTX_get_params(EVP_KDF_CTX *ctx, OSSL_PARAM params[]);
int EVP_KDF_CTX_set_params(EVP_KDF_CTX *ctx, const OSSL_PARAM params[]);
const OSSL_PARAM *EVP_KDF_gettable_params(const EVP_KDF *kdf);
const OSSL_PARAM *EVP_KDF_CTX_gettable_params(const EVP_KDF *kdf);
const OSSL_PARAM *EVP_KDF_CTX_settable_params(const EVP_KDF *kdf);
const OSSL_PARAM *EVP_KDF_gettable_ctx_params(const EVP_KDF *kdf);
const OSSL_PARAM *EVP_KDF_settable_ctx_params(const EVP_KDF *kdf);
const OSSL_PROVIDER *EVP_KDF_provider(const EVP_KDF *kdf);
=head1 DESCRIPTION
@@ -75,7 +81,7 @@ NULL is a valid parameter, for which this function is a no-op.
EVP_KDF_CTX_new() creates a new context for the KDF implementation I<kdf>.
EVP_KDF_CTX_free() frees up the context C<ctx>. If I<ctx> is NULL, nothing
EVP_KDF_CTX_free() frees up the context I<ctx>. If I<ctx> is NULL, nothing
is done.
EVP_KDF_CTX_kdf() returns the B<EVP_KDF> associated with the context
@@ -86,9 +92,9 @@ I<ctx>.
EVP_KDF_reset() resets the context to the default state as if the context
had just been created.
EVP_KDF_derive() derives C<keylen> bytes of key material and places it in the
EVP_KDF_derive() derives I<keylen> bytes of key material and places it in the
I<key> buffer. If the algorithm produces a fixed amount of output then an
error will occur unless the C<keylen> parameter is equal to that output size,
error will occur unless the I<keylen> parameter is equal to that output size,
as returned by EVP_KDF_size().
EVP_KDF_get_params() retrieves details about the implementation
@@ -114,8 +120,8 @@ simply ignored.
Also, what happens when a needed parameter isn't passed down is
defined by the implementation.
EVP_KDF_gettable_params(), EVP_KDF_CTX_gettable_params() and
EVP_KDF_CTX_settable_params() get a constant B<OSSL_PARAM> array that
EVP_KDF_gettable_params(), EVP_KDF_gettable_ctx_params() and
EVP_KDF_settable_ctx_params() get a constant B<OSSL_PARAM> array that
decribes the retrievable and settable parameters, i.e. parameters that
can be used with EVP_KDF_get_params(), EVP_KDF_CTX_get_params()
and EVP_KDF_CTX_set_params(), respectively.
@@ -128,35 +134,42 @@ of output and B<SIZE_MAX> otherwise. If an error occurs then 0 is returned.
For some algorithms an error may result if input parameters necessary to
calculate a fixed output size have not yet been supplied.
EVP_KDF_name() returns the name of the given KDF implementation.
EVP_KDF_is_a() returns 1 if I<kdf> is an implementation of an
algorithm that's identifiable with I<name>, otherwise 0.
EVP_KDF_provider() returns the provider that holds the implementation
of the given I<kdf>.
EVP_KDF_do_all_ex() traverses all KDF implemented by all activated
EVP_KDF_do_all_provided() traverses all KDF implemented by all activated
providers in the given library context I<libctx>, and for each of the
implementations, calls the given function I<fn> with the implementation method
and the given I<arg> as argument.
EVP_KDF_number() returns the internal dynamic number assigned to
I<kdf>.
EVP_KDF_names_do_all() traverses all names for I<kdf>, and calls
I<fn> with each name and I<data>.
=head1 PARAMETERS
The standard parameter names are:
=over 4
=item B<OSSL_KDF_PARAM_PASSWORD> ("pass") <octet string>
=item "pass" (B<OSSL_KDF_PARAM_PASSWORD>) <octet string>
Some KDF implementations require a password.
For those KDF implementations that support it, this parameter sets the password.
=item B<OSSL_KDF_PARAM_SALT> ("salt") <octet string>
=item "salt" (B<OSSL_KDF_PARAM_SALT>) <octet string>
Some KDF implementations can take a salt.
For those KDF implementations that support it, this parameter sets the salt.
The default value, if any, is implementation dependent.
=item B<OSSL_KDF_PARAM_ITER> ("iter") <unsigned integer>
=item "iter" (B<OSSL_KDF_PARAM_ITER>) <unsigned integer>
Some KDF implementations require an iteration count.
For those KDF implementations that support it, this parameter sets the
@@ -164,32 +177,28 @@ iteration count.
The default value, if any, is implementation dependent.
=item B<OSSL_KDF_PARAM_PROPERTIES> ("properties") <UTF8 string>
=item "properties" (B<OSSL_KDF_PARAM_PROPERTIES>) <UTF8 string>
=item B<OSSL_KDF_PARAM_MAC> ("mac") <UTF8 string>
=item "mac" (B<OSSL_KDF_PARAM_MAC>) <UTF8 string>
=item B<OSSL_KDF_PARAM_DIGEST> ("digest") <UTF8 string>
=item B<OSSL_MAC_PARAM_ENGINE> ("engine") <UTF8 string>
=item "digest" (B<OSSL_KDF_PARAM_DIGEST>) <UTF8 string>
For KDF implementations that use an underlying computation MAC or
digest, these parameters set what the algorithm should be, and the
engine that implements the algorithm or the properties to fetch it
by if needed.
digest, these parameters set what the algorithm should be.
The value is always the name of the intended engine, algorithm,
The value is always the name of the intended algorithm,
or the properties.
Note that not all algorithms may support all possible underlying
implementations.
=item B<OSSL_KDF_PARAM_KEY> ("key") <octet string>
=item "key" (B<OSSL_KDF_PARAM_KEY>) <octet string>
Some KDF implementations require a key.
For those KDF implementations that support it, this octet string parameter
sets the key.
=item B<OSSL_KDF_PARAM_MAC_SIZE> ("maclen") <unsigned integer>
=item "maclen" (B<OSSL_KDF_PARAM_MAC_SIZE>) <unsigned integer>
Used by implementations that use a MAC with a variable output size (KMAC).
For those KDF implementations that support it, this parameter
@@ -198,11 +207,11 @@ sets the MAC output size.
The default value, if any, is implementation dependent.
The length must never exceed what can be given with a B<size_t>.
=item B<OSSL_KDF_PARAM_SCRYPT_MAXMEM> ("macmaxmem_byteslen") <unsigned integer>
=item "maxmem_bytes" (B<OSSL_KDF_PARAM_SCRYPT_MAXMEM>) <unsigned integer>
Memory-hard password-based KDF algorithms, such as scrypt, use an amount of
memory that depends on the load factors provided as input.
For those KDF implementations that support it, this uint64_t parameter sets
For those KDF implementations that support it, this B<uint64_t> parameter sets
an upper limit on the amount of memory that may be consumed while performing
a key derivation.
If this memory usage limit is exceeded because the load factors are chosen
@@ -215,23 +224,20 @@ The memory size must never exceed what can be given with a B<size_t>.
=head1 RETURN VALUES
EVP_MAC_fetch() returns a pointer to a newly fetched B<EVP_KDF>, or
EVP_KDF_fetch() returns a pointer to a newly fetched B<EVP_KDF>, or
NULL if allocation failed.
EVP_KDF_name() returns the name for the given I<kdf>, if it has been
added to the object database.
EVP_KDF_provider() returns a pointer to the provider for the KDF, or
NULL on error.
EVP_MAC_up_ref() returns 1 on success, 0 on error.
EVP_KDF_up_ref() returns 1 on success, 0 on error.
EVP_KDF_CTX_new() returns either the newly allocated
C<EVP_KDF_CTX> structure or C<NULL> if an error occurred.
B<EVP_KDF_CTX> structure or NULL if an error occurred.
EVP_KDF_CTX_free() and EVP_KDF_reset() do not return a value.
EVP_KDF_size() returns the output size. C<SIZE_MAX> is returned to indicate
EVP_KDF_size() returns the output size. B<SIZE_MAX> is returned to indicate
that the algorithm produces a variable amount of output; 0 to indicate failure.
The remaining functions return 1 for success and 0 or a negative value for
doc/man3/EVP_KEYEXCH_free.pod
+33 -4
View File
@@ -2,7 +2,9 @@
=head1 NAME
EVP_KEYEXCH_fetch, EVP_KEYEXCH_free, EVP_KEYEXCH_up_ref, EVP_KEYEXCH_provider
EVP_KEYEXCH_fetch, EVP_KEYEXCH_free, EVP_KEYEXCH_up_ref, EVP_KEYEXCH_provider,
EVP_KEYEXCH_is_a, EVP_KEYEXCH_do_all_provided,
EVP_KEYEXCH_number, EVP_KEYEXCH_names_do_all
- Functions to manage EVP_KEYEXCH algorithm objects
=head1 SYNOPSIS
@@ -14,12 +16,20 @@ EVP_KEYEXCH_fetch, EVP_KEYEXCH_free, EVP_KEYEXCH_up_ref, EVP_KEYEXCH_provider
void EVP_KEYEXCH_free(EVP_KEYEXCH *exchange);
int EVP_KEYEXCH_up_ref(EVP_KEYEXCH *exchange);
OSSL_PROVIDER *EVP_KEYEXCH_provider(const EVP_KEYEXCH *exchange);
int EVP_KEYEXCH_is_a(const EVP_KEYEXCH *exchange, const char *name);
int EVP_KEYEXCH_number(const EVP_KEYEXCH *exchange);
void EVP_KEYEXCH_do_all_provided(OPENSSL_CTX *libctx,
void (*fn)(EVP_KEYEXCH *exchange, void *arg),
void *arg);
void EVP_KEYEXCH_names_do_all(const EVP_KEYEXCH *exchange,
void (*fn)(const char *name, void *data),
void *data);
=head1 DESCRIPTION
EVP_KEYEXCH_fetch() fetches the key exchange implementation for the given
B<algorithm> from any provider offering it, within the criteria given
by the B<properties>.
I<algorithm> from any provider offering it, within the criteria given
by the I<properties>.
See L<provider(7)/Fetching algorithms> for further information.
The returned value must eventually be freed with EVP_KEYEXCH_free().
@@ -34,13 +44,32 @@ structure.
EVP_KEYEXCH_provider() returns the provider that I<exchange> was fetched from.
EVP_KEYEXCH_is_a() checks if I<exchange> is an implementation of an
algorithm that's identifiable with I<name>.
EVP_KEYEXCH_number() returns the internal dynamic number assigned to
the I<exchange>.
EVP_KEYEXCH_names_do_all() traverses all names for the I<exchange>, and
calls I<fn> with each name and I<data>.
EVP_KEYEXCH_do_all_provided() traverses all key exchange implementations by
all activated providers in the library context I<libctx>, and for each
of the implementations, calls I<fn> with the implementation method and
I<data> as arguments.
=head1 RETURN VALUES
EVP_KEYEXCH_fetch() returns a pointer to a B<EVP_KEYEXCH> for success
or B<NULL> for failure.
or NULL for failure.
EVP_KEYEXCH_up_ref() returns 1 for success or 0 otherwise.
EVP_KEYEXCH_is_a() returns 1 of I<exchange> was identifiable,
otherwise 0.
EVP_KEYEXCH_number() returns an integer.
=head1 SEE ALSO
L<provider(7)/Fetching algorithms>, L<OSSL_PROVIDER(3)>
doc/man3/EVP_KEYMGMT.pod
+32 -1
View File
@@ -6,7 +6,11 @@ EVP_KEYMGMT,
EVP_KEYMGMT_fetch,
EVP_KEYMGMT_up_ref,
EVP_KEYMGMT_free,
EVP_KEYMGMT_provider
EVP_KEYMGMT_provider,
EVP_KEYMGMT_is_a,
EVP_KEYMGMT_number,
EVP_KEYMGMT_do_all_provided,
EVP_KEYMGMT_names_do_all
- EVP key management routines
=head1 SYNOPSIS
@@ -20,6 +24,14 @@ EVP_KEYMGMT_provider
int EVP_KEYMGMT_up_ref(EVP_KEYMGMT *keymgmt);
void EVP_KEYMGMT_free(EVP_KEYMGMT *keymgmt);
const OSSL_PROVIDER *EVP_KEYMGMT_provider(const EVP_KEYMGMT *keymgmt);
int EVP_KEYMGMT_is_a(const EVP_KEYMGMT *keymgmt, const char *name);
int EVP_KEYMGMT_number(const EVP_KEYMGMT *keymgmt);
void EVP_KEYMGMT_do_all_provided(OPENSSL_CTX *libctx,
void (*fn)(EVP_KEYMGMT *keymgmt, void *arg),
void *arg);
void EVP_KEYMGMT_names_do_all(const EVP_KEYMGMT *keymgmt,
void (*fn)(const char *name, void *data),
void *data);
=head1 DESCRIPTION
@@ -45,6 +57,20 @@ B<EVP_KEYMGMT> I<keymgmt>, and when the count reaches zero, frees it.
EVP_KEYMGMT_provider() returns the provider that has this particular
implementation.
EVP_KEYMGMT_is_a() checks if I<keymgmt> is an implementation of an
algorithm that's identifiable with I<name>.
EVP_KEYMGMT_number() returns the internal dynamic number assigned to
the I<keymgmt>.
EVP_KEYMGMT_names_do_all() traverses all names for the I<keymgmt>, and
calls I<fn> with each name and I<data>.
EVP_KEYMGMT_do_all_provided() traverses all key keymgmt implementations by
all activated providers in the library context I<libctx>, and for each
of the implementations, calls I<fn> with the implementation method and
I<data> as arguments.
=head1 NOTES
EVP_KEYMGMT_fetch() may be called implicitly by other fetching
@@ -64,6 +90,11 @@ EVP_KEYMGMT_free() doesn't return any value.
EVP_KEYMGMT_provider() returns a pointer to a provider object, or NULL
on error.
EVP_KEYMGMT_is_a() returns 1 of I<keymgmt> was identifiable,
otherwise 0.
EVP_KEYMGMT_number() returns an integer.
=head1 SEE ALSO
L<EVP_MD_fetch(3)>, L<OPENSSL_CTX(3)>
doc/man3/EVP_MAC.pod
+36 -36
View File
@@ -3,13 +3,13 @@
=head1 NAME
EVP_MAC, EVP_MAC_fetch, EVP_MAC_up_ref, EVP_MAC_free,
EVP_MAC_is_a, EVP_MAC_name,
EVP_MAC_is_a, EVP_MAC_number, EVP_MAC_names_do_all,
EVP_MAC_provider, EVP_MAC_get_params, EVP_MAC_gettable_params,
EVP_MAC_CTX, EVP_MAC_CTX_new, EVP_MAC_CTX_free, EVP_MAC_CTX_dup,
EVP_MAC_CTX_mac, EVP_MAC_CTX_get_params, EVP_MAC_CTX_set_params,
EVP_MAC_size, EVP_MAC_init, EVP_MAC_update, EVP_MAC_final,
EVP_MAC_CTX_gettable_params, EVP_MAC_CTX_settable_params,
EVP_MAC_do_all_ex - EVP MAC routines
EVP_MAC_gettable_ctx_params, EVP_MAC_settable_ctx_params,
EVP_MAC_do_all_provided - EVP MAC routines
=head1 SYNOPSIS
@@ -23,7 +23,10 @@ EVP_MAC_do_all_ex - EVP MAC routines
int EVP_MAC_up_ref(EVP_MAC *mac);
void EVP_MAC_free(EVP_MAC *mac);
int EVP_MAC_is_a(const EVP_MAC *mac, const char *name);
const char *EVP_MAC_name(const EVP_MAC *mac);
int EVP_MAC_number(const EVP_MAC *mac);
void EVP_MAC_names_do_all(const EVP_MAC *mac,
void (*fn)(const char *name, void *data),
void *data);
const OSSL_PROVIDER *EVP_MAC_provider(const EVP_MAC *mac);
int EVP_MAC_get_params(EVP_MAC *mac, OSSL_PARAM params[]);
@@ -41,12 +44,12 @@ EVP_MAC_do_all_ex - EVP MAC routines
unsigned char *out, size_t *outl, size_t outsize);
const OSSL_PARAM *EVP_MAC_gettable_params(const EVP_MAC *mac);
const OSSL_PARAM *EVP_MAC_CTX_gettable_params(const EVP_MAC *mac);
const OSSL_PARAM *EVP_MAC_CTX_settable_params(const EVP_MAC *mac);
const OSSL_PARAM *EVP_MAC_gettable_ctx_params(const EVP_MAC *mac);
const OSSL_PARAM *EVP_MAC_settable_ctx_params(const EVP_MAC *mac);
void EVP_MAC_do_all_ex(OPENSSL_CTX *libctx,
void (*fn)(EVP_MAC *mac, void *arg),
void *arg);
void EVP_MAC_do_all_provided(OPENSSL_CTX *libctx,
void (*fn)(EVP_MAC *mac, void *arg),
void *arg);
=head1 DESCRIPTION
@@ -116,10 +119,10 @@ EVP_MAC_update() adds I<datalen> bytes from I<data> to the MAC input.
EVP_MAC_final() does the final computation and stores the result in
the memory pointed at by I<out> of size I<outsize>, and sets the number
of bytes written in I<*outl> at.
If I<out> is B<NULL> or I<outsize> is too small, then no computation
If I<out> is NULL or I<outsize> is too small, then no computation
is made.
To figure out what the output length will be and allocate space for it
dynamically, simply call with I<out> being B<NULL> and I<outl>
dynamically, simply call with I<out> being NULL and I<outl>
pointing at a valid location, then allocate space and make a second
call with I<out> pointing at the allocated space.
@@ -146,8 +149,8 @@ simply ignored.
Also, what happens when a needed parameter isn't passed down is
defined by the implementation.
EVP_MAC_gettable_params(), EVP_MAC_CTX_gettable_params() and
EVP_MAC_CTX_settable_params() get a constant B<OSSL_PARAM> array that
EVP_MAC_gettable_params(), EVP_MAC_gettable_ctx_params() and
EVP_MAC_settable_ctx_params() get a constant B<OSSL_PARAM> array that
decribes the retrievable and settable parameters, i.e. parameters that
can be used with EVP_MAC_get_params(), EVP_MAC_CTX_get_params()
and EVP_MAC_CTX_set_params(), respectively.
@@ -157,19 +160,23 @@ See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor.
EVP_MAC_size() returns the MAC output size for the given context.
EVP_MAC_name() returns the name of the given MAC implementation.
EVP_MAC_is_a() checks if the given I<mac> is an implementation of an
algorithm that's identifiable with I<name>.
EVP_MAC_provider() returns the provider that holds the implementation
of the given I<mac>.
EVP_MAC_do_all_ex() traverses all MAC implemented by all activated
EVP_MAC_do_all_provided() traverses all MAC implemented by all activated
providers in the given library context I<libctx>, and for each of the
implementations, calls the given function I<fn> with the implementation method
and the given I<arg> as argument.
EVP_MAC_number() returns the internal dynamic number assigned to
I<mac>.
EVP_MAC_names_do_all() traverses all names for I<mac>, and calls
I<fn> with each name and I<data>.
=head1 PARAMETERS
Parameters are identified by name as strings, and have an expected
@@ -183,59 +190,55 @@ The standard parameter names are:
=over 4
=item B<OSSL_MAC_PARAM_KEY> ("key") <octet string>
=item "key" (B<OSSL_MAC_PARAM_KEY>) <octet string>
Its value is the MAC key as an array of bytes.
For MACs that use an underlying computation algorithm, the algorithm
must be set first, see parameter names "algorithm" below.
=item B<OSSL_MAC_PARAM_IV> ("iv") <octet string>
=item "iv" (B<OSSL_MAC_PARAM_IV>) <octet string>
Some MAC implementations require an IV, this parameter sets the IV.
=item B<OSSL_MAC_PARAM_CUSTOM> ("custom") <octet string>
=item "custom" (B<OSSL_MAC_PARAM_CUSTOM>) <octet string>
Some MAC implementations (KMAC, BLAKE2) accept a Customization String,
this parameter sets the Customization String. The default value is the
empty string.
=item B<OSSL_MAC_PARAM_SALT> ("salt") <octet string>
=item "salt" (B<OSSL_MAC_PARAM_SALT>) <octet string>
This option is used by BLAKE2 MAC.
=item B<OSSL_MAC_PARAM_XOF> ("xof") <integer>
=item "xof" (B<OSSL_MAC_PARAM_XOF>) <integer>
It's a simple flag, the value 0 or 1 are expected.
This option is used by KMAC.
=item B<OSSL_MAC_PARAM_FLAGS> ("flags") <integer>
=item "flags" (B<OSSL_MAC_PARAM_FLAGS>) <integer>
These will set the MAC flags to the given numbers.
Some MACs do not support this option.
=item B<OSSL_MAC_PARAM_ENGINE> ("engine") <UTF8 string>
=item "properties" (B<OSSL_MAC_PARAM_PROPERTIES>) <UTF8 string>
=item B<OSSL_MAC_PARAM_PROPERTIES> ("properties") <UTF8 string>
=item "digest" (B<OSSL_MAC_PARAM_DIGEST>) <UTF8 string>
=item B<OSSL_MAC_PARAM_DIGEST> ("digest") <UTF8 string>
=item B<OSSL_MAC_PARAM_CIPHER> ("cipher") <UTF8 string>
=item "cipher" (B<OSSL_MAC_PARAM_CIPHER>) <UTF8 string>
For MAC implementations that use an underlying computation cipher or
digest, these parameters set what the algorithm should be, and the
engine that implements the algorithm or the properties to fetch it
by if needed.
digest, these parameters set what the algorithm should be.
The value is always the name of the intended engine, algorithm,
The value is always the name of the intended algorithm,
or the properties.
Note that not all algorithms may support all digests.
HMAC does not support variable output length digests such as SHAKE128
or SHAKE256.
=item B<OSSL_MAC_PARAM_SIZE> ("size") <unsigned integer>
=item "size" (B<OSSL_MAC_PARAM_SIZE>) <unsigned integer>
For MAC implementations that support it, set the output size that
EVP_MAC_final() should produce.
@@ -258,9 +261,6 @@ EVP_MAC_up_ref() returns 1 on success, 0 on error.
EVP_MAC_free() returns nothing at all.
EVP_MAC_name() returns the name of the MAC, or NULL if NULL was
passed.
EVP_MAC_is_a() returns 1 if the given method can be identified with
the given name, otherwise 0.
@@ -282,7 +282,7 @@ EVP_MAC_size() returns the expected output size, or 0 if it isn't
set.
If it isn't set, a call to EVP_MAC_init() should get it set.
EVP_MAC_do_all_ex() returns nothing at all.
EVP_MAC_do_all_provided() returns nothing at all.
=head1 EXAMPLES
doc/man3/EVP_PKEY_CTX_ctrl.pod
+6 -5
View File
@@ -163,23 +163,24 @@ The parameters currently supported by the default provider are:
=over 4
=item "pad" (B<OSSL_EXCHANGE_PARAM_PAD>) <uint>
=item "pad" (B<OSSL_EXCHANGE_PARAM_PAD>) <unsigned integer>
Sets the DH padding mode.
If B<OSSL_EXCHANGE_PARAM_PAD> is 1 then the shared secret is padded with zeroes
If B<OSSL_EXCHANGE_PARAM_PAD> is 1 then the shared secret is padded with zeros
up to the size of the DH prime B<p>.
If B<OSSL_EXCHANGE_PARAM_PAD> is zero (the default) then no padding is
performed.
=item "digest" (B<OSSL_SIGNATURE_PARAM_DIGEST>) <utf8 string>
=item "digest" (B<OSSL_SIGNATURE_PARAM_DIGEST>) <UTF8 string>
Gets and sets the name of the digest algorithm used for the input to the
signature functions.
=item "digest-size" (B<OSSL_SIGNATURE_PARAM_DIGEST_SIZE>) <size_t>
=item "digest-size" (B<OSSL_SIGNATURE_PARAM_DIGEST_SIZE>) <unsigned integer>
Gets and sets the output size of the digest algorithm used for the input to the
signature functions.
The length of the "digest-size" parameter should not exceed that of a B<size_t>.
The internal algorithm that supports this parameter is DSA.
=back
@@ -344,7 +345,7 @@ parameter generation. Use 0 for PKCS#3 DH and 1 for X9.42 DH.
The default is 0.
The EVP_PKEY_CTX_set_dh_pad() function sets the DH padding mode.
If B<pad> is 1 the shared secret is padded with zeroes up to the size of the DH
If B<pad> is 1 the shared secret is padded with zeros up to the size of the DH
prime B<p>.
If B<pad> is zero (the default) then no padding is performed.
doc/man3/EVP_PKEY_CTX_new.pod
+21 -8
View File
@@ -2,7 +2,9 @@
=head1 NAME
EVP_PKEY_CTX_new, EVP_PKEY_CTX_new_id, EVP_PKEY_CTX_dup, EVP_PKEY_CTX_free - public key algorithm context functions
EVP_PKEY_CTX_new, EVP_PKEY_CTX_new_id, EVP_PKEY_CTX_new_provided,
EVP_PKEY_CTX_dup, EVP_PKEY_CTX_free
- public key algorithm context functions
=head1 SYNOPSIS
@@ -10,23 +12,34 @@ EVP_PKEY_CTX_new, EVP_PKEY_CTX_new_id, EVP_PKEY_CTX_dup, EVP_PKEY_CTX_free - pub
EVP_PKEY_CTX *EVP_PKEY_CTX_new(EVP_PKEY *pkey, ENGINE *e);
EVP_PKEY_CTX *EVP_PKEY_CTX_new_id(int id, ENGINE *e);
EVP_PKEY_CTX *EVP_PKEY_CTX_new_provided(const char *name,
const char *propquery);
EVP_PKEY_CTX *EVP_PKEY_CTX_dup(const EVP_PKEY_CTX *ctx);
void EVP_PKEY_CTX_free(EVP_PKEY_CTX *ctx);
=head1 DESCRIPTION
The EVP_PKEY_CTX_new() function allocates public key algorithm context using
the algorithm specified in B<pkey> and ENGINE B<e>.
the algorithm specified in I<pkey> and ENGINE I<e>.
The EVP_PKEY_CTX_new_id() function allocates public key algorithm context
using the algorithm specified by B<id> and ENGINE B<e>. It is normally used
when no B<EVP_PKEY> structure is associated with the operations, for example
during parameter generation of key generation for some algorithms.
using the algorithm specified by I<id> and ENGINE I<e>.
EVP_PKEY_CTX_dup() duplicates the context B<ctx>.
The EVP_PKEY_CTX_new_provided() function allocates a public key
algorithm context using the algorithm specified by I<name> and the
property query I<propquery>. The strings aren't duplicated, so they
must remain unchanged for the lifetime of the returned B<EVP_PKEY_CTX>
or of any of its duplicates.
EVP_PKEY_CTX_free() frees up the context B<ctx>.
If B<ctx> is NULL, nothing is done.
EVP_PKEY_CTX_new_id() and EVP_PKEY_CTX_new_provided() are normally
used when no B<EVP_PKEY> structure is associated with the operations,
for example during parameter generation or key generation for some
algorithms.
EVP_PKEY_CTX_dup() duplicates the context I<ctx>.
EVP_PKEY_CTX_free() frees up the context I<ctx>.
If I<ctx> is NULL, nothing is done.
=head1 NOTES
doc/man3/EVP_SIGNATURE_free.pod
+25 -1
View File
@@ -3,7 +3,8 @@
=head1 NAME
EVP_SIGNATURE_fetch, EVP_SIGNATURE_free, EVP_SIGNATURE_up_ref,
EVP_SIGNATURE_provider
EVP_SIGNATURE_number, EVP_SIGNATURE_is_a, EVP_SIGNATURE_provider,
EVP_SIGNATURE_do_all_provided, EVP_SIGNATURE_names_do_all
- Functions to manage EVP_SIGNATURE algorithm objects
=head1 SYNOPSIS
@@ -14,7 +15,16 @@ EVP_SIGNATURE_provider
const char *properties);
void EVP_SIGNATURE_free(EVP_SIGNATURE *signature);
int EVP_SIGNATURE_up_ref(EVP_SIGNATURE *signature);
int EVP_SIGNATURE_number(const EVP_SIGNATURE *signature);
int EVP_SIGNATURE_is_a(const EVP_SIGNATURE *signature, const char *name);
OSSL_PROVIDER *EVP_SIGNATURE_provider(const EVP_SIGNATURE *signature);
void EVP_SIGNATURE_do_all_provided(OPENSSL_CTX *libctx,
void (*fn)(EVP_SIGNATURE *signature,
void *arg),
void *arg);
void EVP_SIGNATURE_names_do_all(const EVP_SIGNATURE *signature,
void (*fn)(const char *name, void *data),
void *data);
=head1 DESCRIPTION
@@ -35,8 +45,22 @@ structure is freed.
EVP_SIGNATURE_up_ref() increments the reference count for an B<EVP_SIGNATURE>
structure.
EVP_SIGNATURE_is_a() returns 1 if I<signature> is an implementation of an
algorithm that's identifiable with I<name>, otherwise 0.
EVP_SIGNATURE_provider() returns the provider that I<signature> was fetched from.
EVP_SIGNATURE_do_all_provided() traverses all SIGNATURE implemented by all
activated roviders in the given library context I<libctx>, and for each of the
implementations, calls the given function I<fn> with the implementation method
and the given I<arg> as argument.
EVP_SIGNATURE_number() returns the internal dynamic number assigned to
I<signature>.
EVP_SIGNATURE_names_do_all() traverses all names for I<signature>, and calls
I<fn> with each name and I<data>.
=head1 RETURN VALUES
EVP_SIGNATURE_fetch() returns a pointer to an B<EVP_SIGNATURE> for success
doc/man3/EVP_aes.pod
+1 -1
View File
@@ -51,7 +51,7 @@ EVP_aes_256_xts
=head1 SYNOPSIS
=for comment generic
=for openssl generic
#include <openssl/evp.h>
doc/man3/EVP_aria.pod
+1 -1
View File
@@ -36,7 +36,7 @@ EVP_aria_256_gcm,
=head1 SYNOPSIS
=for comment generic
=for openssl generic
#include <openssl/evp.h>
doc/man3/EVP_camellia.pod
+1 -1
View File
@@ -30,7 +30,7 @@ EVP_camellia_256_ofb
=head1 SYNOPSIS
=for comment generic
=for openssl generic
#include <openssl/evp.h>
doc/man3/EVP_des.pod
+1 -1
View File
@@ -28,7 +28,7 @@ EVP_des_ede3_wrap
=head1 SYNOPSIS
=for comment generic
=for openssl generic
#include <openssl/evp.h>
doc/man3/HMAC.pod
+1 -1
View File
@@ -69,7 +69,7 @@ EVP_shake256().
HMAC_CTX_new() creates a new HMAC_CTX in heap memory.
HMAC_CTX_reset() zeroes an existing B<HMAC_CTX> and associated
HMAC_CTX_reset() clears an existing B<HMAC_CTX> and associated
resources, making it suitable for new computations as if it was newly
created with HMAC_CTX_new().
doc/man3/OCSP_cert_to_id.pod
+1 -1
View File
@@ -52,7 +52,7 @@ corresponding parameter can be set to B<NULL>.
OCSP_cert_to_id() and OCSP_cert_id_new() return either a pointer to a valid
B<OCSP_CERTID> structure or B<NULL> if an error occurred.
OCSP_id_cmp() and OCSP_id_issuer_cmp() returns zero for a match and non-zero
OCSP_id_cmp() and OCSP_id_issuer_cmp() returns zero for a match and nonzero
otherwise.
OCSP_CERTID_free() does not return a value.
doc/man3/OCSP_request_add1_nonce.pod
+1 -1
View File
@@ -57,7 +57,7 @@ performance reasons. As a result they do not support nonces.
The return values of OCSP_check_nonce() can be checked to cover each case. A
positive return value effectively indicates success: nonces are both present
and match, both absent or present in the response only. A non-zero return
and match, both absent or present in the response only. A nonzero return
additionally covers the case where the nonce is present in the request only:
this will happen if the responder doesn't support nonces. A zero return value
indicates present and mismatched nonces: this should be treated as an error
doc/man3/OCSP_resp_find_status.pod
+2 -2
View File
@@ -112,7 +112,7 @@ no freeing of the results is necessary.
OCSP_check_validity() checks the validity of B<thisupd> and B<nextupd> values
which will be typically obtained from OCSP_resp_find_status() or
OCSP_single_get0_status(). If B<sec> is non-zero it indicates how many seconds
OCSP_single_get0_status(). If B<sec> is nonzero it indicates how many seconds
leeway should be allowed in the check. If B<maxsec> is positive it indicates
the maximum age of B<thisupd> in seconds.
@@ -167,7 +167,7 @@ can then take appropriate action based on the status of the certificate.
An OCSP response for a certificate contains B<thisUpdate> and B<nextUpdate>
fields. Normally the current time should be between these two values. To
account for clock skew the B<maxsec> field can be set to non-zero in
account for clock skew the B<maxsec> field can be set to nonzero in
OCSP_check_validity(). Some responders do not set the B<nextUpdate> field, this
would otherwise mean an ancient response would be considered valid: the
B<maxsec> parameter to OCSP_check_validity() can be used to limit the permitted
doc/man3/OPENSSL_LH_COMPFUNC.pod
+38 -38
View File
@@ -12,7 +12,7 @@ lh_TYPE_doall, lh_TYPE_doall_arg, lh_TYPE_error - dynamic hash table
=head1 SYNOPSIS
=for comment generic
=for openssl generic
#include <openssl/lhash.h>
@@ -41,25 +41,25 @@ lh_TYPE_doall, lh_TYPE_doall_arg, lh_TYPE_error - dynamic hash table
This library implements type-checked dynamic hash tables. The hash
table entries can be arbitrary structures. Usually they consist of key
and value fields. In the description here, I<TYPE> is used a placeholder
and value fields. In the description here, B<I<TYPE>> is used a placeholder
for any of the OpenSSL datatypes, such as I<SSL_SESSION>.
lh_TYPE_new() creates a new B<LHASH_OF(TYPE)> structure to store
B<lh_I<TYPE>_new>() creates a new B<LHASH_OF>(B<I<TYPE>>) structure to store
arbitrary data entries, and specifies the 'hash' and 'compare'
callbacks to be used in organising the table's entries. The B<hash>
callbacks to be used in organising the table's entries. The I<hash>
callback takes a pointer to a table entry as its argument and returns
an unsigned long hash value for its key field. The hash value is
normally truncated to a power of 2, so make sure that your hash
function returns well mixed low order bits. The B<compare> callback
function returns well mixed low order bits. The I<compare> callback
takes two arguments (pointers to two hash table entries), and returns
0 if their keys are equal, non-zero otherwise.
0 if their keys are equal, nonzero otherwise.
If your hash table
will contain items of some particular type and the B<hash> and
B<compare> callbacks hash/compare these types, then the
will contain items of some particular type and the I<hash> and
I<compare> callbacks hash/compare these types, then the
B<IMPLEMENT_LHASH_HASH_FN> and B<IMPLEMENT_LHASH_COMP_FN> macros can be
used to create callback wrappers of the prototypes required by
lh_TYPE_new() as shown in this example:
B<lh_I<TYPE>_new>() as shown in this example:
/*
* Implement the hash and compare functions; "stuff" can be any word.
@@ -85,35 +85,35 @@ can be used in a common header file to declare the function wrappers:
DECLARE_LHASH_HASH_FN(stuff, TYPE)
DECLARE_LHASH_COMP_FN(stuff, TYPE)
Then a hash table of TYPE objects can be created using this:
Then a hash table of B<I<TYPE>> objects can be created using this:
LHASH_OF(TYPE) *htable;
htable = lh_TYPE_new(LHASH_HASH_FN(stuff), LHASH_COMP_FN(stuff));
htable = B<lh_I<TYPE>_new>(LHASH_HASH_FN(stuff), LHASH_COMP_FN(stuff));
lh_TYPE_free() frees the B<LHASH_OF(TYPE)> structure
B<table>. Allocated hash table entries will not be freed; consider
using lh_TYPE_doall() to deallocate any remaining entries in the
B<lh_I<TYPE>_free>() frees the B<LHASH_OF>(B<I<TYPE>>) structure
I<table>. Allocated hash table entries will not be freed; consider
using B<lh_I<TYPE>_doall>() to deallocate any remaining entries in the
hash table (see below).
lh_TYPE_flush() empties the B<LHASH_OF(TYPE)> structure B<table>. New
B<lh_I<TYPE>_flush>() empties the B<LHASH_OF>(B<I<TYPE>>) structure I<table>. New
entries can be added to the flushed table. Allocated hash table entries
will not be freed; consider using lh_TYPE_doall() to deallocate any
will not be freed; consider using B<lh_I<TYPE>_doall>() to deallocate any
remaining entries in the hash table (see below).
lh_TYPE_insert() inserts the structure pointed to by B<data> into
B<table>. If there already is an entry with the same key, the old
value is replaced. Note that lh_TYPE_insert() stores pointers, the
B<lh_I<TYPE>_insert>() inserts the structure pointed to by I<data> into
I<table>. If there already is an entry with the same key, the old
value is replaced. Note that B<lh_I<TYPE>_insert>() stores pointers, the
data are not copied.
lh_TYPE_delete() deletes an entry from B<table>.
B<lh_I<TYPE>_delete>() deletes an entry from I<table>.
lh_TYPE_retrieve() looks up an entry in B<table>. Normally, B<data>
B<lh_I<TYPE>_retrieve>() looks up an entry in I<table>. Normally, I<data>
is a structure with the key field(s) set; the function will return a
pointer to a fully populated structure.
lh_TYPE_doall() will, for every entry in the hash table, call
B<func> with the data item as its parameter.
B<lh_I<TYPE>_doall>() will, for every entry in the hash table, call
I<func> with the data item as its parameter.
For example:
/* Cleans up resources belonging to 'a' (this is implemented elsewhere) */
@@ -137,9 +137,9 @@ you start (which will stop the hash table ever decreasing in size).
The best solution is probably to avoid deleting items from the hash
table inside a "doall" callback!
lh_TYPE_doall_arg() is the same as lh_TYPE_doall() except that
B<func> will be called with B<arg> as the second argument and B<func>
should be of type B<LHASH_DOALL_ARG_FN_TYPE> (a callback prototype
B<lh_I<TYPE>_doall_arg>() is the same as B<lh_I<TYPE>_doall>() except that
I<func> will be called with I<arg> as the second argument and I<func>
should be of type B<LHASH_DOALL_ARG_FN>(B<I<TYPE>>) (a callback prototype
that is passed both the table entry and an extra argument). As with
lh_doall(), you can instead choose to declare your callback with a
prototype matching the types you are dealing with and use the
@@ -159,33 +159,33 @@ that is provided by the caller):
logging_bio);
lh_TYPE_error() can be used to determine if an error occurred in the last
B<lh_I<TYPE>_error>() can be used to determine if an error occurred in the last
operation.
=head1 RETURN VALUES
lh_TYPE_new() returns B<NULL> on error, otherwise a pointer to the new
B<lh_I<TYPE>_new>() returns NULL on error, otherwise a pointer to the new
B<LHASH> structure.
When a hash table entry is replaced, lh_TYPE_insert() returns the value
being replaced. B<NULL> is returned on normal operation and on error.
When a hash table entry is replaced, B<lh_I<TYPE>_insert>() returns the value
being replaced. NULL is returned on normal operation and on error.
lh_TYPE_delete() returns the entry being deleted. B<NULL> is returned if
B<lh_I<TYPE>_delete>() returns the entry being deleted. NULL is returned if
there is no such value in the hash table.
lh_TYPE_retrieve() returns the hash table entry if it has been found,
B<NULL> otherwise.
B<lh_I<TYPE>_retrieve>() returns the hash table entry if it has been found,
NULL otherwise.
lh_TYPE_error() returns 1 if an error occurred in the last operation, 0
B<lh_I<TYPE>_error>() returns 1 if an error occurred in the last operation, 0
otherwise. It's meaningful only after non-retrieve operations.
lh_TYPE_free(), lh_TYPE_flush, lh_TYPE_doall() and lh_TYPE_doall_arg()
return no values.
B<lh_I<TYPE>_free>(), B<lh_I<TYPE>_flush>(), B<lh_I<TYPE>_doall>() and
B<lh_I<TYPE>_doall_arg>() return no values.
=head1 NOTE
The LHASH code is not thread safe. All updating operations, as well as
lh_TYPE_error call must be performed under a write lock. All retrieve
B<lh_I<TYPE>_error>() call must be performed under a write lock. All retrieve
operations should be performed under a read lock, I<unless> accurate
usage statistics are desired. In which case, a write lock should be used
for retrieve operations as well. For output of the usage statistics,
@@ -223,7 +223,7 @@ without any "const" qualifiers.
=head1 BUGS
lh_TYPE_insert() returns B<NULL> both for success and error.
B<lh_I<TYPE>_insert>() returns NULL both for success and error.
=head1 SEE ALSO
doc/man3/OPENSSL_s390xcap.pod
+8
View File
@@ -145,6 +145,10 @@ the numbering is continuous across 64-bit mask boundaries.
# 64 1<<63 PCC-Scalar-Multiply-P256
# 65 1<<62 PCC-Scalar-Multiply-P384
# 66 1<<61 PCC-Scalar-Multiply-P521
# 72 1<<55 PCC-Scalar-Multiply-Ed25519
# 73 1<<54 PCC-Scalar-Multiply-Ed448
# 80 1<<47 PCC-Scalar-Multiply-X25519
# 81 1<<46 PCC-Scalar-Multiply-X448
kdsa :
# 1 1<<62 KDSA-ECDSA-Verify-P256
@@ -153,6 +157,10 @@ the numbering is continuous across 64-bit mask boundaries.
# 9 1<<54 KDSA-ECDSA-Sign-P256
# 10 1<<53 KDSA-ECDSA-Sign-P384
# 11 1<<52 KDSA-ECDSA-Sign-P521
# 32 1<<31 KDSA-EdDSA-Verify-Ed25519
# 36 1<<27 KDSA-EdDSA-Verify-Ed448
# 40 1<<23 KDSA-EdDSA-Sign-Ed25519
# 44 1<<19 KDSA-EdDSA-Sign-Ed448
:
=head1 RETURN VALUES
doc/man3/OSSL_CMP_CTX_new.pod
+662
View File
@@ -0,0 +1,662 @@
=pod
=head1 NAME
OSSL_CMP_CTX_new,
OSSL_CMP_CTX_free,
OSSL_CMP_CTX_reinit,
OSSL_CMP_CTX_set_option,
OSSL_CMP_CTX_get_option,
OSSL_CMP_CTX_set_log_cb,
OSSL_CMP_CTX_set_log_verbosity,
OSSL_CMP_CTX_print_errors,
OSSL_CMP_CTX_set1_serverPath,
OSSL_CMP_CTX_set1_serverName,
OSSL_CMP_CTX_set_serverPort,
OSSL_CMP_CTX_set1_proxyName,
OSSL_CMP_CTX_set_proxyPort,
OSSL_CMP_DEFAULT_PORT,
OSSL_CMP_CTX_set_http_cb,
OSSL_CMP_CTX_set_http_cb_arg,
OSSL_CMP_CTX_get_http_cb_arg,
OSSL_CMP_CTX_set_transfer_cb,
OSSL_CMP_CTX_set_transfer_cb_arg,
OSSL_CMP_CTX_get_transfer_cb_arg,
OSSL_CMP_CTX_set1_srvCert,
OSSL_CMP_CTX_set1_expected_sender,
OSSL_CMP_CTX_set0_trustedStore,
OSSL_CMP_CTX_get0_trustedStore,
OSSL_CMP_CTX_set1_untrusted_certs,
OSSL_CMP_CTX_get0_untrusted_certs,
OSSL_CMP_CTX_set1_clCert,
OSSL_CMP_CTX_set1_pkey,
OSSL_CMP_CTX_set1_referenceValue,
OSSL_CMP_CTX_set1_secretValue,
OSSL_CMP_CTX_set1_recipient,
OSSL_CMP_CTX_push0_geninfo_ITAV,
OSSL_CMP_CTX_set1_extraCertsOut,
OSSL_CMP_CTX_set0_newPkey,
OSSL_CMP_CTX_get0_newPkey,
OSSL_CMP_CTX_set1_issuer,
OSSL_CMP_CTX_set1_subjectName,
OSSL_CMP_CTX_push1_subjectAltName,
OSSL_CMP_CTX_set0_reqExtensions,
OSSL_CMP_CTX_reqExtensions_have_SAN,
OSSL_CMP_CTX_push0_policy,
OSSL_CMP_CTX_set1_oldCert,
OSSL_CMP_CTX_set1_p10CSR,
OSSL_CMP_CTX_push0_genm_ITAV,
OSSL_CMP_CTX_set_certConf_cb,
OSSL_CMP_CTX_set_certConf_cb_arg,
OSSL_CMP_CTX_get_certConf_cb_arg,
OSSL_CMP_CTX_get_status,
OSSL_CMP_CTX_get0_statusString,
OSSL_CMP_CTX_get_failInfoCode,
OSSL_CMP_CTX_get0_newCert,
OSSL_CMP_CTX_get1_caPubs,
OSSL_CMP_CTX_get1_extraCertsIn,
OSSL_CMP_CTX_set1_transactionID,
OSSL_CMP_CTX_set1_senderNonce
- functions for managing the CMP client context data structure
=head1 SYNOPSIS
#include <openssl/cmp.h>
OSSL_CMP_CTX *OSSL_CMP_CTX_new(void);
void OSSL_CMP_CTX_free(OSSL_CMP_CTX *ctx);
int OSSL_CMP_CTX_reinit(OSSL_CMP_CTX *ctx);
int OSSL_CMP_CTX_set_option(OSSL_CMP_CTX *ctx, int opt, int val);
int OSSL_CMP_CTX_get_option(const OSSL_CMP_CTX *ctx, int opt);
/* logging and error reporting: */
int OSSL_CMP_CTX_set_log_cb(OSSL_CMP_CTX *ctx, OSSL_cmp_log_cb_t cb);
#define OSSL_CMP_CTX_set_log_verbosity(ctx, level)
void OSSL_CMP_CTX_print_errors(OSSL_CMP_CTX *ctx);
/* message transfer: */
int OSSL_CMP_CTX_set1_serverPath(OSSL_CMP_CTX *ctx, const char *path);
int OSSL_CMP_CTX_set1_serverName(OSSL_CMP_CTX *ctx, const char *name);
int OSSL_CMP_CTX_set_serverPort(OSSL_CMP_CTX *ctx, int port);
int OSSL_CMP_CTX_set1_proxyName(OSSL_CMP_CTX *ctx, const char *name);
int OSSL_CMP_CTX_set_proxyPort(OSSL_CMP_CTX *ctx, int port);
#define OSSL_CMP_DEFAULT_PORT 80
typedef BIO (*OSSL_cmp_http_cb_t) (OSSL_CMP_CTX *ctx, BIO *hbio,
unsigned long detail);
int OSSL_CMP_CTX_set_http_cb(OSSL_CMP_CTX *ctx, OSSL_cmp_http_cb_t cb);
int OSSL_CMP_CTX_set_http_cb_arg(OSSL_CMP_CTX *ctx, void *arg);
void *OSSL_CMP_CTX_get_http_cb_arg(const OSSL_CMP_CTX *ctx);
typedef int (*OSSL_cmp_transfer_cb_t) (OSSL_CMP_CTX *ctx,
const OSSL_CMP_MSG *req,
OSSL_CMP_MSG **res);
int OSSL_CMP_CTX_set_transfer_cb(OSSL_CMP_CTX *ctx,
OSSL_cmp_transfer_cb_t cb);
int OSSL_CMP_CTX_set_transfer_cb_arg(OSSL_CMP_CTX *ctx, void *arg);
void *OSSL_CMP_CTX_get_transfer_cb_arg(const OSSL_CMP_CTX *ctx);
/* server authentication: */
int OSSL_CMP_CTX_set1_srvCert(OSSL_CMP_CTX *ctx, X509 *cert);
int OSSL_CMP_CTX_set1_expected_sender(OSSL_CMP_CTX *ctx,
const X509_NAME *name);
int OSSL_CMP_CTX_set0_trustedStore(OSSL_CMP_CTX *ctx, X509_STORE *store);
X509_STORE *OSSL_CMP_CTX_get0_trustedStore(const OSSL_CMP_CTX *ctx);
int OSSL_CMP_CTX_set1_untrusted_certs(OSSL_CMP_CTX *ctx,
STACK_OF(X509) *certs);
STACK_OF(X509) *OSSL_CMP_CTX_get0_untrusted_certs(const OSSL_CMP_CTX *ctx);
/* client authentication: */
int OSSL_CMP_CTX_set1_clCert(OSSL_CMP_CTX *ctx, X509 *cert);
int OSSL_CMP_CTX_set1_pkey(OSSL_CMP_CTX *ctx, EVP_PKEY *pkey);
int OSSL_CMP_CTX_set1_referenceValue(OSSL_CMP_CTX *ctx,
const unsigned char *ref, int len);
int OSSL_CMP_CTX_set1_secretValue(OSSL_CMP_CTX *ctx, const unsigned char *sec,
const int len);
/* CMP message header and extra certificates: */
int OSSL_CMP_CTX_set1_recipient(OSSL_CMP_CTX *ctx, const X509_NAME *name);
int OSSL_CMP_CTX_push0_geninfo_ITAV(OSSL_CMP_CTX *ctx, OSSL_CMP_ITAV *itav);
int OSSL_CMP_CTX_set1_extraCertsOut(OSSL_CMP_CTX *ctx,
STACK_OF(X509) *extraCertsOut);
/* certificate template: */
int OSSL_CMP_CTX_set0_newPkey(OSSL_CMP_CTX *ctx, int priv, EVP_PKEY *pkey);
EVP_PKEY *OSSL_CMP_CTX_get0_newPkey(const OSSL_CMP_CTX *ctx, int priv);
int OSSL_CMP_CTX_set1_issuer(OSSL_CMP_CTX *ctx, const X509_NAME *name);
int OSSL_CMP_CTX_set1_subjectName(OSSL_CMP_CTX *ctx, const X509_NAME *name);
int OSSL_CMP_CTX_push1_subjectAltName(OSSL_CMP_CTX *ctx,
const GENERAL_NAME *name);
int OSSL_CMP_CTX_set0_reqExtensions(OSSL_CMP_CTX *ctx, X509_EXTENSIONS *exts);
int OSSL_CMP_CTX_reqExtensions_have_SAN(OSSL_CMP_CTX *ctx);
int OSSL_CMP_CTX_push0_policy(OSSL_CMP_CTX *ctx, POLICYINFO *pinfo);
int OSSL_CMP_CTX_set1_oldCert(OSSL_CMP_CTX *ctx, X509 *cert);
int OSSL_CMP_CTX_set1_p10CSR(OSSL_CMP_CTX *ctx, const X509_REQ *csr);
/* misc body contents: */
int OSSL_CMP_CTX_push0_genm_ITAV(OSSL_CMP_CTX *ctx, OSSL_CMP_ITAV *itav);
/* certificate confirmation: */
typedef int (*OSSL_cmp_certConf_cb_t) (OSSL_CMP_CTX *ctx, X509 *cert,
int fail_info, const char **txt);
int OSSL_CMP_CTX_set_certConf_cb(OSSL_CMP_CTX *ctx, OSSL_cmp_certConf_cb_t cb);
int OSSL_CMP_CTX_set_certConf_cb_arg(OSSL_CMP_CTX *ctx, void *arg);
void *OSSL_CMP_CTX_get_certConf_cb_arg(const OSSL_CMP_CTX *ctx);
/* result fetching: */
int OSSL_CMP_CTX_get_status(const OSSL_CMP_CTX *ctx);
OSSL_CMP_PKIFREETEXT *OSSL_CMP_CTX_get0_statusString(const OSSL_CMP_CTX *ctx);
int OSSL_CMP_CTX_get_failInfoCode(const OSSL_CMP_CTX *ctx);
X509 *OSSL_CMP_CTX_get0_newCert(const OSSL_CMP_CTX *ctx);
STACK_OF(X509) *OSSL_CMP_CTX_get1_caPubs(const OSSL_CMP_CTX *ctx);
STACK_OF(X509) *OSSL_CMP_CTX_get1_extraCertsIn(const OSSL_CMP_CTX *ctx);
/* for test purposes only: */
int OSSL_CMP_CTX_set1_transactionID(OSSL_CMP_CTX *ctx,
const ASN1_OCTET_STRING *id);
int OSSL_CMP_CTX_set1_senderNonce(OSSL_CMP_CTX *ctx,
const ASN1_OCTET_STRING *nonce);
=head1 DESCRIPTION
This is the context API for using CMP (Certificate Management Protocol) with
OpenSSL.
OSSL_CMP_CTX_new() allocates and initializes an OSSL_CMP_CTX structure to
default values, e.g., proof-of-possession method is set to POPOSigningKey.
OSSL_CMP_CTX_free() deallocates an OSSL_CMP_CTX structure.
OSSL_CMP_CTX_reinit() prepares the given B<ctx> for a further transaction by
clearing the internal CMP transaction (aka session) status, PKIStatusInfo,
and any previous results (newCert, caPubs, and extraCertsIn)
from the last executed transaction.
All other field values (i.e., CMP options) are retained for potential re-use.
OSSL_CMP_CTX_set_option() sets the given value for the given option
(e.g., OSSL_CMP_OPT_IMPLICITCONFIRM) in the given OSSL_CMP_CTX structure.
The following options can be set:
=over 4
=item B<OSSL_CMP_OPT_LOG_VERBOSITY>
The level of severity needed for actually outputting log messages
due to errors, warnings, general info, debugging, etc.
Default is OSSL_CMP_LOG_INFO. See also L<OSSL_CMP_log_open(3)>.
=item B<OSSL_CMP_OPT_MSGTIMEOUT>
Number of seconds (or 0 for infinite) a CMP message round trip is
allowed to take before a timeout error is returned. Default is 120.
=item B<OSSL_CMP_OPT_TOTALTIMEOUT>
Maximum total number of seconds an enrollment (including polling)
may take. Default is 0 (infinite).
=item B<OSSL_CMP_OPT_VALIDITYDAYS>
Number of days new certificates are asked to be valid for.
=item B<OSSL_CMP_OPT_SUBJECTALTNAME_NODEFAULT>
Do not take default Subject Alternative Names
from the reference certificate.
=item B<OSSL_CMP_OPT_SUBJECTALTNAME_CRITICAL>
Demand that the given Subject Alternative Names are flagged as critical.
=item B<OSSL_CMP_OPT_POLICIES_CRITICAL>
Demand that the given policies are flagged as critical.
=item B<OSSL_CMP_OPT_POPOMETHOD>
Select the proof of possession method to use. Possible values are:
OSSL_CRMF_POPO_NONE - ProofOfPossession field omitted
OSSL_CRMF_POPO_RAVERIFIED - assert that the RA has already
verified the PoPo
OSSL_CRMF_POPO_SIGNATURE - sign a value with private key,
which is the default.
OSSL_CRMF_POPO_KEYENC - decrypt the encrypted certificate
("indirect method")
Note that a signature-based POPO can only be produced if a private key
is provided as the newPkey or client pkey component of the CMP context.
=item B<OSSL_CMP_OPT_DIGEST_ALGNID>
The digest algorithm NID to be used in RFC 4210's MSG_SIG_ALG,
if applicable used for message protection and Proof-of-Possession.
Default is SHA256.
OSSL_CMP_OPT_OWF_ALGNID
The digest algorithm NID to be used as one-way function (OWF)
in RFC 4210's MSG_MAC_ALG, if applicable used for message protection.
Default is SHA256.
OSSL_CMP_OPT_MAC_ALGNID
The MAC algorithm NID to be used in RFC 4210's MSG_MAC_ALG,
if applicable used for message protection.
Default is HMAC-SHA1 as per RFC 4210.
=item B<OSSL_CMP_OPT_REVOCATION_REASON>
The reason code to be included in a Revocation Request (RR);
values: 0..10 (RFC 5210, 5.3.1) or -1 for none, which is the default.
=item B<OSSL_CMP_OPT_IMPLICITCONFIRM>
Request server to enable implicit confirm mode, where the client
does not need to send confirmation upon receiving the
certificate. If the server does not enable implicit confirmation
in the return message, then confirmation is sent anyway.
=item B<OSSL_CMP_OPT_DISABLECONFIRM>
Do not confirm enrolled certificates, to cope with broken servers
not supporting implicit confirmation correctly.
B<WARNING:> This setting leads to unspecified behavior and it is meant
exclusively to allow interoperability with server implementations violating
RFC 4210.
=item B<OSSL_CMP_OPT_UNPROTECTED_SEND>
Send messages without CMP-level protection.
=item B<OSSL_CMP_OPT_UNPROTECTED_ERRORS>
Accept unprotected error responses which are either explicitly
unprotected or where protection verification failed. Applies to regular
error messages as well as certificate responses (IP/CP/KUP) and
revocation responses (RP) with rejection.
B<WARNING:> This setting leads to unspecified behavior and it is meant
exclusively to allow interoperability with server implementations violating
RFC 4210.
=item B<OSSL_CMP_OPT_IGNORE_KEYUSAGE>
Ignore key usage restrictions in signer certificate when
validating signature-based protection in received CMP messages.
Else, 'digitalSignature' must be allowed by CMP signer certificates.
=item B<OSSL_CMP_OPT_PERMIT_TA_IN_EXTRACERTS_FOR_IR>
Allow retrieving a trust anchor from extraCerts and using that
to validate the certificate chain of an IP message.
=back
OSSL_CMP_CTX_get_option() reads the current value of the given option
(e.g., OSSL_CMP_OPT_IMPLICITCONFIRM) from the given OSSL_CMP_CTX structure.
OSSL_CMP_CTX_set_log_cb() sets in B<ctx> the callback function C<cb>
for handling error queue entries and logging messages.
When C<cb> is NULL errors are printed to STDERR (if available, else ignored)
any log messages are ignored.
Alternatively, L<OSSL_CMP_log_open(3)> may be used to direct logging to STDOUT.
OSSL_CMP_CTX_set_log_verbosity() is a macro setting the
OSSL_CMP_OPT_LOG_VERBOSITY context option to the given level.
OSSL_CMP_CTX_print_errors() outputs any entries in the OpenSSL error queue.
It is similar to B<ERR_print_errors_cb()> but uses the CMP log callback function
if set in the C<ctx> for uniformity with CMP logging if given. Otherwise it uses
B<ERR_print_errors(3)> to print to STDERR (unless OPENSSL_NO_STDIO is defined).
OSSL_CMP_CTX_set1_serverPath() sets the HTTP path of the CMP server on the host.
OSSL_CMP_CTX_set1_serverName() sets the given server Address (as IP or name)
in the given OSSL_CMP_CTX structure.
OSSL_CMP_CTX_set_serverPort() sets the port of the CMP server to connect to.
Port defaults to OSSL_CMP_DEFAULT_PORT = 80 if not set explicitly.
OSSL_CMP_CTX_set1_proxyName() sets the hostname of the HTTP proxy to be used
for connecting to the CA server.
OSSL_CMP_CTX_set_proxyPort() sets the port of the HTTP proxy.
Port defaults to OSSL_CMP_DEFAULT_PORT = 80 if not set explicitly.
OSSL_CMP_CTX_set_http_cb() sets the optional http connect/disconnect callback
function, which has the prototype
typedef BIO *(*OSSL_cmp_http_cb_t)(OSSL_CMP_CTX *ctx, BIO *hbio,
unsigned long detail);
It may modify the HTTP BIO given in the B<hbio> argument
used by OSSL_CMP_MSG_http_perform().
On connect the B<detail> argument is 1.
On disconnect it is 0 if no error occurred or else the last error code.
For instance, on connect a TLS BIO may be prepended to implement HTTPS,
and on disconnect some error diagnostics and/or cleanup may be done.
The callback function should return NULL to indicate failure.
It may make use of a custom defined argument stored in the ctx
by means of OSSL_CMP_CTX_set_http_cb_arg(),
which may be retrieved again through OSSL_CMP_CTX_get_http_cb_arg().
OSSL_CMP_CTX_set_http_cb_arg() sets an argument, respectively a pointer to
a structure containing arguments,
optionally to be used by the http connect/disconnect callback function.
B<arg> is not consumed, and it must therefore explicitly be freed when not
needed any more. B<arg> may be NULL to clear the entry.
OSSL_CMP_CTX_get_http_cb_arg() gets the argument, respectively the pointer to a
structure containing arguments, previously set by
OSSL_CMP_CTX_set_http_cb_arg() or NULL if unset.
OSSL_CMP_CTX_set_transfer_cb() sets the message transfer callback function,
which has the type
typedef int (*OSSL_cmp_transfer_cb_t)(const OSSL_CMP_CTX *ctx,
const OSSL_CMP_MSG *req,
OSSL_CMP_MSG **res);
Returns 1 on success, 0 on error.
Default is NULL, which implies the use of L<OSSL_CMP_MSG_http_perform(3)>.
The callback should send the CMP request it obtains via the B<req> parameter
and on success place the response in the B<*res> output parameter.
The transfer callback may make use of a custom defined argument stored in
the ctx by means of OSSL_CMP_CTX_set_transfer_cb_arg(), which may be retrieved
again through OSSL_CMP_CTX_get_transfer_cb_arg().
On success the cb must return 0, else a CMP error reason code defined in cmp.h.
OSSL_CMP_CTX_set_transfer_cb_arg() sets an argument, respectively a pointer to a
structure containing arguments, optionally to be used by the transfer callback.
B<arg> is not consumed, and it must therefore explicitly be freed when not
needed any more. B<arg> may be NULL to clear the entry.
OSSL_CMP_CTX_get_transfer_cb_arg() gets the argument, respectively the pointer
to a structure containing arguments, previously set by
OSSL_CMP_CTX_set_transfer_cb_arg() or NULL if unset.
OSSL_CMP_CTX_set1_srvCert() pins the server certificate to be directly trusted
(even if it is expired) for verifying response messages.
The cert pointer is not consumed. It may be NULL to clear the entry.
OSSL_CMP_CTX_set1_expected_sender() sets the Distinguished Name (DN) expected to
be given in the sender response for messages protected with MSG_SIG_ALG. This
may be used to enforce that during validation of received messages the given DN
matches the sender field of the PKIMessage header, which in turn is used to
identify the server certificate.
This can be used to ensure that only a particular entity is accepted to act as
CMP server, and attackers are not able to use arbitrary certificates of a
trusted PKI hierarchy to fraudulently pose as server.
This defaults to the subject DN of the certificate set via
OSSL_CMP_CTX_set1_srvCert(), if any.
OSSL_CMP_CTX_set0_trustedStore() sets the X509_STORE type certificate store
containing trusted (root) CA certificates. The certificate store may also hold
CRLs and a certificate verification callback function used for CMP server
authentication. Any already existing store entry is freed. When given a NULL
parameter the entry is cleared.
OSSL_CMP_CTX_get0_trustedStore() returns a pointer to the certificate store
containing trusted root CA certificates, which may be empty if unset.
OSSL_CMP_CTX_set1_untrusted_certs() takes over a list of certificates containing
non-trusted intermediate certs used for path construction in authentication
of the CMP server and potentially others (TLS server, newly enrolled cert).
The reference counts of those certificates handled successfully are increased.
OSSL_CMP_CTX_get0_untrusted_certs(OSSL_CMP_CTX *ctx) returns a pointer to the
list of untrusted certs, which my be empty if unset.
OSSL_CMP_CTX_set1_clCert() sets the client certificate in the given
OSSL_CMP_CTX structure. The client certificate will then be used by the
functions to set the "sender" field for outgoing messages and it will be
included in the extraCerts field.
OSSL_CMP_CTX_set1_pkey() sets the private key corresponding to the client
certificate set with B<OSSL_CMP_CTX_set1_clCert()> in the given CMP context.
Used to create the protection in case of MSG_SIG_ALG.
OSSL_CMP_CTX_set1_referenceValue() sets the given referenceValue in the given
B<ctx> or clears it if the B<ref> argument is NULL.
OSSL_CMP_CTX_set1_secretValue() sets the B<sec> with the length B<len> in the
given B<ctx> or clears it if the B<sec> argument is NULL.
OSSL_CMP_CTX_set1_recipient() sets the recipient name that will be used in the
PKIHeader of a request message, i.e. the X509 name of the (CA) server.
Setting is overruled by subject of srvCert if set.
If neither srvCert nor recipient are set, the recipient of the PKI message is
determined in the following order: issuer, issuer of old cert (oldCert),
issuer of client cert (clCert), else NULL-DN.
When a response is received, its sender must match the recipient of the request.
OSSL_CMP_CTX_push0_geninfo_ITAV() adds B<itav> to the stack in the B<ctx> to be
added to the GeneralInfo field of the CMP PKIMessage header of a request
message sent with this context. Consumes the pointer to B<itav>.
OSSL_CMP_CTX_set1_extraCertsOut() sets the stack of extraCerts that will be
sent to remote.
OSSL_CMP_CTX_set0_newPkey() can be used to explicitly set the given EVP_PKEY
structure as the private or public key to be certified in the CMP context.
The B<priv> parameter must be 0 if and only if the given key is a public key.
OSSL_CMP_CTX_get0_newPkey() gives the key to use for certificate enrollment
dependent on fields of the CMP context structure:
the newPkey (which may be a private or public key) if present,
else the public key in the p10CSR if present, else the client private key.
If the B<priv> parameter is not 0 and the selected key does not have a
private component then NULL is returned.
OSSL_CMP_CTX_set1_issuer() sets the name of the intended issuer that
will be set in the CertTemplate, i.e., the X509 name of the CA server.
OSSL_CMP_CTX_set1_subjectName() sets the subject DN that will be used in
the CertTemplate structure when requesting a new cert. For Key Update Requests
(KUR), it defaults to the subject DN of the reference certificate,
see B<OSSL_CMP_CTX_set1_oldCert()>. This default is used for Initialization
Requests (IR) and Certification Requests (CR) only if no SANs are set.
If clCert is not set (e.g. in case of IR with MSG_MAC_ALG), the subject DN
is also used as sender of the PKI message.
OSSL_CMP_CTX_push1_subjectAltName() adds the given X509 name to the list of
alternate names on the certificate template request. This cannot be used if
any Subject Alternative Name extension is set via
OSSL_CMP_CTX_set0_reqExtensions().
By default, unless OSSL_CMP_OPT_SUBJECTALTNAME_NODEFAULT has been set,
the Subject Alternative Names are copied from the reference certificate,
see OSSL_CMP_CTX_set1_oldCert().
If set and the subject DN is not set with OSSL_CMP_CTX_set1_subjectName(), then
the certificate template of an IR and CR will not be filled with the default
subject DN from the reference certificate (see OSSL_CMP_CTX_set1_oldCert().
If a subject DN is desired it needs to be set explicitly with
OSSL_CMP_CTX_set1_subjectName().
OSSL_CMP_CTX_set0_reqExtensions() sets the X.509v3 extensions to be used in
IR/CR/KUR.
OSSL_CMP_CTX_reqExtensions_have_SAN() returns 1 if the context contains
a Subject Alternative Name extension, else 0 or -1 on error.
OSSL_CMP_CTX_push0_policy() adds the certificate policy info object
to the X509_EXTENSIONS of the requested certificate template.
OSSL_CMP_CTX_set1_oldCert() sets the old certificate to be updated in
Key Update Requests (KUR) or to be revoked in Revocation Requests (RR).
It must be given for RR, else it defaults to B<clCert>.
The reference certificate determined in this way, if any, is also used for
deriving default subject DN and Subject Alternative Names for IR, CR, and KUR.
Its issuer, if any, is used as default recipient in the CMP message header.
OSSL_CMP_CTX_set1_p10CSR() sets the PKCS#10 CSR to be used in P10CR.
OSSL_CMP_CTX_push0_genm_ITAV() adds B<itav> to the stack in the B<ctx> which
will be the body of a General Message sent with this context.
Consumes the pointer to B<itav>.
OSSL_CMP_CTX_set_certConf_cb() sets the callback used for evaluating the newly
enrolled certificate before the library sends, depending on its result,
a positive or negative certConf message to the server. The callback has type
typedef int (*OSSL_cmp_certConf_cb_t) (OSSL_CMP_CTX *ctx, X509 *cert,
int fail_info, const char **txt);
and should inspect the certificate it obtains via the B<cert> parameter and may
overrule the pre-decision given in the B<fail_info> and B<*txt> parameters.
If it accepts the certificate it must return 0, indicating success. Else it must
return a bit field reflecting PKIFailureInfo with at least one failure bit and
may set the B<*txt> output parameter to point to a string constant with more
detail. The transfer callback may make use of a custom defined argument stored
in the B<ctx> by means of OSSL_CMP_CTX_set_certConf_cb_arg(), which may be
retrieved again through OSSL_CMP_CTX_get_certConf_cb_arg().
Typically, the callback will check at least that the certificate can be verified
using a set of trusted certificates.
It also could compare the subject DN and other fields of the newly
enrolled certificate with the certificate template of the request.
OSSL_CMP_CTX_set_certConf_cb_arg() sets an argument, respectively a pointer to a
structure containing arguments, optionally to be used by the certConf callback.
B<arg> is not consumed, and it must therefore explicitly be freed when not
needed any more. B<arg> may be NULL to clear the entry.
OSSL_CMP_CTX_get_certConf_cb_arg() gets the argument, respectively the pointer
to a structure containing arguments, previously set by
OSSL_CMP_CTX_set_certConf_cb_arg(), or NULL if unset.
OSSL_CMP_CTX_get_status() returns the PKIstatus from the last received
CertRepMessage or Revocation Response or error message, or -1 if unset.
OSSL_CMP_CTX_get0_statusString() returns the statusString from the last received
CertRepMessage or Revocation Response or error message, or NULL if unset.
OSSL_CMP_CTX_get_failInfoCode() returns the error code from the failInfo field
of the last received CertRepMessage or Revocation Response or error message.
This is a bit field and the flags for it are specified in L<cmp.h>.
The flags start with OSSL_CMP_CTX_FAILINFO, for example:
OSSL_CMP_CTX_FAILINFO_badAlg. Returns -1 if the failInfoCode field is unset.
OSSL_CMP_CTX_get0_newCert() returns the pointer to the newly obtained
certificate in case it is available, else NULL.
OSSL_CMP_CTX_get1_caPubs() returns a pointer to a duplicate of the stack of
X.509 certificates received in the caPubs field of last received certificate
response message IP/CP/KUP.
OSSL_CMP_CTX_get1_extraCertsIn() returns a pointer to a duplicate of the stack
of X.509 certificates received in the last received non-empty extraCerts field.
Returns an empty stack if no extraCerts have been received in the current
transaction.
OSSL_CMP_CTX_set1_transactionID() sets the given transaction ID in the given
OSSL_CMP_CTX structure.
OSSL_CMP_CTX_set1_senderNonce() stores the last sent sender B<nonce> in
the B<ctx>. This will be used to validate the recipNonce in incoming messages.
=head1 NOTES
CMP is defined in RFC 4210 (and CRMF in RFC 4211).
=head1 RETURN VALUES
OSSL_CMP_CTX_free() and OSSL_CMP_CTX_print_errors() do not return anything.
OSSL_CMP_CTX_new(),
OSSL_CMP_CTX_get_http_cb_arg(),
OSSL_CMP_CTX_get_transfer_cb_arg(),
OSSL_CMP_CTX_get0_trustedStore(),
OSSL_CMP_CTX_get0_untrusted_certs(),
OSSL_CMP_CTX_get0_newPkey(),
OSSL_CMP_CTX_get_certConf_cb_arg(),
OSSL_CMP_CTX_get0_statusString(),
OSSL_CMP_CTX_get0_newCert(),
OSSL_CMP_CTX_get1_caPubs(), and
OSSL_CMP_CTX_get1_extraCertsIn()
return the intended pointer value as described above or NULL on error.
OSSL_CMP_CTX_get_option(),
OSSL_CMP_CTX_reqExtensions_have_SAN(),
OSSL_CMP_CTX_get_status(), and
OSSL_CMP_CTX_get_failInfoCode()
return the intended value as described above or -1 on error.
All other functions return 1 on success, 0 on error.
=head1 EXAMPLES
The following code does an Initialization Request:
cmp_ctx = OSSL_CMP_CTX_new();
OSSL_CMP_CTX_set1_serverName(cmp_ctx, opt_serverName);
OSSL_CMP_CTX_set1_referenceValue(cmp_ctx, ref, ref_len);
OSSL_CMP_CTX_set1_secretValue(cmp_ctx, sec, sec_len);
OSSL_CMP_CTX_set0_newPkey(cmp_ctx, new_pkey, 1);
OSSL_CMP_CTX_set1_caCert(cmp_ctx, ca_cert);
initialClCert = OSSL_CMP_exec_IR_ses(cmp_ctx);
The following code does an Initialization Request using an
external identity certificate (RFC 4210, Appendix E.7):
cmp_ctx = OSSL_CMP_CTX_new();
OSSL_CMP_CTX_set1_serverName(cmp_ctx, sname);
OSSL_CMP_CTX_set1_clCert(cmp_ctx, cl_cert);
OSSL_CMP_CTX_set1_pkey(cmp_ctx, pkey);
OSSL_CMP_CTX_set0_newPkey(cmp_ctx, new_pkey, 1);
OSSL_CMP_CTX_set1_caCert(cmp_ctx, ca_cert);
initialClCert = OSSL_CMP_exec_IR_ses(cmp_ctx);
Here externalCert is an X509 certificate granted to the EE by another CA
which is trusted by the current CA the code will connect to.
The following code does a Key Update Request:
cmp_ctx = OSSL_CMP_CTX_new();
OSSL_CMP_CTX_set1_serverName(cmp_ctx, sname);
OSSL_CMP_CTX_set1_pkey(cmp_ctx, pkey);
OSSL_CMP_CTX_set0_newPkey(cmp_ctx, new_pkey, 1);
OSSL_CMP_CTX_set1_clCert(cmp_ctx, cl_cert);
OSSL_CMP_CTX_set1_caCert(cmp_ctx, ca_cert);
updatedClCert = OSSL_CMP_exec_KUR_ses(cmp_ctx);
The following code (which omits error handling) sends a General Message
including, as an example, the id-it-signKeyPairTypes OID and prints info on
the General Response contents.
cmp_ctx = OSSL_CMP_CTX_new();
OSSL_CMP_CTX_set1_serverName(cmp_ctx, sname);
OSSL_CMP_CTX_set1_referenceValue(cmp_ctx, ref, ref_len);
OSSL_CMP_CTX_set1_secretValue(cmp_ctx, sec, sec_len);
ASN1_OBJECT *type = OBJ_txt2obj("1.3.6.1.5.5.7.4.2", 1);
OSSL_CMP_ITAV *itav = OSSL_CMP_ITAV_new(type, NULL);
OSSL_CMP_CTX_push0_genm_ITAV(cmp_ctx, itav);
STACK_OF(OSSL_CMP_ITAV) *itavs;
itavs = OSSL_CMP_exec_GENM_ses(cmp_ctx);
print_itavs(itavs);
sk_OSSL_CMP_ITAV_pop_free(itavs, OSSL_CMP_ITAV_free);
=head1 SEE ALSO
L<OSSL_CMP_exec_IR_ses(3)>, L<OSSL_CMP_exec_KUR_ses(3)>,
L<OSSL_CMP_exec_GENM_ses(3)>
=head1 HISTORY
The OpenSSL CMP support was added in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2007-2019 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (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
doc/man3/OSSL_CMP_ITAV_set0.pod
+6
View File
@@ -23,6 +23,8 @@ OSSL_CMP_ITAV_push0_stack_item
=head1 DESCRIPTION
Certificate Management Protocol (CMP, RFC 4210) extension to OpenSSL
ITAV is short for InfoTypeAndValue. This type is defined in RFC 4210
section 5.3.19 and Appendix F. It is used at various places in CMP messages,
e.g., in the generalInfo PKIHeader field, to hold a key-value pair.
@@ -93,6 +95,10 @@ included in the requests' PKIHeader's genInfo field.
L<OSSL_CMP_CTX_new(3)>, L<OSSL_CMP_CTX_free(3)>, L<ASN1_TYPE_set(3)>
=head1 HISTORY
The OpenSSL CMP support was added in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2007-2019 The OpenSSL Project Authors. All Rights Reserved.
doc/man3/OSSL_CMP_log_open.pod
+140
View File
@@ -0,0 +1,140 @@
=pod
=head1 NAME
OSSL_CMP_log_open,
OSSL_CMP_log_close,
OSSL_CMP_alert,
OSSL_CMP_err,
OSSL_CMP_warn,
OSSL_CMP_info,
OSSL_CMP_debug,
OSSL_CMP_log,
OSSL_CMP_log1,
OSSL_CMP_log2,
OSSL_CMP_log3,
OSSL_CMP_log4,
OSSL_CMP_severity,
OSSL_CMP_LOG_EMERG,
OSSL_CMP_LOG_ALERT,
OSSL_CMP_LOG_CRIT,
OSSL_CMP_LOG_ERR,
OSSL_CMP_LOG_WARNING,
OSSL_CMP_LOG_NOTICE,
OSSL_CMP_LOG_INFO,
OSSL_CMP_LOG_DEBUG,
OSSL_CMP_print_errors_cb
- functions for logging and error reporting
=head1 SYNOPSIS
#include <openssl/cmp_util.h>
int OSSL_CMP_log_open(void);
void OSSL_CMP_log_close(void);
#define OSSL_CMP_alert(msg)
#define OSSL_CMP_err(msg)
#define OSSL_CMP_warn(msg)
#define OSSL_CMP_info(msg)
#define OSSL_CMP_debug(msg)
#define OSSL_CMP_log(level, msg)
#define OSSL_CMP_log1(level, fmt, arg1)
#define OSSL_CMP_log2(level, fmt, arg1, arg2)
#define OSSL_CMP_log3(level, fmt, arg1, arg2, arg3)
#define OSSL_CMP_log4(level, fmt, arg1, arg2, arg3, arg4)
/* severity level declarations resemble those from syslog.h */
typedef int OSSL_CMP_severity;
#define OSSL_CMP_LOG_EMERG 0
#define OSSL_CMP_LOG_ALERT 1
#define OSSL_CMP_LOG_CRIT 2
#define OSSL_CMP_LOG_ERR 3
#define OSSL_CMP_LOG_WARNING 4
#define OSSL_CMP_LOG_NOTICE 5
#define OSSL_CMP_LOG_INFO 6
#define OSSL_CMP_LOG_DEBUG 7
typedef int (*OSSL_cmp_log_cb_t) (const char *component,
const char *file, int line,
OSSL_CMP_severity level, const char *msg);
void OSSL_CMP_print_errors_cb(OSSL_cmp_log_cb_t log_fn);
=head1 DESCRIPTION
The logging and error reporting facility described here contains
convenience functions for CMP-specific logging via the trace API,
including a string prefix mirroring the severity levels of syslog.h,
and enhancements of the error queue mechanism needed for large diagnostic
messages produced by the CMP library in case of certificate validation failures.
When an interesting activity is performed or an error occurs, some detail
should be provided for user information, debugging, and auditing purposes.
A CMP application can obtain this information by providing a callback function
with the following type:
typedef void (*OSSL_cmp_log_cb_t)(const char *component,
const char *file, int line,
OSSL_CMP_severity level, const char *msg);
The parameters may provide
a component identifier (which may be a library name or function name) or NULL,
a file pathname or NULL,
a line number or 0 indicating the source code location,
a severity level, and
a message string describing the nature of the event, terminated by '\n'.
Even when an activity is successful some warnings may be useful and some degree
of auditing may be required. Therefore the logging facility supports a severity
level and the callback function has a B<level> parameter indicating such a
level, such that error, warning, info, debug, etc. can be treated differently.
The callback is activated only when the severity level is sufficient according
to the current level of verbosity, which by default is OSSL_CMP_LOG_INFO.
The callback function may itself do non-trivial tasks like writing to
a log file or remote stream, which in turn may fail.
Therefore the function should return 1 on success and 0 on failure.
OSSL_CMP_log_open() initializes the CMP-specific logging facility to output
everything to STDOUT. It fails if the integrated tracing is disabled or STDIO
is not available. It may be called during application startup.
Alternatively, L<OSSL_CMP_CTX_set_log_cb(3)> can be used for more flexibility.
As long as neither if the two is used any logging output is ignored.
OSSL_CMP_log_close() may be called when all activities are finished to flush
any pending CMP-specific log output and deallocate related resources.
It may be called multiple times. It does get called at OpenSSL stutdown.
OSSL_CMP_alert() outputs a simple alert message via the trace API.
OSSL_CMP_err() outputs a simple error message via the trace API.
OSSL_CMP_warn() outputs a simple warning message via the trace API.
OSSL_CMP_info() outputs a simple info message via the trace API.
OSSL_CMP_debug() outputs a simple debug message via the trace API.
Note that due to the design of the trace API used, the log functions have no
effect unless the B<enable-trace> option is used during build configuration.
OSSL_CMP_print_errors_cb() outputs any entries in the OpenSSL error queue.
It is similar to B<ERR_print_errors_cb()> but uses the CMP log callback function
C<log_fn> for uniformity with CMP logging if not B<NULL>. Otherwise it uses
B<ERR_print_errors(3)> to print to STDERR (unless OPENSSL_NO_STDIO is defined).
=head1 RETURN VALUES
OSSL_CMP_log_close() and OSSL_CMP_print_errors_cb() do not return anything.
All other functions return 1 on success, 0 on error.
=head1 HISTORY
The OpenSSL CMP support was added in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2007-2019 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (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
doc/man3/OSSL_CRMF_MSG_get0_tmpl.pod
+15
View File
@@ -5,6 +5,8 @@
OSSL_CRMF_MSG_get0_tmpl,
OSSL_CRMF_CERTTEMPLATE_get0_serialNumber,
OSSL_CRMF_CERTTEMPLATE_get0_issuer,
OSSL_CRMF_CERTID_get0_serialNumber,
OSSL_CRMF_CERTID_get0_issuer,
OSSL_CRMF_ENCRYPTEDVALUE_get1_encCert,
OSSL_CRMF_MSG_get_certReqId
- functions reading from CRMF CertReqMsg structures
@@ -18,6 +20,9 @@ OSSL_CRMF_MSG_get_certReqId
*OSSL_CRMF_CERTTEMPLATE_get0_serialNumber(OSSL_CRMF_CERTTEMPLATE *tmpl);
X509_NAME *OSSL_CRMF_CERTTEMPLATE_get0_issuer(OSSL_CRMF_CERTTEMPLATE *tmpl);
ASN1_INTEGER *OSSL_CRMF_CERTID_get0_serialNumber(const OSSL_CRMF_CERTID *cid);
X509_NAME *OSSL_CRMF_CERTID_get0_issuer(const OSSL_CRMF_CERTID *cid);
X509 *OSSL_CRMF_ENCRYPTEDVALUE_get1_encCert(OSSL_CRMF_ENCRYPTEDVALUE *ecert,
EVP_PKEY *pkey);
@@ -34,6 +39,12 @@ given certificate template B<tmpl>.
OSSL_CRMF_CERTTEMPLATE_get0_issuer() retrieves the issuer name of the
given certificate template B<tmpl>.
OSSL_CRMF_CERTID_get0_serialNumber retrieves the serialNumber
of the given CertId B<cid>.
OSSL_CRMF_CERTID_get0_issuer retrieves the issuer name
of the given CertId B<cid>, which must be of ASN.1 type GEN_DIRNAME.
OSSL_CRMF_ENCRYPTEDVALUE_get1_encCert() decrypts the certificate in the given
encryptedValue B<ecert>, using the private key B<pkey>.
This is needed for the indirect PoP method as in RFC 4210 section 5.2.8.2.
@@ -54,6 +65,10 @@ All other functions return a pointer with the intended result or NULL on error.
B<RFC 4211>
=head1 HISTORY
The OpenSSL CRMF support was added in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2007-2019 The OpenSSL Project Authors. All Rights Reserved.
doc/man3/OSSL_CRMF_MSG_set1_regCtrl_regToken.pod
+5 -1
View File
@@ -69,7 +69,7 @@ control in the given B<msg> copying the given B<tok> as value. See RFC 4211,
section 6.3.
OSSL_CRMF_MSG_set1_regCtrl_protocolEncrKey() sets the protocolEncrKey control in
the given B<msg> copying the given B<pubkey> as value. See RFC 4211, section 6.6.
the given B<msg> copying the given B<pubkey> as value. See RFC 4211 section 6.6.
OSSL_CRMF_MSG_set1_regCtrl_oldCertID() sets the oldCertID control in the given
B<msg> copying the given B<cid> as value. See RFC 4211, section 6.5.
@@ -94,6 +94,10 @@ create the needed OSSL_CRMF_PKIARCHIVEOPTINS content.
RFC 4211
=head1 HISTORY
The OpenSSL CRMF support was added in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2007-2019 The OpenSSL Project Authors. All Rights Reserved.
doc/man3/OSSL_CRMF_MSG_set1_regInfo_certReq.pod
+4
View File
@@ -37,6 +37,10 @@ multiple utf8Pairs in one regInfo structure, it does not allow multiple certReq.
RFC 4211
=head1 HISTORY
The OpenSSL CRMF support was added in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2007-2019 The OpenSSL Project Authors. All Rights Reserved.
doc/man3/OSSL_CRMF_MSG_set_validity.pod
+10 -7
View File
@@ -25,11 +25,9 @@ OSSL_CRMF_MSGS_verify_popo
const X509_NAME *issuer,
const ASN1_INTEGER *serial);
int OSSL_CRMF_MSG_set0_extensions(OSSL_CRMF_MSG *crm,
X509_EXTENSIONS *exts);
int OSSL_CRMF_MSG_set0_extensions(OSSL_CRMF_MSG *crm, X509_EXTENSIONS *exts);
int OSSL_CRMF_MSG_push0_extension(OSSL_CRMF_MSG *crm,
const X509_EXTENSION *ext);
int OSSL_CRMF_MSG_push0_extension(OSSL_CRMF_MSG *crm, X509_EXTENSION *ext);
int OSSL_CRMF_MSG_create_popo(OSSL_CRMF_MSG *crm, EVP_PKEY *pkey,
int dgst, int ppmtd);
@@ -56,9 +54,10 @@ certTemplate of B<crm>. Frees any pre-existing ones and consumes B<exts>.
OSSL_CRMF_MSG_push0_extension() pushes the X509 extension B<ext> to the
extensions in the certTemplate of B<crm>. Consumes B<ext>.
OSSL_CRMF_MSG_create_popo() creates and sets the Proof-of-Possession (POP)
according to the method B<ppmtd> for B<pkey> to B<crm>. In case the method is
OSSL_CRMF_POPO_SIGNATURE, POP is calculated using the B<dgst>.
OSSL_CRMF_MSG_create_popo() creates and sets the Proof-of-Possession (POPO)
according to the method B<ppmtd> in B<crm>.
In case the method is OSSL_CRMF_POPO_SIGNATURE the POPO is calculated
using the private B<pkey> and the digest algorithm NID B<dgst>.
B<ppmtd> can be one of the following:
@@ -93,6 +92,10 @@ All functions return 1 on success, 0 on error.
RFC 4211
=head1 HISTORY
The OpenSSL CRMF support was added in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2007-2019 The OpenSSL Project Authors. All Rights Reserved.
doc/man3/OSSL_CRMF_pbmp_new.pod
+4
View File
@@ -66,6 +66,10 @@ structure, or NULL on error.
RFC 4211 section 4.4
=head1 HISTORY
The OpenSSL CRMF support was added in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2007-2019 The OpenSSL Project Authors. All Rights Reserved.
doc/man3/OSSL_PARAM.pod
+5
View File
@@ -87,6 +87,11 @@ setting parameters) or shall (when requesting parameters) be stored,
and I<data_size> is its size in bytes.
The organization of the data depends on the parameter type and flag.
When I<requesting parameters>, it's acceptable for I<data> to be NULL.
This can be used by the I<requestor> to figure out dynamically exactly
how much buffer space is needed to store the parameter data.
In this case, I<data_size> is ignored.
When the B<OSSL_PARAM> is used as a parameter descriptor, I<data>
should be ignored.
If I<data_size> is zero, it means that an arbitrary data size is
doc/man3/OSSL_PARAM_construct_from_text.pod
+1 -1
View File
@@ -120,7 +120,7 @@ Can be written like this instead:
OSSL_PARAM *params =
OPENSSL_zalloc(sizeof(*params)
* (sk_OPENSSL_STRING_num(opts) + 1));
const OSSL_PARAM *paramdefs = EVP_MAC_CTX_settable_params(mac);
const OSSL_PARAM *paramdefs = EVP_MAC_settable_ctx_params(mac);
size_t params_n;
char *opt = "<unknown>";
doc/man3/OSSL_PARAM_int.pod
+12 -4
View File
@@ -32,7 +32,7 @@ OSSL_PARAM_set_octet_ptr
=head1 SYNOPSIS
=for comment generic
=for openssl generic
#include <openssl/params.h>
@@ -198,6 +198,8 @@ Type coercion takes place as discussed in the NOTES section.
OSSL_PARAM_set_TYPE() stores a value B<val> of type B<TYPE> into the parameter
B<p>.
If the parameter's I<data> field is NULL, then only its I<return_size> field
will be assigned the size the parameter's I<data> buffer should have.
Type coercion takes place as discussed in the NOTES section.
OSSL_PARAM_get_BN() retrieves a BIGNUM from the parameter pointed to by B<p>.
@@ -205,6 +207,8 @@ The BIGNUM referenced by B<val> is updated and is allocated if B<*val> is
B<NULL>.
OSSL_PARAM_set_BN() stores the BIGNUM B<val> into the parameter B<p>.
If the parameter's I<data> field is NULL, then only its I<return_size> field
will be assigned the size the parameter's I<data> buffer should have.
OSSL_PARAM_get_utf8_string() retrieves a UTF8 string from the parameter
pointed to by B<p>.
@@ -215,6 +219,8 @@ If memory is allocated by this function, it must be freed by the caller.
OSSL_PARAM_set_utf8_string() sets a UTF8 string from the parameter pointed to
by B<p> to the value referenced by B<val>.
If the parameter's I<data> field is NULL, then only its I<return_size> field
will be assigned the size the parameter's I<data> buffer should have.
OSSL_PARAM_get_octet_string() retrieves an OCTET string from the parameter
pointed to by B<p>.
@@ -225,6 +231,8 @@ If memory is allocated by this function, it must be freed by the caller.
OSSL_PARAM_set_octet_string() sets an OCTET string from the parameter
pointed to by B<p> to the value referenced by B<val>.
If the parameter's I<data> field is NULL, then only its I<return_size> field
will be assigned the size the parameter's I<data> buffer should have.
OSSL_PARAM_get_utf8_ptr() retrieves the UTF8 string pointer from the parameter
referenced by B<p> and stores it in B<*val>.
@@ -260,9 +268,9 @@ representable by the target type or parameter.
Apart from that, the functions must be used appropriately for the
expected type of the parameter.
For OSSL_PARAM_get_utf8_ptr() and OSSL_PARAM_get_octet_ptr(), B<bsize>
is not relevant if the purpose is to send the B<OSSL_PARAM> array to a
I<responder>, i.e. to get parameter data back.
For OSSL_PARAM_construct_utf8_ptr() and OSSL_PARAM_consstruct_octet_ptr(),
B<bsize> is not relevant if the purpose is to send the B<OSSL_PARAM> array
to a I<responder>, i.e. to get parameter data back.
In that case, B<bsize> can safely be given zero.
See L<OSSL_PARAM(3)/DESCRIPTION> for further information on the
possible purposes.
doc/man3/OSSL_trace_enabled.pod
+1 -1
View File
@@ -12,7 +12,7 @@ OSSL_TRACE_ENABLED
=head1 SYNOPSIS
=for comment generic
=for openssl generic
#include <openssl/trace.h>
doc/man3/OSSL_trace_set_channel.pod
+1 -1
View File
@@ -1,6 +1,6 @@
=pod
=for comment foreign manuals: atexit(3)
=for openssl foreign manuals: atexit(3)
=head1 NAME
doc/man3/OpenSSL_version.pod
+1 -1
View File
@@ -168,7 +168,7 @@ The configured dynamically loadable module extension.
=item OPENSSL_INFO_DIR_FILENAME_SEPARATOR
The separator between a directory specification and a file name.
The separator between a directory specification and a filename.
Note that on some operating systems, this is not the same as the
separator between directory elements.
doc/man3/PEM_bytes_read_bio.pod
+2 -2
View File
@@ -17,7 +17,8 @@ PEM_bytes_read_bio, PEM_bytes_read_bio_secmem - read a PEM-encoded data structur
=head1 DESCRIPTION
PEM_bytes_read_bio() reads PEM-formatted (RFC 1421) data from the BIO
PEM_bytes_read_bio() reads PEM-formatted (IETF RFC 1421 and IETF RFC 7468)
data from the BIO
I<bp> for the data type given in I<name> (RSA PRIVATE KEY, CERTIFICATE,
etc.). If multiple PEM-encoded data structures are present in the same
stream, PEM_bytes_read_bio() will skip non-matching data types and
@@ -66,7 +67,6 @@ PEM_bytes_read_bio() and PEM_bytes_read_bio_secmem() return 1 for success or
=head1 SEE ALSO
L<PEM(3)>,
L<PEM_read_bio_ex(3)>,
L<passphrase-encoding(7)>
doc/man3/PEM_read_CMS.pod
+15 -12
View File
@@ -40,7 +40,7 @@ PEM_write_bio_SSL_SESSION
=head1 SYNOPSIS
=for comment generic
=for openssl generic
#include <openssl/pem.h>
@@ -53,8 +53,8 @@ PEM_write_bio_SSL_SESSION
=head1 DESCRIPTION
In the description below, I<TYPE> is used
as a placeholder for any of the OpenSSL datatypes, such as I<X509>.
In the description below, B<I<TYPE>> is used
as a placeholder for any of the OpenSSL datatypes, such as B<X509>.
The macro B<DECLARE_PEM_rw> expands to the set of declarations shown in
the next four lines of the synopsis.
@@ -63,15 +63,17 @@ the PEM encoding. For more information on the templates, see
L<ASN1_ITEM(3)>. For more information on the lower-level routines used
by the functions here, see L<PEM_read(3)>.
PEM_read_TYPE() reads a PEM-encoded object of I<TYPE> from the file B<fp>
and returns it. The B<cb> and B<u> parameters are as described in
B<PEM_read_I<TYPE>>() reads a PEM-encoded object of B<I<TYPE>> from the file
I<fp> and returns it. The I<cb> and I<u> parameters are as described in
L<pem_password_cb(3)>.
PEM_read_bio_TYPE() is similar to PEM_read_TYPE() but reads from the BIO B<bp>.
B<PEM_read_bio_I<TYPE>>() is similar to B<PEM_read_I<TYPE>>() but reads from
the BIO I<bp>.
PEM_write_TYPE() writes the PEM encoding of the object B<a> to the file B<fp>.
B<PEM_write_I<TYPE>>() writes the PEM encoding of the object I<a> to the file
I<fp>.
PEM_write_bio_TYPE() similarly writes to the BIO B<bp>.
B<PEM_write_bio_I<TYPE>>() similarly writes to the BIO I<bp>.
=head1 NOTES
@@ -81,11 +83,12 @@ It will simply be treated as a byte sequence.
=head1 RETURN VALUES
PEM_read_TYPE() and PEM_read_bio_TYPE() return a pointer to an allocated
object, which should be released by calling TYPE_free(), or NULL on error.
B<PEM_read_I<TYPE>>() and B<PEM_read_bio_I<TYPE>>() return a pointer to an
allocated object, which should be released by calling B<I<TYPE>_free>(), or
NULL on error.
PEM_write_TYPE() and PEM_write_bio_TYPE() return the number of bytes written
or zero on error.
B<PEM_write_I<TYPE>>() and B<PEM_write_bio_I<TYPE>>() return the number of bytes
written or zero on error.
=head1 SEE ALSO
doc/man3/PEM_read_bio_PrivateKey.pod
+44 -34
View File
@@ -15,7 +15,8 @@ PEM_write_RSAPublicKey, PEM_read_bio_RSA_PUBKEY, PEM_read_RSA_PUBKEY,
PEM_write_bio_RSA_PUBKEY, PEM_write_RSA_PUBKEY, PEM_read_bio_DSAPrivateKey,
PEM_read_DSAPrivateKey, PEM_write_bio_DSAPrivateKey, PEM_write_DSAPrivateKey,
PEM_read_bio_DSA_PUBKEY, PEM_read_DSA_PUBKEY, PEM_write_bio_DSA_PUBKEY,
PEM_write_DSA_PUBKEY, PEM_read_bio_DSAparams, PEM_read_DSAparams,
PEM_write_DSA_PUBKEY, PEM_read_bio_Parameters, PEM_write_bio_Parameters,
PEM_read_bio_DSAparams, PEM_read_DSAparams,
PEM_write_bio_DSAparams, PEM_write_DSAparams, PEM_read_bio_DHparams,
PEM_read_DHparams, PEM_write_bio_DHparams, PEM_write_DHparams,
PEM_read_bio_X509, PEM_read_X509, PEM_write_bio_X509, PEM_write_X509,
@@ -109,6 +110,9 @@ PEM_write_bio_PKCS7, PEM_write_PKCS7 - PEM routines
int PEM_write_bio_DSA_PUBKEY(BIO *bp, DSA *x);
int PEM_write_DSA_PUBKEY(FILE *fp, DSA *x);
EVP_PKEY *PEM_read_bio_Parameters(BIO *bp, EVP_PKEY **x);
int PEM_write_bio_Parameters(BIO *bp, const EVP_PKEY *x);
DSA *PEM_read_bio_DSAparams(BIO *bp, DSA **x, pem_password_cb *cb, void *u);
DSA *PEM_read_DSAparams(FILE *fp, DSA **x, pem_password_cb *cb, void *u);
int PEM_write_bio_DSAparams(BIO *bp, DSA *x);
@@ -160,9 +164,9 @@ For more details about the meaning of arguments see the
B<PEM FUNCTION ARGUMENTS> section.
Each operation has four functions associated with it. For
brevity the term "B<TYPE> functions" will be used below to collectively
refer to the PEM_read_bio_TYPE(), PEM_read_TYPE(),
PEM_write_bio_TYPE(), and PEM_write_TYPE() functions.
brevity the term "B<I<TYPE>> functions" will be used below to collectively
refer to the B<PEM_read_bio_I<TYPE>>(), B<PEM_read_I<TYPE>>(),
B<PEM_write_bio_I<TYPE>>(), and B<PEM_write_I<TYPE>>() functions.
The B<PrivateKey> functions read or write a private key in PEM format using an
EVP_PKEY structure. The write routines use PKCS#8 private key format and are
@@ -175,16 +179,16 @@ be used for compatibility with legacy programs.
PEM_write_bio_PKCS8PrivateKey() and PEM_write_PKCS8PrivateKey() write a private
key in an EVP_PKEY structure in PKCS#8 EncryptedPrivateKeyInfo format using
PKCS#5 v2.0 password based encryption algorithms. The B<cipher> argument
PKCS#5 v2.0 password based encryption algorithms. The I<cipher> argument
specifies the encryption algorithm to use: unlike some other PEM routines the
encryption is applied at the PKCS#8 level and not in the PEM headers. If
B<cipher> is NULL then no encryption is used and a PKCS#8 PrivateKeyInfo
I<cipher> is NULL then no encryption is used and a PKCS#8 PrivateKeyInfo
structure is used instead.
PEM_write_bio_PKCS8PrivateKey_nid() and PEM_write_PKCS8PrivateKey_nid()
also write out a private key as a PKCS#8 EncryptedPrivateKeyInfo however
it uses PKCS#5 v1.5 or PKCS#12 encryption algorithms instead. The algorithm
to use is specified in the B<nid> parameter and should be the NID of the
to use is specified in the I<nid> parameter and should be the NID of the
corresponding OBJECT IDENTIFIER (see NOTES section).
The B<PUBKEY> functions process a public key using an EVP_PKEY
@@ -215,6 +219,12 @@ a DSA structure. The public key is encoded using a
SubjectPublicKeyInfo structure and an error occurs if the public
key is not DSA.
The B<Parameters> functions read or write key parameters in PEM format using
an EVP_PKEY structure. The encoding depends on the type of key; for DSA key
parameters, it will be a Dss-Parms structure as defined in RFC2459, and for DH
key parameters, it will be a PKCS#3 DHparameter structure. I<These functions
only exist for the B<BIO> type>.
The B<DSAparams> functions process DSA parameters using a DSA
structure. The parameters are encoded using a Dss-Parms structure
as defined in RFC2459.
@@ -247,36 +257,36 @@ structure.
The PEM functions have many common arguments.
The B<bp> BIO parameter (if present) specifies the BIO to read from
The I<bp> BIO parameter (if present) specifies the BIO to read from
or write to.
The B<fp> FILE parameter (if present) specifies the FILE pointer to
The I<fp> FILE parameter (if present) specifies the FILE pointer to
read from or write to.
The PEM read functions all take an argument B<TYPE **x> and return
a B<TYPE *> pointer. Where B<TYPE> is whatever structure the function
uses. If B<x> is NULL then the parameter is ignored. If B<x> is not
NULL but B<*x> is NULL then the structure returned will be written
to B<*x>. If neither B<x> nor B<*x> is NULL then an attempt is made
to reuse the structure at B<*x> (but see BUGS and EXAMPLES sections).
Irrespective of the value of B<x> a pointer to the structure is always
The PEM read functions all take an argument I<B<TYPE> **x> and return
a I<B<TYPE> *> pointer. Where I<B<TYPE>> is whatever structure the function
uses. If I<x> is NULL then the parameter is ignored. If I<x> is not
NULL but I<*x> is NULL then the structure returned will be written
to I<*x>. If neither I<x> nor I<*x> is NULL then an attempt is made
to reuse the structure at I<*x> (but see BUGS and EXAMPLES sections).
Irrespective of the value of I<x> a pointer to the structure is always
returned (or NULL if an error occurred).
The PEM functions which write private keys take an B<enc> parameter
The PEM functions which write private keys take an I<enc> parameter
which specifies the encryption algorithm to use, encryption is done
at the PEM level. If this parameter is set to NULL then the private
key is written in unencrypted form.
The B<cb> argument is the callback to use when querying for the pass
The I<cb> argument is the callback to use when querying for the pass
phrase used for encrypted PEM structures (normally only private keys).
For the PEM write routines if the B<kstr> parameter is not NULL then
B<klen> bytes at B<kstr> are used as the passphrase and B<cb> is
For the PEM write routines if the I<kstr> parameter is not NULL then
I<klen> bytes at I<kstr> are used as the passphrase and I<cb> is
ignored.
If the B<cb> parameters is set to NULL and the B<u> parameter is not
NULL then the B<u> parameter is interpreted as a null terminated string
to use as the passphrase. If both B<cb> and B<u> are NULL then the
If the I<cb> parameters is set to NULL and the I<u> parameter is not
NULL then the I<u> parameter is interpreted as a null terminated string
to use as the passphrase. If both I<cb> and I<u> are NULL then the
default callback routine is used which will typically prompt for the
passphrase on the current terminal with echoing turned off.
@@ -286,15 +296,15 @@ routine has the following form:
int cb(char *buf, int size, int rwflag, void *u);
B<buf> is the buffer to write the passphrase to. B<size> is the maximum
length of the passphrase (i.e. the size of buf). B<rwflag> is a flag
I<buf> is the buffer to write the passphrase to. I<size> is the maximum
length of the passphrase (i.e. the size of buf). I<rwflag> is a flag
which is set to 0 when reading and 1 when writing. A typical routine
will ask the user to verify the passphrase (for example by prompting
for it twice) if B<rwflag> is 1. The B<u> parameter has the same
value as the B<u> parameter passed to the PEM routine. It allows
for it twice) if I<rwflag> is 1. The I<u> parameter has the same
value as the I<u> parameter passed to the PEM routine. It allows
arbitrary data to be passed to the callback by the application
(for example a window handle in a GUI application). The callback
B<must> return the number of characters in the passphrase or -1 if
I<must> return the number of characters in the passphrase or -1 if
an error occurred.
=head1 NOTES
@@ -316,7 +326,7 @@ this:
PEM_read_bio_X509(bp, &x, 0, NULL);
this is a bug because an attempt will be made to reuse the data at B<x>
this is a bug because an attempt will be made to reuse the data at I<x>
which is an uninitialised pointer.
These functions make no assumption regarding the pass phrase received from the
@@ -344,15 +354,15 @@ cipher encoded as a set of hexadecimal digits. After those two lines is
the base64-encoded encrypted data.
The encryption key is derived using EVP_BytesToKey(). The cipher's
initialization vector is passed to EVP_BytesToKey() as the B<salt>
initialization vector is passed to EVP_BytesToKey() as the I<salt>
parameter. Internally, B<PKCS5_SALT_LEN> bytes of the salt are used
(regardless of the size of the initialization vector). The user's
password is passed to EVP_BytesToKey() using the B<data> and B<datal>
password is passed to EVP_BytesToKey() using the I<data> and I<datal>
parameters. Finally, the library uses an iteration count of 1 for
EVP_BytesToKey().
The B<key> derived by EVP_BytesToKey() along with the original initialization
vector is then used to decrypt the encrypted data. The B<iv> produced by
The I<key> derived by EVP_BytesToKey() along with the original initialization
vector is then used to decrypt the encrypted data. The I<iv> produced by
EVP_BytesToKey() is not utilized or needed, and NULL should be passed to
the function.
@@ -380,7 +390,7 @@ an existing structure. Therefore the following:
PEM_read_bio_X509(bp, &x, 0, NULL);
where B<x> already contains a valid certificate, may not work, whereas:
where I<x> already contains a valid certificate, may not work, whereas:
X509_free(x);
x = PEM_read_bio_X509(bp, NULL, 0, NULL);
doc/man3/PEM_read_bio_ex.pod
+1 -1
View File
@@ -52,7 +52,7 @@ PEM_read_bio_ex() returns 1 for success or 0 for failure.
=head1 SEE ALSO
L<PEM(3)>
L<PEM_bytes_read_bio(3)>
=head1 HISTORY
doc/man3/PKCS7_verify.pod
+1 -1
View File
@@ -85,7 +85,7 @@ certificates supplied in B<certs> then the verify will fail because the
signer cannot be found.
Care should be taken when modifying the default verify behaviour, for example
setting B<PKCS7_NOVERIFY|PKCS7_NOSIGS> will totally disable all verification
setting C<PKCS7_NOVERIFY|PKCS7_NOSIGS> will totally disable all verification
and any signed message 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.
doc/man3/RAND_add.pod
+1 -1
View File
@@ -67,7 +67,7 @@ usage by the random seed sources. Some seed sources maintain open file
descriptors by default, which allows such sources to operate in a
chroot(2) jail without the associated device nodes being available. When
the B<keep> argument is zero, this call disables the retention of file
descriptors. Conversely, a non-zero argument enables the retention of
descriptors. Conversely, a nonzero argument enables the retention of
file descriptors. This function is usually called during initialization
and it takes effect immediately.
doc/man3/RAND_load_file.pod
+2 -2
View File
@@ -37,7 +37,7 @@ file. B<buf> points to a buffer of size B<num> in which to store the
filename.
On all systems, if the environment variable B<RANDFILE> is set, its
value will be used as the seed file name.
value will be used as the seed filename.
Otherwise, the file is called C<.rnd>, found in platform dependent locations:
=over 4
@@ -57,7 +57,7 @@ Otherwise, the file is called C<.rnd>, found in platform dependent locations:
=back
If C<$HOME> (on non-Windows and non-VMS system) is not set either, or
B<num> is too small for the path name, an error occurs.
B<num> is too small for the pathname, an error occurs.
=head1 RETURN VALUES
doc/man3/RSA_set_method.pod
+1 -1
View File
@@ -129,7 +129,7 @@ the default method is used.
const unsigned char *m, unsigned int m_length,
const unsigned char *sigbuf, unsigned int siglen,
const RSA *rsa);
/* keygen. If NULL builtin RSA key generation will be used */
/* keygen. If NULL built-in RSA key generation will be used */
int (*rsa_keygen)(RSA *rsa, int bits, BIGNUM *e, BN_GENCB *cb);
} RSA_METHOD;
doc/man3/SCT_new.pod
+3 -2
View File
@@ -108,7 +108,8 @@ See RFC 6962, Section 3.2 for the definition of LogID.
=item *
SCT_set_timestamp() to set the time the SCT was issued (epoch time in milliseconds).
SCT_set_timestamp() to set the time the SCT was issued (time in milliseconds
since the Unix Epoch).
=item *
@@ -149,7 +150,7 @@ B<CT_LOG_ENTRY_TYPE_PRECERT> for a pre-certificate.
=item *
The time that the SCT was issued (epoch time in milliseconds).
The time that the SCT was issued (time in milliseconds since the Unix Epoch).
=item *
doc/man3/SSL_CONF_cmd.pod
+1 -1
View File
@@ -549,7 +549,7 @@ The value is a string without any specific structure.
=item B<SSL_CONF_TYPE_FILE>
The value is a file name.
The value is a filename.
=item B<SSL_CONF_TYPE_DIR>
doc/man3/SSL_CTX_dane_enable.pod
+1 -1
View File
@@ -136,7 +136,7 @@ SSL_CTX_dane_set_flags() and SSL_dane_set_flags() can be used to enable
optional DANE verification features.
SSL_CTX_dane_clear_flags() and SSL_dane_clear_flags() can be used to disable
the same features.
The B<flags> argument is a bitmask of the features to enable or disable.
The B<flags> argument is a bit-mask of the features to enable or disable.
The B<flags> set for an B<SSL_CTX> context are copied to each B<SSL> handle
associated with that context at the time the handle is created.
Subsequent changes in the context's B<flags> have no effect on the B<flags> set
doc/man3/SSL_CTX_set_client_hello_cb.pod
+1 -1
View File
@@ -26,7 +26,7 @@ SSL_CTX_set_client_hello_cb, SSL_client_hello_cb_fn, SSL_client_hello_isv2, SSL_
SSL_CTX_set_client_hello_cb() sets the callback function, which is automatically
called during the early stages of ClientHello processing on the server.
The argument supplied when setting the callback is passed back to the
callback at runtime. A callback that returns failure (0) will cause the
callback at run time. A callback that returns failure (0) will cause the
connection to terminate, and callbacks returning failure should indicate
what alert value is to be sent in the B<al> parameter. A callback may
also return a negative value to suspend the handshake, and the handshake
doc/man3/SSL_CTX_set_info_callback.pod
+1 -1
View File
@@ -50,7 +50,7 @@ the callback function was called. If B<ret> is 0, an error condition occurred.
If an alert is handled, SSL_CB_ALERT is set and B<ret> specifies the alert
information.
B<where> is a bitmask made up of the following bits:
B<where> is a bit-mask made up of the following bits:
=over 4
doc/man3/SSL_CTX_set_mode.pod
+6 -6
View File
@@ -18,13 +18,13 @@ SSL_CTX_set_mode, SSL_CTX_clear_mode, SSL_set_mode, SSL_clear_mode, SSL_CTX_get_
=head1 DESCRIPTION
SSL_CTX_set_mode() adds the mode set via bitmask in B<mode> to B<ctx>.
SSL_CTX_set_mode() adds the mode set via bit-mask in B<mode> to B<ctx>.
Options already set before are not cleared.
SSL_CTX_clear_mode() removes the mode set via bitmask in B<mode> from B<ctx>.
SSL_CTX_clear_mode() removes the mode set via bit-mask in B<mode> from B<ctx>.
SSL_set_mode() adds the mode set via bitmask in B<mode> to B<ssl>.
SSL_set_mode() adds the mode set via bit-mask in B<mode> to B<ssl>.
Options already set before are not cleared.
SSL_clear_mode() removes the mode set via bitmask in B<mode> from B<ssl>.
SSL_clear_mode() removes the mode set via bit-mask in B<mode> from B<ssl>.
SSL_CTX_get_mode() returns the mode set for B<ctx>.
@@ -137,10 +137,10 @@ default since 1.1.1.
=head1 RETURN VALUES
SSL_CTX_set_mode() and SSL_set_mode() return the new mode bitmask
SSL_CTX_set_mode() and SSL_set_mode() return the new mode bit-mask
after adding B<mode>.
SSL_CTX_get_mode() and SSL_get_mode() return the current bitmask.
SSL_CTX_get_mode() and SSL_get_mode() return the current bit-mask.
=head1 SEE ALSO
doc/man3/SSL_CTX_set_options.pod
+8 -8
View File
@@ -23,16 +23,16 @@ SSL_get_secure_renegotiation_support - manipulate SSL options
=head1 DESCRIPTION
SSL_CTX_set_options() adds the options set via bitmask in B<options> to B<ctx>.
SSL_CTX_set_options() adds the options set via bit-mask in B<options> to B<ctx>.
Options already set before are not cleared!
SSL_set_options() adds the options set via bitmask in B<options> to B<ssl>.
SSL_set_options() adds the options set via bit-mask in B<options> to B<ssl>.
Options already set before are not cleared!
SSL_CTX_clear_options() clears the options set via bitmask in B<options>
SSL_CTX_clear_options() clears the options set via bit-mask in B<options>
to B<ctx>.
SSL_clear_options() clears the options set via bitmask in B<options> to B<ssl>.
SSL_clear_options() clears the options set via bit-mask in B<options> to B<ssl>.
SSL_CTX_get_options() returns the options set for B<ctx>.
@@ -45,7 +45,7 @@ Note, this is implemented via a macro.
=head1 NOTES
The behaviour of the SSL library can be changed by setting several options.
The options are coded as bitmasks and can be combined by a bitwise B<or>
The options are coded as bit-masks and can be combined by a bitwise B<or>
operation (|).
SSL_CTX_set_options() and SSL_set_options() affect the (external)
@@ -348,13 +348,13 @@ and renegotiation between OpenSSL and unpatched clients or servers.
=head1 RETURN VALUES
SSL_CTX_set_options() and SSL_set_options() return the new options bitmask
SSL_CTX_set_options() and SSL_set_options() return the new options bit-mask
after adding B<options>.
SSL_CTX_clear_options() and SSL_clear_options() return the new options bitmask
SSL_CTX_clear_options() and SSL_clear_options() return the new options bit-mask
after clearing B<options>.
SSL_CTX_get_options() and SSL_get_options() return the current bitmask.
SSL_CTX_get_options() and SSL_get_options() return the current bit-mask.
SSL_get_secure_renegotiation_support() returns 1 is the peer supports
secure renegotiation and 0 if it does not.
doc/man3/SSL_CTX_set_stateless_cookie_generate_cb.pod
+52 -15
View File
@@ -3,7 +3,9 @@
=head1 NAME
SSL_CTX_set_stateless_cookie_generate_cb,
SSL_CTX_set_stateless_cookie_verify_cb
SSL_CTX_set_stateless_cookie_verify_cb,
SSL_CTX_set_cookie_generate_cb,
SSL_CTX_set_cookie_verify_cb
- Callback functions for stateless TLS1.3 cookies
=head1 SYNOPSIS
@@ -21,22 +23,51 @@ SSL_CTX_set_stateless_cookie_verify_cb
const unsigned char *cookie,
size_t cookie_len));
void SSL_CTX_set_cookie_generate_cb(SSL_CTX *ctx,
int (*app_gen_cookie_cb) (SSL *ssl,
unsigned char
*cookie,
unsigned int
*cookie_len));
void SSL_CTX_set_cookie_verify_cb(SSL_CTX *ctx,
int (*app_verify_cookie_cb) (SSL *ssl,
const unsigned
char *cookie,
unsigned int
cookie_len));
=head1 DESCRIPTION
SSL_CTX_set_cookie_generate_cb() sets the callback used by L<SSL_stateless(3)>
to generate the application-controlled portion of the cookie provided to clients
in the HelloRetryRequest transmitted as a response to a ClientHello with a
missing or invalid cookie. gen_stateless_cookie_cb() must write at most
SSL_COOKIE_LENGTH bytes into B<cookie>, and must write the number of bytes
written to B<cookie_len>. If a cookie cannot be generated, a zero return value
can be used to abort the handshake.
SSL_CTX_set_stateless_cookie_generate_cb() sets the callback used by
L<SSL_stateless(3)> to generate the application-controlled portion of the cookie
provided to clients in the HelloRetryRequest transmitted as a response to a
ClientHello with a missing or invalid cookie. gen_stateless_cookie_cb() must
write at most SSL_COOKIE_LENGTH bytes into B<cookie>, and must write the number
of bytes written to B<cookie_len>. If a cookie cannot be generated, a zero
return value can be used to abort the handshake.
SSL_CTX_set_cookie_verify_cb() sets the callback used by L<SSL_stateless(3)> to
determine whether the application-controlled portion of a ClientHello cookie is
valid. A nonzero return value from app_verify_cookie_cb() communicates that the
cookie is valid. The integrity of the entire cookie, including the
application-controlled portion, is automatically verified by HMAC before
verify_stateless_cookie_cb() is called.
SSL_CTX_set_stateless_cookie_verify_cb() sets the callback used by
L<SSL_stateless(3)> to determine whether the application-controlled portion of a
ClientHello cookie is valid. The cookie data is pointed to by B<cookie> and is of
length B<cookie_len>. A nonzero return value from verify_stateless_cookie_cb()
communicates that the cookie is valid. The integrity of the entire cookie,
including the application-controlled portion, is automatically verified by HMAC
before verify_stateless_cookie_cb() is called.
SSL_CTX_set_cookie_generate_cb() sets the callback used by L<DTLSv1_listen(3)>
to generate the cookie provided to clients in the HelloVerifyRequest transmitted
as a response to a ClientHello with a missing or invalid cookie.
app_gen_cookie_cb() must write at most DTLS1_COOKIE_LENGTH bytes into
B<cookie>, and must write the number of bytes written to B<cookie_len>. If a
cookie cannot be generated, a zero return value can be used to abort the
handshake.
SSL_CTX_set_cookie_verify_cb() sets the callback used by L<DTLSv1_listen(3)> to
determine whether the cookie in a ClientHello is valid. The cookie data is
pointed to by B<cookie> and is of length B<cookie_len>. A nonzero return value
from app_verify_cookie_cb() communicates that the cookie is valid. The
integrity of the cookie is not verified by OpenSSL. This is an application
responsibility.
=head1 RETURN VALUES
@@ -44,7 +75,13 @@ Neither function returns a value.
=head1 SEE ALSO
L<SSL_stateless(3)>
L<SSL_stateless(3)>,
L<DTLSv1_listen(3)>
=head1 HISTORY
SSL_CTX_set_stateless_cookie_generate_cb() and
SSL_CTX_set_stateless_cookie_verify_cb() were added in OpenSSL 1.1.1.
=head1 COPYRIGHT
doc/man3/SSL_get_all_async_fds.pod
+16 -16
View File
@@ -9,7 +9,7 @@ SSL_get_changed_async_fds
=head1 SYNOPSIS
=for comment multiple includes
=for openssl multiple includes
#include <openssl/async.h>
#include <openssl/ssl.h>
@@ -22,32 +22,32 @@ SSL_get_changed_async_fds
=head1 DESCRIPTION
SSL_waiting_for_async() determines whether an SSL connection is currently
waiting for asynchronous operations to complete (see the SSL_MODE_ASYNC mode in
L<SSL_CTX_set_mode(3)>).
waiting for asynchronous operations to complete (see the B<SSL_MODE_ASYNC> mode
in L<SSL_CTX_set_mode(3)>).
SSL_get_all_async_fds() returns a list of file descriptor which can be used in a
call to select() or poll() to determine whether the current asynchronous
operation has completed or not. A completed operation will result in data
appearing as "read ready" on the file descriptor (no actual data should be read
from the file descriptor). This function should only be called if the SSL object
is currently waiting for asynchronous work to complete (i.e.
SSL_ERROR_WANT_ASYNC has been received - see L<SSL_get_error(3)>). Typically the
list will only contain one file descriptor. However if multiple asynchronous
from the file descriptor). This function should only be called if the B<SSL>
object is currently waiting for asynchronous work to complete (i.e.
B<SSL_ERROR_WANT_ASYNC> has been received - see L<SSL_get_error(3)>). Typically
the list will only contain one file descriptor. However if multiple asynchronous
capable engines are in use then more than one is possible. The number of file
descriptors returned is stored in B<*numfds> and the file descriptors themselves
are in B<*fds>. The B<fds> parameter may be NULL in which case no file
descriptors are returned but B<*numfds> is still populated. It is the callers
responsibility to ensure sufficient memory is allocated at B<*fds> so typically
this function is called twice (once with a NULL B<fds> parameter and once
descriptors returned is stored in I<*numfds> and the file descriptors themselves
are in I<*fds>. The I<fds> parameter may be NULL in which case no file
descriptors are returned but I<*numfds> is still populated. It is the callers
responsibility to ensure sufficient memory is allocated at I<*fds> so typically
this function is called twice (once with a NULL I<fds> parameter and once
without).
SSL_get_changed_async_fds() returns a list of the asynchronous file descriptors
that have been added and a list that have been deleted since the last
SSL_ERROR_WANT_ASYNC was received (or since the SSL object was created if no
SSL_ERROR_WANT_ASYNC has been received). Similar to SSL_get_all_async_fds() it
is the callers responsibility to ensure that B<*addfd> and B<*delfd> have
B<SSL_ERROR_WANT_ASYNC> was received (or since the B<SSL> object was created if
no B<SSL_ERROR_WANT_ASYNC> has been received). Similar to SSL_get_all_async_fds()
it is the callers responsibility to ensure that I<*addfd> and I<*delfd> have
sufficient memory allocated, although they may be NULL. The number of added fds
and the number of deleted fds are stored in B<*numaddfds> and B<*numdelfds>
and the number of deleted fds are stored in I<*numaddfds> and I<*numdelfds>
respectively.
=head1 RETURN VALUES
doc/man3/SSL_read_early_data.pod
+2 -2
View File
@@ -202,7 +202,7 @@ early data settings for the SSL_CTX and SSL objects respectively. Generally a
server application will either use both of SSL_read_early_data() and
SSL_CTX_set_max_early_data() (or SSL_set_max_early_data()), or neither of them,
since there is no practical benefit from using only one of them. If the maximum
early data setting for a server is non-zero then replay protection is
early data setting for a server is nonzero then replay protection is
automatically enabled (see L</REPLAY PROTECTION> below).
If the server rejects the early data sent by a client then it will skip over
@@ -285,7 +285,7 @@ retry with a lower maximum protocol version.
When early data is in use the TLS protocol provides no security guarantees that
the same early data was not replayed across multiple connections. As a
mitigation for this issue OpenSSL automatically enables replay protection if the
server is configured with a non-zero max early data value. With replay
server is configured with a nonzero max early data value. With replay
protection enabled sessions are forced to be single use only. If a client
attempts to reuse a session ticket more than once, then the second and
subsequent attempts will fall back to a full handshake (and any early data that
doc/man3/SSL_set1_host.pod
+1 -1
View File
@@ -19,7 +19,7 @@ SSL server verification parameters
These functions configure server hostname checks in the SSL client.
SSL_set1_host() sets the expected DNS hostname to B<name> clearing
any previously specified host name or names. If B<name> is NULL,
any previously specified hostname. If B<name> is NULL,
or the empty string the list of hostnames is cleared, and name
checks are not performed on the peer certificate. When a non-empty
B<name> is specified, certificate verification automatically checks
doc/man3/SSL_set_async_callback.pod
+52 -21
View File
@@ -12,7 +12,7 @@ SSL_async_callback_fn
=head1 SYNOPSIS
=for comment multiple includes
=for openssl multiple includes
#include <openssl/ssl.h>
@@ -25,53 +25,84 @@ SSL_async_callback_fn
=head1 DESCRIPTION
SSL_CTX_set_async_callback() sets an asynchronous callback function. All SSL
objects generated based on this SSL_CTX will get this callback. If an engine
SSL_CTX_set_async_callback() sets an asynchronous callback function. All B<SSL>
objects generated based on this B<SSL_CTX> will get this callback. If an engine
supports the callback mechanism, it will be automatically called if
SSL_MODE_ASYNC has been set and an asynchronous capable engine completes a
B<SSL_MODE_ASYNC> has been set and an asynchronous capable engine completes a
cryptography operation to notify the application to resume the paused work flow.
SSL_CTX_set_async_callback_arg() sets the callback argument.
SSL_set_async_callback() allows an application to set a callback in an
asynchronous SSL object, so that when an engine completes a cryptography
asynchronous B<SSL> object, so that when an engine completes a cryptography
operation, the callback will be called to notify the application to resume the
paused work flow.
SSL_set_async_callback_arg() sets an argument for the SSL object when the above
callback is called.
SSL_set_async_callback_arg() sets an argument for the B<SSL> object when the
above callback is called.
SSL_get_async_status() returns the engine status. This function facilitates the
communication from the engine to the application. During an SSL session,
cryptographic operations are dispatched to an engine. The engine status is very
useful for an application to know if the operation has been successfully
dispatched. If the engine does not support this additional callback method,
"ASYNC_STATUS_UNSUPPORTED" will be returned. See ASYNC_WAIT_CTX_set_status() for
a description of all of the status values.
B<ASYNC_STATUS_UNSUPPORTED> will be returned. See ASYNC_WAIT_CTX_set_status()
for a description of all of the status values.
An example of the above functions would be the following.
1. Application sets the async callback and callback data on an SSL connection
An example of the above functions would be the following:
=over 4
=item 1.
Application sets the async callback and callback data on an SSL connection
by calling SSL_set_async_callback().
2. Application sets SSL_MODE_ASYNC and makes an asynchronous SSL call
3. OpenSSL submits the asynchronous request to the engine. If a retry occurs at
this point then the status within the ASYNC_WAIT_CTX would be set and the async
callback function would be called (goto Step 7).
4. The OpenSSL engine pauses the current job and returns, so that the
=item 2.
Application sets B<SSL_MODE_ASYNC> and makes an asynchronous SSL call
=item 3.
OpenSSL submits the asynchronous request to the engine. If a retry occurs at
this point then the status within the B<ASYNC_WAIT_CTX> would be set and the
async callback function would be called (goto Step 7).
=item 4.
The OpenSSL engine pauses the current job and returns, so that the
application can continue processing other connections.
5. At a future point in time (probably via a polling mechanism or via an
=item 5.
At a future point in time (probably via a polling mechanism or via an
interrupt) the engine will become aware that the asynchronous request has
finished processing.
6. The engine will call the application's callback passing the callback data as
=item 6.
The engine will call the application's callback passing the callback data as
a parameter.
7. The callback function should then run. Note: it is a requirement that the
=item 7.
The callback function should then run. Note: it is a requirement that the
callback function is small and non-blocking as it will be run in the context of
a polling mechanism or an interrupt.
8. It is the application's responsibility via the callback function to schedule
=item 8.
It is the application's responsibility via the callback function to schedule
recalling the OpenSSL asynchronous function and to continue processing.
9. The callback function has the option to check the status returned via
=item 9.
The callback function has the option to check the status returned via
SSL_get_async_status() to determine whether a retry happened instead of the
request being submitted, allowing different processing if required.
=back
=head1 RETURN VALUES
SSL_CTX_set_async_callback(), SSL_set_async_callback(),
doc/man3/SSL_set_shutdown.pod
+1 -1
View File
@@ -20,7 +20,7 @@ SSL_get_shutdown() returns the shutdown mode of B<ssl>.
=head1 NOTES
The shutdown state of an ssl connection is a bitmask of:
The shutdown state of an ssl connection is a bit-mask of:
=over 4
doc/man3/UI_UTIL_read_pw.pod
+1 -1
View File
@@ -21,7 +21,7 @@ UI_UTIL_read_pw_string() asks for a passphrase, using B<prompt> as a
prompt, and stores it in B<buf>.
The maximum allowed size is given with B<length>, including the
terminating NUL byte.
If B<verify> is non-zero, the password will be verified as well.
If B<verify> is nonzero, the password will be verified as well.
UI_UTIL_read_pw() does the same as UI_UTIL_read_pw_string(), the
difference is that you can give it an external buffer B<buff> for the
doc/man3/UI_new.pod
+3 -3
View File
@@ -132,7 +132,7 @@ the possible answers (given through the I<action_desc> argument).
UI_add_info_string() and UI_add_error_string() add strings that are shown at
the same time as the prompt for extra information or to show an error string.
The difference between the two is only conceptual. With the builtin method,
The difference between the two is only conceptual. With the built-in method,
there's no technical difference between them. Other methods may make a
difference between them, however.
@@ -152,13 +152,13 @@ UI_construct_prompt() is a helper function that can be used to create
a prompt from two pieces of information: an description and a name.
The default constructor (if there is none provided by the method used)
creates a string "Enter I<description> for I<name>:". With the
description "pass phrase" and the file name "foo.key", that becomes
description "pass phrase" and the filename "foo.key", that becomes
"Enter pass phrase for foo.key:". Other methods may create whatever
string and may include encodings that will be processed by the other
method functions.
UI_add_user_data() adds a user data pointer for the method to use at any
time. The builtin UI method doesn't care about this info. Note that several
time. The built-in UI method doesn't care about this info. Note that several
calls to this function doesn't add data, it replaces the previous blob
with the one given as argument.
doc/man3/X509_ALGOR_dup.pod
+2 -2
View File
@@ -34,7 +34,7 @@ X509_ALGOR_set_md() sets the B<AlgorithmIdentifier> B<alg> to appropriate
values for the message digest B<md>.
X509_ALGOR_cmp() compares B<a> and B<b> and returns 0 if they have identical
encodings and non-zero otherwise.
encodings and nonzero otherwise.
=head1 RETURN VALUES
@@ -46,7 +46,7 @@ X509_ALGOR_set0() returns 1 on success or 0 on error.
X509_ALGOR_get0() and X509_ALGOR_set_md() return no values.
X509_ALGOR_cmp() returns 0 if the two parameters have identical encodings and
non-zero otherwise.
nonzero otherwise.
=head1 COPYRIGHT
doc/man3/X509_LOOKUP_hash_dir.pod
+1 -1
View File
@@ -80,7 +80,7 @@ upon each lookup, so that newer CRLs are as soon as they appear in
the directory.
The directory should contain one certificate or CRL per file in PEM format,
with a file name of the form I<hash>.I<N> for a certificate, or
with a filename of the form I<hash>.I<N> for a certificate, or
I<hash>.B<r>I<N> for a CRL.
The I<hash> is the value returned by the L<X509_NAME_hash(3)> function applied
to the subject name for certificates or issuer name for CRLs.

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