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

Imported OpenSSL 1.1.1a

Browse Source
This commit is contained in:
Steve Dower
2019-02-08 14:45:21 -08:00
parent 66bc075dac
commit d6b2cd4920
3033 changed files with 1039677 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

179
doc/man3/ADMISSIONS.pod Normal file
View File

@@ -0,0 +1,179 @@
=pod
=head1 NAME
ADMISSIONS,
ADMISSIONS_get0_admissionAuthority,
ADMISSIONS_get0_namingAuthority,
ADMISSIONS_get0_professionInfos,
ADMISSIONS_set0_admissionAuthority,
ADMISSIONS_set0_namingAuthority,
ADMISSIONS_set0_professionInfos,
ADMISSION_SYNTAX,
ADMISSION_SYNTAX_get0_admissionAuthority,
ADMISSION_SYNTAX_get0_contentsOfAdmissions,
ADMISSION_SYNTAX_set0_admissionAuthority,
ADMISSION_SYNTAX_set0_contentsOfAdmissions,
NAMING_AUTHORITY,
NAMING_AUTHORITY_get0_authorityId,
NAMING_AUTHORITY_get0_authorityURL,
NAMING_AUTHORITY_get0_authorityText,
NAMING_AUTHORITY_set0_authorityId,
NAMING_AUTHORITY_set0_authorityURL,
NAMING_AUTHORITY_set0_authorityText,
PROFESSION_INFO,
PROFESSION_INFOS,
PROFESSION_INFO_get0_addProfessionInfo,
PROFESSION_INFO_get0_namingAuthority,
PROFESSION_INFO_get0_professionItems,
PROFESSION_INFO_get0_professionOIDs,
PROFESSION_INFO_get0_registrationNumber,
PROFESSION_INFO_set0_addProfessionInfo,
PROFESSION_INFO_set0_namingAuthority,
PROFESSION_INFO_set0_professionItems,
PROFESSION_INFO_set0_professionOIDs,
PROFESSION_INFO_set0_registrationNumber
- Accessors and settors for ADMISSION_SYNTAX
=head1 SYNOPSIS
typedef struct NamingAuthority_st NAMING_AUTHORITY;
typedef struct ProfessionInfo_st PROFESSION_INFO;
typedef STACK_OF(PROFESSION_INFO) PROFESSION_INFOS;
typedef struct Admissions_st ADMISSIONS;
typedef struct AdmissionSyntax_st ADMISSION_SYNTAX;
const ASN1_OBJECT *NAMING_AUTHORITY_get0_authorityId(
const NAMING_AUTHORITY *n);
void NAMING_AUTHORITY_set0_authorityId(NAMING_AUTHORITY *n,
ASN1_OBJECT* namingAuthorityId);
const ASN1_IA5STRING *NAMING_AUTHORITY_get0_authorityURL(
const NAMING_AUTHORITY *n);
void NAMING_AUTHORITY_set0_authorityURL(NAMING_AUTHORITY *n,
ASN1_IA5STRING* namingAuthorityUrl);
const ASN1_STRING *NAMING_AUTHORITY_get0_authorityText(
const NAMING_AUTHORITY *n);
void NAMING_AUTHORITY_set0_authorityText(NAMING_AUTHORITY *n,
ASN1_STRING* namingAuthorityText);
const GENERAL_NAME *ADMISSION_SYNTAX_get0_admissionAuthority(
const ADMISSION_SYNTAX *as);
void ADMISSION_SYNTAX_set0_admissionAuthority(
ADMISSION_SYNTAX *as, GENERAL_NAME *aa);
const STACK_OF(ADMISSIONS) *ADMISSION_SYNTAX_get0_contentsOfAdmissions(
const ADMISSION_SYNTAX *as);
void ADMISSION_SYNTAX_set0_contentsOfAdmissions(
ADMISSION_SYNTAX *as, STACK_OF(ADMISSIONS) *a);
const GENERAL_NAME *ADMISSIONS_get0_admissionAuthority(const ADMISSIONS *a);
void ADMISSIONS_set0_admissionAuthority(ADMISSIONS *a, GENERAL_NAME *aa);
const NAMING_AUTHORITY *ADMISSIONS_get0_namingAuthority(const ADMISSIONS *a);
void ADMISSIONS_set0_namingAuthority(ADMISSIONS *a, NAMING_AUTHORITY *na);
const PROFESSION_INFOS *ADMISSIONS_get0_professionInfos(const ADMISSIONS *a);
void ADMISSIONS_set0_professionInfos(ADMISSIONS *a, PROFESSION_INFOS *pi);
const ASN1_OCTET_STRING *PROFESSION_INFO_get0_addProfessionInfo(
const PROFESSION_INFO *pi);
void PROFESSION_INFO_set0_addProfessionInfo(
PROFESSION_INFO *pi, ASN1_OCTET_STRING *aos);
const NAMING_AUTHORITY *PROFESSION_INFO_get0_namingAuthority(
const PROFESSION_INFO *pi);
void PROFESSION_INFO_set0_namingAuthority(
PROFESSION_INFO *pi, NAMING_AUTHORITY *na);
const STACK_OF(ASN1_STRING) *PROFESSION_INFO_get0_professionItems(
const PROFESSION_INFO *pi);
void PROFESSION_INFO_set0_professionItems(
PROFESSION_INFO *pi, STACK_OF(ASN1_STRING) *as);
const STACK_OF(ASN1_OBJECT) *PROFESSION_INFO_get0_professionOIDs(
const PROFESSION_INFO *pi);
void PROFESSION_INFO_set0_professionOIDs(
PROFESSION_INFO *pi, STACK_OF(ASN1_OBJECT) *po);
const ASN1_PRINTABLESTRING *PROFESSION_INFO_get0_registrationNumber(
const PROFESSION_INFO *pi);
void PROFESSION_INFO_set0_registrationNumber(
PROFESSION_INFO *pi, ASN1_PRINTABLESTRING *rn);
=head1 DESCRIPTION
The B<PROFESSION_INFOS>, B<ADMISSION_SYNTAX>, B<ADMISSIONS>, and
B<PROFESSION_INFO> types are opaque structures representing the
analogous types defined in the Common PKI Specification published
by L<https://www.t7ev.org>.
Knowledge of those structures and their semantics is assumed.
The conventional routines to convert between DER and the local format
are described in L<d2i_X509(3)>.
The conventional routines to allocate and free the types are defined
in L<X509_dup(3)>.
The B<PROFESSION_INFOS> type is a stack of B<PROFESSION_INFO>; see
L<DEFINE_STACK_OF(3)> for details.
The B<NAMING_AUTHORITY> type has an authority ID and URL, and text fields.
The NAMING_AUTHORITY_get0_authorityId(),
NAMING_AUTHORITY_get0_get0_authorityURL(), and
NAMING_AUTHORITY_get0_get0_authorityText(), functions return pointers
to those values within the object.
The NAMING_AUTHORITY_set0_authorityId(),
NAMING_AUTHORITY_set0_get0_authorityURL(), and
NAMING_AUTHORITY_set0_get0_authorityText(),
functions free any existing value and set the pointer to the specified value.
The B<ADMISSION_SYNTAX> type has an authority name and a stack of
B<ADMISSION> objects.
The ADMISSION_SYNTAX_get0_admissionAuthority()
and ADMISSION_SYNTAX_get0_contentsOfAdmissions() functions return pointers
to those values within the object.
The
ADMISSION_SYNTAX_set0_admissionAuthority() and
ADMISSION_SYNTAX_set0_contentsOfAdmissions()
functions free any existing value and set the pointer to the specified value.
The B<ADMISSION> type has an authority name, authority object, and a
stack of B<PROFSSION_INFO> items.
The ADMISSIONS_get0_admissionAuthority(), ADMISSIONS_get0_namingAuthority(),
and ADMISSIONS_get0_professionInfos()
functions return pointers to those values within the object.
The
ADMISSIONS_set0_admissionAuthority(),
ADMISSIONS_set0_namingAuthority(), and
ADMISSIONS_set0_professionInfos()
functions free any existing value and set the pointer to the specified value.
The B<PROFESSION_INFO> type has a name authority, stacks of
profession Items and OIDs, a registration number, and additional
profession info.
The functions PROFESSION_INFO_get0_addProfessionInfo(),
PROFESSION_INFO_get0_namingAuthority(), PROFESSION_INFO_get0_professionItems(),
PROFESSION_INFO_get0_professionOIDs(), and
PROFESSION_INFO_get0_registrationNumber()
functions return pointers to those values within the object.
The
PROFESSION_INFO_set0_addProfessionInfo(),
PROFESSION_INFO_set0_namingAuthority(),
PROFESSION_INFO_set0_professionItems(),
PROFESSION_INFO_set0_professionOIDs(), and
PROFESSION_INFO_set0_registrationNumber()
functions free any existing value and set the pointer to the specified value.
=head1 RETURN VALUES
Described above.
Note that all of the I<get0> functions return a pointer to the internal data
structure and must not be freed.
=head1 SEE ALSO
L<X509_dup(3)>,
L<d2i_X509(3)>,
=head1 COPYRIGHT
Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

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

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

39
doc/man3/ASN1_ITEM_lookup.pod Normal file
View File

@@ -0,0 +1,39 @@
=pod
=head1 NAME
ASN1_ITEM_lookup, ASN1_ITEM_get - lookup ASN.1 structures
=head1 SYNOPSIS
#include <openssl/asn1.h>
const ASN1_ITEM *ASN1_ITEM_lookup(const char *name);
const ASN1_ITEM *ASN1_ITEM_get(size_t i);
=head1 DESCRIPTION
ASN1_ITEM_lookup() returns the B<ASN1_ITEM 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.
=head1 RETURN VALUES
ASN1_ITEM_lookup() and ASN1_ITEM_get() return a valid B<ASN1_ITEM> structure
or B<NULL> if an error occurred.
=head1 SEE ALSO
L<ERR_get_error(3)>
=head1 COPYRIGHT
Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

51
doc/man3/ASN1_OBJECT_new.pod Normal file
View File

@@ -0,0 +1,51 @@
=pod
=head1 NAME
ASN1_OBJECT_new, ASN1_OBJECT_free - object allocation functions
=head1 SYNOPSIS
#include <openssl/asn1.h>
ASN1_OBJECT *ASN1_OBJECT_new(void);
void ASN1_OBJECT_free(ASN1_OBJECT *a);
=head1 DESCRIPTION
The ASN1_OBJECT allocation routines, allocate and free an
ASN1_OBJECT structure, which represents an ASN1 OBJECT IDENTIFIER.
ASN1_OBJECT_new() allocates and initializes an ASN1_OBJECT structure.
ASN1_OBJECT_free() frees up the B<ASN1_OBJECT> structure B<a>.
If B<a> is NULL, nothing is done.
=head1 NOTES
Although ASN1_OBJECT_new() allocates a new ASN1_OBJECT structure it
is almost never used in applications. The ASN1 object utility functions
such as OBJ_nid2obj() are used instead.
=head1 RETURN VALUES
If the allocation fails, ASN1_OBJECT_new() returns B<NULL> and sets an error
code that can be obtained by L<ERR_get_error(3)>.
Otherwise it returns a pointer to the newly allocated structure.
ASN1_OBJECT_free() returns no value.
=head1 SEE ALSO
L<ERR_get_error(3)>, L<d2i_ASN1_OBJECT(3)>
=head1 COPYRIGHT
Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

65
doc/man3/ASN1_STRING_TABLE_add.pod Normal file
View File

@@ -0,0 +1,65 @@
=pod
=head1 NAME
ASN1_STRING_TABLE, ASN1_STRING_TABLE_add, ASN1_STRING_TABLE_get,
ASN1_STRING_TABLE_cleanup - ASN1_STRING_TABLE manipulation functions
=head1 SYNOPSIS
#include <openssl/asn1.h>
typedef struct asn1_string_table_st ASN1_STRING_TABLE;
int ASN1_STRING_TABLE_add(int nid, long minsize, long maxsize,
unsigned long mask, unsigned long flags);
ASN1_STRING_TABLE * ASN1_STRING_TABLE_get(int nid);
void ASN1_STRING_TABLE_cleanup(void);
=head1 DESCRIPTION
=head2 Types
B<ASN1_STRING_TABLE> is a table which holds string information
(basically minimum size, maximum size, type and etc) for a NID object.
=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.
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,
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.
ASN1_STRING_TABLE_cleanup() frees all B<ASN1_STRING_TABLE> items added
by ASN1_STRING_TABLE_add().
=head1 RETURN VALUES
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.
ASN1_STRING_TABLE_cleanup() does not return a value.
=head1 SEE ALSO
L<ERR_get_error(3)>
=head1 COPYRIGHT
Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

113
doc/man3/ASN1_STRING_length.pod Normal file
View File

@@ -0,0 +1,113 @@
=pod
=head1 NAME
ASN1_STRING_dup, ASN1_STRING_cmp, ASN1_STRING_set, ASN1_STRING_length,
ASN1_STRING_type, ASN1_STRING_get0_data, ASN1_STRING_data,
ASN1_STRING_to_UTF8 - ASN1_STRING utility functions
=head1 SYNOPSIS
#include <openssl/asn1.h>
int ASN1_STRING_length(ASN1_STRING *x);
const unsigned char * ASN1_STRING_get0_data(const ASN1_STRING *x);
unsigned char * ASN1_STRING_data(ASN1_STRING *x);
ASN1_STRING * ASN1_STRING_dup(ASN1_STRING *a);
int ASN1_STRING_cmp(ASN1_STRING *a, ASN1_STRING *b);
int ASN1_STRING_set(ASN1_STRING *str, const void *data, int len);
int ASN1_STRING_type(const ASN1_STRING *x);
int ASN1_STRING_to_UTF8(unsigned char **out, const ASN1_STRING *in);
=head1 DESCRIPTION
These functions allow an B<ASN1_STRING> structure to be manipulated.
ASN1_STRING_length() returns the length of the content of B<x>.
ASN1_STRING_get0_data() returns an internal pointer to the data of B<x>.
Since this is an internal pointer it should B<not> be freed or
modified in any way.
ASN1_STRING_data() is similar to ASN1_STRING_get0_data() except the
returned value is not constant. This function is deprecated:
applications should use ASN1_STRING_get0_data() instead.
ASN1_STRING_dup() returns a copy of the structure B<a>.
ASN1_STRING_cmp() compares B<a> and B<b> returning 0 if the two
are identical. The string types and content are compared.
ASN1_STRING_set() sets the data of string B<str> to the buffer
B<data> or length B<len>. The supplied data is copied. If B<len>
is -1 then the length is determined by strlen(data).
ASN1_STRING_type() returns the type of B<x>, using standard constants
such as B<V_ASN1_OCTET_STRING>.
ASN1_STRING_to_UTF8() converts the string B<in> to UTF8 format, the
converted data is allocated in a buffer in B<*out>. The length of
B<out> is returned or a negative error code. The buffer B<*out>
should be freed using OPENSSL_free().
=head1 NOTES
Almost all ASN1 types in OpenSSL are represented as an B<ASN1_STRING>
structure. Other types such as B<ASN1_OCTET_STRING> are simply typedef'ed
to B<ASN1_STRING> and the functions call the B<ASN1_STRING> equivalents.
B<ASN1_STRING> is also used for some B<CHOICE> types which consist
entirely of primitive string types such as B<DirectoryString> and
B<Time>.
These functions should B<not> be used to examine or modify B<ASN1_INTEGER>
or B<ASN1_ENUMERATED> types: the relevant B<INTEGER> or B<ENUMERATED>
utility functions should be used instead.
In general it cannot be assumed that the data returned by ASN1_STRING_data()
is null terminated or does not contain embedded nulls. The actual format
of the data will depend on the actual string type itself: for example
for an IA5String the data will be ASCII, for a BMPString two bytes per
character in big endian format, and for an UTF8String it will be in UTF8 format.
Similar care should be take to ensure the data is in the correct format
when calling ASN1_STRING_set().
=head1 RETURN VALUES
ASN1_STRING_length() returns the length of the content of B<x>.
ASN1_STRING_get0_data() and ASN1_STRING_data() return an internal pointer to
the data of B<x>.
ASN1_STRING_dup() returns a valid B<ASN1_STRING> structure or B<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>.
ASN1_STRING_set() returns 1 on success or 0 on error.
ASN1_STRING_type() returns the type of B<x>.
ASN1_STRING_to_UTF8() returns the number of bytes in output string B<out> or a
negative value if an error occurred.
=head1 SEE ALSO
L<ERR_get_error(3)>
=head1 COPYRIGHT
Copyright 2002-2018 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

52
doc/man3/ASN1_STRING_new.pod Normal file
View File

@@ -0,0 +1,52 @@
=pod
=head1 NAME
ASN1_STRING_new, ASN1_STRING_type_new, ASN1_STRING_free -
ASN1_STRING allocation functions
=head1 SYNOPSIS
#include <openssl/asn1.h>
ASN1_STRING * ASN1_STRING_new(void);
ASN1_STRING * ASN1_STRING_type_new(int type);
void ASN1_STRING_free(ASN1_STRING *a);
=head1 DESCRIPTION
ASN1_STRING_new() returns an allocated B<ASN1_STRING> structure. Its type
is undefined.
ASN1_STRING_type_new() returns an allocated B<ASN1_STRING> structure of
type B<type>.
ASN1_STRING_free() frees up B<a>.
If B<a> is NULL nothing is done.
=head1 NOTES
Other string types call the B<ASN1_STRING> functions. For example
ASN1_OCTET_STRING_new() calls ASN1_STRING_type(V_ASN1_OCTET_STRING).
=head1 RETURN VALUES
ASN1_STRING_new() and ASN1_STRING_type_new() return a valid
ASN1_STRING structure or B<NULL> if an error occurred.
ASN1_STRING_free() does not return a value.
=head1 SEE ALSO
L<ERR_get_error(3)>
=head1 COPYRIGHT
Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

115
doc/man3/ASN1_STRING_print_ex.pod Normal file
View File

@@ -0,0 +1,115 @@
=pod
=head1 NAME
ASN1_tag2str, ASN1_STRING_print_ex, ASN1_STRING_print_ex_fp, ASN1_STRING_print
- ASN1_STRING output routines
=head1 SYNOPSIS
#include <openssl/asn1.h>
int ASN1_STRING_print_ex(BIO *out, const ASN1_STRING *str, unsigned long flags);
int ASN1_STRING_print_ex_fp(FILE *fp, const ASN1_STRING *str, unsigned long flags);
int ASN1_STRING_print(BIO *out, const ASN1_STRING *str);
const char *ASN1_tag2str(int tag);
=head1 DESCRIPTION
These functions output an B<ASN1_STRING> structure. B<ASN1_STRING> is used to
represent all the ASN1 string types.
ASN1_STRING_print_ex() outputs B<str> to B<out>, the format is determined by
the options B<flags>. ASN1_STRING_print_ex_fp() is identical except it outputs
to B<fp> instead.
ASN1_STRING_print() prints B<str> to B<out> but using a different format to
ASN1_STRING_print_ex(). It replaces unprintable characters (other than CR, LF)
with '.'.
ASN1_tag2str() returns a human-readable name of the specified ASN.1 B<tag>.
=head1 NOTES
ASN1_STRING_print() is a deprecated function which should be avoided; use
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.
Various characters can be escaped. If B<ASN1_STRFLGS_ESC_2253> is set the characters
determined by RFC2253 are escaped. If B<ASN1_STRFLGS_ESC_CTRL> is set control
characters are escaped. If B<ASN1_STRFLGS_ESC_MSB> is set characters with the
MSB set are escaped: this option should B<not> be used if the terminal correctly
interprets UTF8 sequences.
Escaping takes several forms.
If the character being escaped is a 16 bit character then the form "\UXXXX" is used
using exactly four characters for the hex representation. If it is 32 bits then
"\WXXXXXXXX" is used using eight characters of its hex representation. These forms
will only be used if UTF8 conversion is not set (see below).
Printable characters are normally escaped using the backslash '\' character. If
B<ASN1_STRFLGS_ESC_QUOTE> is set then the whole string is instead surrounded by
double quote characters: this is arguably more readable than the backslash
notation. Other characters use the "\XX" using exactly two characters of the hex
representation.
If B<ASN1_STRFLGS_UTF8_CONVERT> is set then characters are converted to UTF8
format first. If the terminal supports the display of UTF8 sequences then this
option will correctly display multi byte characters.
If B<ASN1_STRFLGS_IGNORE_TYPE> is set then the string type is not interpreted at
all: everything is assumed to be one byte per character. This is primarily for
debugging purposes and can result in confusing output in multi character strings.
If B<ASN1_STRFLGS_SHOW_TYPE> is set then the string type itself is printed out
before its value (for example "BMPSTRING"), this actually uses ASN1_tag2str().
The content of a string instead of being interpreted can be "dumped": this just
outputs the value of the string using the form #XXXX using hex format for each
octet.
If B<ASN1_STRFLGS_DUMP_ALL> is set then any type is dumped.
Normally non character string types (such as OCTET STRING) are assumed to be
one byte per character, if B<ASN1_STRFLGS_DUMP_UNKNOWN> is set then they will
be dumped instead.
When a type is dumped normally just the content octets are printed, if
B<ASN1_STRFLGS_DUMP_DER> is set then the complete encoding is dumped
instead (including tag and length octets).
B<ASN1_STRFLGS_RFC2253> includes all the flags required by RFC2253. It is
equivalent to:
ASN1_STRFLGS_ESC_2253 | ASN1_STRFLGS_ESC_CTRL | ASN1_STRFLGS_ESC_MSB |
ASN1_STRFLGS_UTF8_CONVERT | ASN1_STRFLGS_DUMP_UNKNOWN ASN1_STRFLGS_DUMP_DER
=head1 RETURN VALUES
ASN1_STRING_print_ex() and ASN1_STRING_print_ex_fp() return the number of
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>.
=head1 SEE ALSO
L<X509_NAME_print_ex(3)>,
L<ASN1_tag2str(3)>
=head1 COPYRIGHT
Copyright 2002-2018 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

258
doc/man3/ASN1_TIME_set.pod Normal file
View File

@@ -0,0 +1,258 @@
=pod
=head1 NAME
ASN1_TIME_set, ASN1_UTCTIME_set, ASN1_GENERALIZEDTIME_set,
ASN1_TIME_adj, ASN1_UTCTIME_adj, ASN1_GENERALIZEDTIME_adj,
ASN1_TIME_check, ASN1_UTCTIME_check, ASN1_GENERALIZEDTIME_check,
ASN1_TIME_set_string, ASN1_UTCTIME_set_string, ASN1_GENERALIZEDTIME_set_string,
ASN1_TIME_set_string_X509,
ASN1_TIME_normalize,
ASN1_TIME_to_tm,
ASN1_TIME_print, ASN1_UTCTIME_print, ASN1_GENERALIZEDTIME_print,
ASN1_TIME_diff,
ASN1_TIME_cmp_time_t, ASN1_UTCTIME_cmp_time_t,
ASN1_TIME_compare,
ASN1_TIME_to_generalizedtime - ASN.1 Time functions
=head1 SYNOPSIS
ASN1_TIME *ASN1_TIME_set(ASN1_TIME *s, time_t t);
ASN1_UTCTIME *ASN1_UTCTIME_set(ASN1_UTCTIME *s, time_t t);
ASN1_GENERALIZEDTIME *ASN1_GENERALIZEDTIME_set(ASN1_GENERALIZEDTIME *s,
time_t t);
ASN1_TIME *ASN1_TIME_adj(ASN1_TIME *s, time_t t, int offset_day,
long offset_sec);
ASN1_UTCTIME *ASN1_UTCTIME_adj(ASN1_UTCTIME *s, time_t t,
int offset_day, long offset_sec);
ASN1_GENERALIZEDTIME *ASN1_GENERALIZEDTIME_adj(ASN1_GENERALIZEDTIME *s,
time_t t, int offset_day,
long offset_sec);
int ASN1_TIME_set_string(ASN1_TIME *s, const char *str);
int ASN1_TIME_set_string_X509(ASN1_TIME *s, const char *str);
int ASN1_UTCTIME_set_string(ASN1_UTCTIME *s, const char *str);
int ASN1_GENERALIZEDTIME_set_string(ASN1_GENERALIZEDTIME *s,
const char *str);
int ASN1_TIME_normalize(ASN1_TIME *s);
int ASN1_TIME_check(const ASN1_TIME *t);
int ASN1_UTCTIME_check(const ASN1_UTCTIME *t);
int ASN1_GENERALIZEDTIME_check(const ASN1_GENERALIZEDTIME *t);
int ASN1_TIME_print(BIO *b, const ASN1_TIME *s);
int ASN1_UTCTIME_print(BIO *b, const ASN1_UTCTIME *s);
int ASN1_GENERALIZEDTIME_print(BIO *b, const ASN1_GENERALIZEDTIME *s);
int ASN1_TIME_to_tm(const ASN1_TIME *s, struct tm *tm);
int ASN1_TIME_diff(int *pday, int *psec, const ASN1_TIME *from,
const ASN1_TIME *to);
int ASN1_TIME_cmp_time_t(const ASN1_TIME *s, time_t t);
int ASN1_UTCTIME_cmp_time_t(const ASN1_UTCTIME *s, time_t t);
int ASN1_TIME_compare(const ASN1_TIME *a, const ASN1_TIME *b);
ASN1_GENERALIZEDTIME *ASN1_TIME_to_generalizedtime(ASN1_TIME *t,
ASN1_GENERALIZEDTIME **out);
=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.
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
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_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
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.
The ASN1_TIME_normalize() function converts an ASN1_GENERALIZEDTIME or
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>.
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
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
seconds, e.g. YYYYMMDDHHMMSS.SSSZ, the fractional seconds will be lost while
converting B<s> to B<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.
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 ASN1_TIME_compare() function compares the two times represented by the
time structures B<a> and B<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.
=head1 NOTES
The ASN1_TIME structure corresponds to the ASN.1 structure B<Time>
defined in RFC5280 et al. The time setting functions obey the rules outlined
in RFC5280: if the date can be represented by UTCTime it is used, else
GeneralizedTime is used.
The ASN1_TIME, ASN1_UTCTIME and ASN1_GENERALIZEDTIME structures are represented
as an ASN1_STRING internally and can be freed up using ASN1_STRING_free().
The ASN1_TIME structure can represent years from 0000 to 9999 but no attempt
is made to correct ancient calendar changes (for example from Julian to
Gregorian calendars).
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
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.
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.
=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
certificates complying with RFC5280 et al use GMT anyway.
Use the ASN1_TIME_normalize() function to normalize the time value before
printing to get GMT results.
=head1 EXAMPLES
Set a time structure to one hour after the current time and print it out:
#include <time.h>
#include <openssl/asn1.h>
ASN1_TIME *tm;
time_t t;
BIO *b;
t = time(NULL);
tm = ASN1_TIME_adj(NULL, t, 0, 60 * 60);
b = BIO_new_fp(stdout, BIO_NOCLOSE);
ASN1_TIME_print(b, tm);
ASN1_STRING_free(tm);
BIO_free(b);
Determine if one time is later or sooner than the current time:
int day, sec;
if (!ASN1_TIME_diff(&day, &sec, NULL, to))
/* Invalid time format */
if (day > 0 || sec > 0)
printf("Later\n");
else if (day < 0 || sec < 0)
printf("Sooner\n");
else
printf("Same\n");
=head1 RETURN VALUES
ASN1_TIME_set(), 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_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_to_tm() returns 1 if the time is successfully parsed and 0 if an
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
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_to_generalizedtime() returns a pointer to
the appropriate time structure on success or NULL if an error occurred.
=head1 HISTORY
The ASN1_TIME_to_tm() function was added in OpenSSL 1.1.1.
The ASN1_TIME_set_string_X509() function was added in OpenSSL 1.1.1.
The ASN1_TIME_normalize() function was added in OpenSSL 1.1.1.
The ASN1_TIME_cmp_time_t() function was added in OpenSSL 1.1.1.
The ASN1_TIME_compare() function was added in OpenSSL 1.1.1.
=head1 COPYRIGHT
Copyright 2015-2018 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

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

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

270
doc/man3/ASN1_generate_nconf.pod Normal file
View File

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

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

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

331
doc/man3/ASYNC_start_job.pod Normal file
View File

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

119
doc/man3/BF_encrypt.pod Normal file
View File

@@ -0,0 +1,119 @@
=pod
=head1 NAME
BF_set_key, BF_encrypt, BF_decrypt, BF_ecb_encrypt, BF_cbc_encrypt,
BF_cfb64_encrypt, BF_ofb64_encrypt, BF_options - Blowfish encryption
=head1 SYNOPSIS
#include <openssl/blowfish.h>
void BF_set_key(BF_KEY *key, int len, const unsigned char *data);
void BF_ecb_encrypt(const unsigned char *in, unsigned char *out,
BF_KEY *key, int enc);
void BF_cbc_encrypt(const unsigned char *in, unsigned char *out,
long length, BF_KEY *schedule,
unsigned char *ivec, int enc);
void BF_cfb64_encrypt(const unsigned char *in, unsigned char *out,
long length, BF_KEY *schedule,
unsigned char *ivec, int *num, int enc);
void BF_ofb64_encrypt(const unsigned char *in, unsigned char *out,
long length, BF_KEY *schedule,
unsigned char *ivec, int *num);
const char *BF_options(void);
void BF_encrypt(BF_LONG *data, const BF_KEY *key);
void BF_decrypt(BF_LONG *data, const BF_KEY *key);
=head1 DESCRIPTION
This library implements the Blowfish cipher, which was invented and described
by Counterpane (see http://www.counterpane.com/blowfish.html ).
Blowfish is a block cipher that operates on 64 bit (8 byte) blocks of data.
It uses a variable size key, but typically, 128 bit (16 byte) keys are
considered good for strong encryption. Blowfish can be used in the same
modes as DES (see L<des_modes(7)>). Blowfish is currently one
of the faster block ciphers. It is quite a bit faster than DES, and much
faster than IDEA or RC2.
Blowfish consists of a key setup phase and the actual encryption or decryption
phase.
BF_set_key() sets up the B<BF_KEY> B<key> using the B<len> bytes long key
at B<data>.
BF_ecb_encrypt() is the basic Blowfish encryption and decryption function.
It encrypts or decrypts the first 64 bits of B<in> using the key B<key>,
putting the result in B<out>. B<enc> decides if encryption (B<BF_ENCRYPT>)
or decryption (B<BF_DECRYPT>) shall be performed. The vector pointed at by
B<in> and B<out> must be 64 bits in length, no less. If they are larger,
everything after the first 64 bits is ignored.
The mode functions BF_cbc_encrypt(), BF_cfb64_encrypt() and BF_ofb64_encrypt()
all operate on variable length data. They all take an initialization vector
B<ivec> which needs to be passed along into the next call of the same function
for the same message. B<ivec> may be initialized with anything, but the
recipient needs to know what it was initialized with, or it won't be able
to decrypt. Some programs and protocols simplify this, like SSH, where
B<ivec> is simply initialized to zero.
BF_cbc_encrypt() operates on data that is a multiple of 8 bytes long, while
BF_cfb64_encrypt() and BF_ofb64_encrypt() are used to encrypt an variable
number of bytes (the amount does not have to be an exact multiple of 8). The
purpose of the latter two is to simulate stream ciphers, and therefore, they
need the parameter B<num>, which is a pointer to an integer where the current
offset in B<ivec> is stored between calls. This integer must be initialized
to zero when B<ivec> is initialized.
BF_cbc_encrypt() is the Cipher Block Chaining function for Blowfish. It
encrypts or decrypts the 64 bits chunks of B<in> using the key B<schedule>,
putting the result in B<out>. B<enc> decides if encryption (BF_ENCRYPT) or
decryption (BF_DECRYPT) shall be performed. B<ivec> must point at an 8 byte
long initialization vector.
BF_cfb64_encrypt() is the CFB mode for Blowfish with 64 bit feedback.
It encrypts or decrypts the bytes in B<in> using the key B<schedule>,
putting the result in B<out>. B<enc> decides if encryption (B<BF_ENCRYPT>)
or decryption (B<BF_DECRYPT>) shall be performed. B<ivec> must point at an
8 byte long initialization vector. B<num> must point at an integer which must
be initially zero.
BF_ofb64_encrypt() is the OFB mode for Blowfish with 64 bit feedback.
It uses the same parameters as BF_cfb64_encrypt(), which must be initialized
the same way.
BF_encrypt() and BF_decrypt() are the lowest level functions for Blowfish
encryption. They encrypt/decrypt the first 64 bits of the vector pointed by
B<data>, using the key B<key>. These functions should not be used unless you
implement 'modes' of Blowfish. The alternative is to use BF_ecb_encrypt().
If you still want to use these functions, you should be aware that they take
each 32-bit chunk in host-byte order, which is little-endian on little-endian
platforms and big-endian on big-endian ones.
=head1 RETURN VALUES
None of the functions presented here return any value.
=head1 NOTE
Applications should use the higher level functions
L<EVP_EncryptInit(3)> etc. instead of calling these
functions directly.
=head1 SEE ALSO
L<EVP_EncryptInit(3)>,
L<des_modes(7)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

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

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

114
doc/man3/BIO_ADDRINFO.pod Normal file
View File

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

117
doc/man3/BIO_connect.pod Normal file
View File

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

136
doc/man3/BIO_ctrl.pod Normal file
View File

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

91
doc/man3/BIO_f_base64.pod Normal file
View File

@@ -0,0 +1,91 @@
=pod
=head1 NAME
BIO_f_base64 - base64 BIO filter
=head1 SYNOPSIS
=for comment multiple includes
#include <openssl/bio.h>
#include <openssl/evp.h>
const BIO_METHOD *BIO_f_base64(void);
=head1 DESCRIPTION
BIO_f_base64() returns the base64 BIO method. This is a filter
BIO that base64 encodes any data written through it and decodes
any data read through it.
Base64 BIOs do not support BIO_gets() or BIO_puts().
BIO_flush() on a base64 BIO that is being written through is
used to signal that no more data is to be encoded: this is used
to flush the final block through the BIO.
The flag BIO_FLAGS_BASE64_NO_NL can be set with BIO_set_flags()
to encode the data all on one line or expect the data to be all
on one line.
=head1 NOTES
Because of the format of base64 encoding the end of the encoded
block cannot always be reliably determined.
=head1 RETURN VALUES
BIO_f_base64() returns the base64 BIO method.
=head1 EXAMPLES
Base64 encode the string "Hello World\n" and write the result
to standard output:
BIO *bio, *b64;
char message[] = "Hello World \n";
b64 = BIO_new(BIO_f_base64());
bio = BIO_new_fp(stdout, BIO_NOCLOSE);
BIO_push(b64, bio);
BIO_write(b64, message, strlen(message));
BIO_flush(b64);
BIO_free_all(b64);
Read Base64 encoded data from standard input and write the decoded
data to standard output:
BIO *bio, *b64, *bio_out;
char inbuf[512];
int inlen;
b64 = BIO_new(BIO_f_base64());
bio = BIO_new_fp(stdin, BIO_NOCLOSE);
bio_out = BIO_new_fp(stdout, BIO_NOCLOSE);
BIO_push(b64, bio);
while ((inlen = BIO_read(b64, inbuf, 512)) > 0)
BIO_write(bio_out, inbuf, inlen);
BIO_flush(bio_out);
BIO_free_all(b64);
=head1 BUGS
The ambiguity of EOF in base64 encoded data can cause additional
data following the base64 encoded block to be misinterpreted.
There should be some way of specifying a test that the BIO can perform
to reliably determine EOF (for example a MIME boundary).
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

92
doc/man3/BIO_f_buffer.pod Normal file
View File

@@ -0,0 +1,92 @@
=pod
=head1 NAME
BIO_get_buffer_num_lines,
BIO_set_read_buffer_size,
BIO_set_write_buffer_size,
BIO_set_buffer_size,
BIO_set_buffer_read_data,
BIO_f_buffer
- buffering BIO
=head1 SYNOPSIS
#include <openssl/bio.h>
const BIO_METHOD *BIO_f_buffer(void);
long BIO_get_buffer_num_lines(BIO *b);
long BIO_set_read_buffer_size(BIO *b, long size);
long BIO_set_write_buffer_size(BIO *b, long size);
long BIO_set_buffer_size(BIO *b, long size);
long BIO_set_buffer_read_data(BIO *b, void *buf, long num);
=head1 DESCRIPTION
BIO_f_buffer() returns the buffering BIO method.
Data written to a buffering BIO is buffered and periodically written
to the next BIO in the chain. Data read from a buffering BIO comes from
an internal buffer which is filled from the next BIO in the chain.
Both BIO_gets() and BIO_puts() are supported.
Calling BIO_reset() on a buffering BIO clears any buffered data.
BIO_get_buffer_num_lines() returns the number of lines currently buffered.
BIO_set_read_buffer_size(), BIO_set_write_buffer_size() and BIO_set_buffer_size()
set the read, write or both read and write buffer sizes to B<size>. The initial
buffer size is DEFAULT_BUFFER_SIZE, currently 4096. Any attempt to reduce the
buffer size below DEFAULT_BUFFER_SIZE is ignored. Any buffered data is cleared
when the buffer is resized.
BIO_set_buffer_read_data() clears the read buffer and fills it with B<num>
bytes of B<buf>. If B<num> is larger than the current buffer size the buffer
is expanded.
=head1 NOTES
These functions, other than BIO_f_buffer(), are implemented as macros.
Buffering BIOs implement BIO_gets() by using BIO_read_ex() operations on the
next BIO in the chain. By prepending a buffering BIO to a chain it is therefore
possible to provide BIO_gets() functionality if the following BIOs do not
support it (for example SSL BIOs).
Data is only written to the next BIO in the chain when the write buffer fills
or when BIO_flush() is called. It is therefore important to call BIO_flush()
whenever any pending data should be written such as when removing a buffering
BIO using BIO_pop(). BIO_flush() may need to be retried if the ultimate
source/sink BIO is non blocking.
=head1 RETURN VALUES
BIO_f_buffer() returns the buffering BIO method.
BIO_get_buffer_num_lines() returns the number of lines buffered (may be 0).
BIO_set_read_buffer_size(), BIO_set_write_buffer_size() and BIO_set_buffer_size()
return 1 if the buffer was successfully resized or 0 for failure.
BIO_set_buffer_read_data() returns 1 if the data was set correctly or 0 if
there was an error.
=head1 SEE ALSO
L<bio(7)>,
L<BIO_reset(3)>,
L<BIO_flush(3)>,
L<BIO_pop(3)>,
L<BIO_ctrl(3)>.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

81
doc/man3/BIO_f_cipher.pod Normal file
View File

@@ -0,0 +1,81 @@
=pod
=head1 NAME
BIO_f_cipher, BIO_set_cipher, BIO_get_cipher_status, BIO_get_cipher_ctx - cipher BIO filter
=head1 SYNOPSIS
=for comment multiple includes
#include <openssl/bio.h>
#include <openssl/evp.h>
const BIO_METHOD *BIO_f_cipher(void);
void BIO_set_cipher(BIO *b, const EVP_CIPHER *cipher,
unsigned char *key, unsigned char *iv, int enc);
int BIO_get_cipher_status(BIO *b)
int BIO_get_cipher_ctx(BIO *b, EVP_CIPHER_CTX **pctx)
=head1 DESCRIPTION
BIO_f_cipher() returns the cipher BIO method. This is a filter
BIO that encrypts any data written through it, and decrypts any data
read from it. It is a BIO wrapper for the cipher routines
EVP_CipherInit(), EVP_CipherUpdate() and EVP_CipherFinal().
Cipher BIOs do not support BIO_gets() or BIO_puts().
BIO_flush() on an encryption BIO that is being written through is
used to signal that no more data is to be encrypted: this is used
to flush and possibly pad the final block through the BIO.
BIO_set_cipher() sets the cipher of BIO B<b> to B<cipher> using key B<key>
and IV B<iv>. B<enc> should be set to 1 for encryption and zero for
decryption.
When reading from an encryption BIO the final block is automatically
decrypted and checked when EOF is detected. BIO_get_cipher_status()
is a BIO_ctrl() macro which can be called to determine whether the
decryption operation was successful.
BIO_get_cipher_ctx() is a BIO_ctrl() macro which retrieves the internal
BIO cipher context. The retrieved context can be used in conjunction
with the standard cipher routines to set it up. This is useful when
BIO_set_cipher() is not flexible enough for the applications needs.
=head1 NOTES
When encrypting BIO_flush() B<must> be called to flush the final block
through the BIO. If it is not then the final block will fail a subsequent
decrypt.
When decrypting an error on the final block is signaled by a zero
return value from the read operation. A successful decrypt followed
by EOF will also return zero for the final read. BIO_get_cipher_status()
should be called to determine if the decrypt was successful.
As always, if BIO_gets() or BIO_puts() support is needed then it can
be achieved by preceding the cipher BIO with a buffering BIO.
=head1 RETURN VALUES
BIO_f_cipher() returns the cipher BIO method.
BIO_set_cipher() does not return a value.
BIO_get_cipher_status() returns 1 for a successful decrypt and 0
for failure.
BIO_get_cipher_ctx() currently always returns 1.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

162
doc/man3/BIO_f_md.pod Normal file
View File

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

39
doc/man3/BIO_f_null.pod Normal file
View File

@@ -0,0 +1,39 @@
=pod
=head1 NAME
BIO_f_null - null filter
=head1 SYNOPSIS
#include <openssl/bio.h>
const BIO_METHOD *BIO_f_null(void);
=head1 DESCRIPTION
BIO_f_null() returns the null filter BIO method. This is a filter BIO
that does nothing.
All requests to a null filter BIO are passed through to the next BIO in
the chain: this means that a BIO chain containing a null filter BIO
behaves just as though the BIO was not there.
=head1 NOTES
As may be apparent a null filter BIO is not particularly useful.
=head1 RETURN VALUES
BIO_f_null() returns the null filter BIO method.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

308
doc/man3/BIO_f_ssl.pod Normal file
View File

@@ -0,0 +1,308 @@
=pod
=head1 NAME
BIO_do_handshake,
BIO_f_ssl, BIO_set_ssl, BIO_get_ssl, BIO_set_ssl_mode,
BIO_set_ssl_renegotiate_bytes,
BIO_get_num_renegotiates, BIO_set_ssl_renegotiate_timeout, BIO_new_ssl,
BIO_new_ssl_connect, BIO_new_buffer_ssl_connect, BIO_ssl_copy_session_id,
BIO_ssl_shutdown - SSL BIO
=head1 SYNOPSIS
=for comment multiple includes
#include <openssl/bio.h>
#include <openssl/ssl.h>
const BIO_METHOD *BIO_f_ssl(void);
long BIO_set_ssl(BIO *b, SSL *ssl, long c);
long BIO_get_ssl(BIO *b, SSL **sslp);
long BIO_set_ssl_mode(BIO *b, long client);
long BIO_set_ssl_renegotiate_bytes(BIO *b, long num);
long BIO_set_ssl_renegotiate_timeout(BIO *b, long seconds);
long BIO_get_num_renegotiates(BIO *b);
BIO *BIO_new_ssl(SSL_CTX *ctx, int client);
BIO *BIO_new_ssl_connect(SSL_CTX *ctx);
BIO *BIO_new_buffer_ssl_connect(SSL_CTX *ctx);
int BIO_ssl_copy_session_id(BIO *to, BIO *from);
void BIO_ssl_shutdown(BIO *bio);
long BIO_do_handshake(BIO *b);
=head1 DESCRIPTION
BIO_f_ssl() returns the SSL BIO method. This is a filter BIO which
is a wrapper round the OpenSSL SSL routines adding a BIO "flavour" to
SSL I/O.
I/O performed on an SSL BIO communicates using the SSL protocol with
the SSLs read and write BIOs. If an SSL connection is not established
then an attempt is made to establish one on the first I/O call.
If a BIO is appended to an SSL BIO using BIO_push() it is automatically
used as the SSL BIOs read and write BIOs.
Calling BIO_reset() on an SSL BIO closes down any current SSL connection
by calling SSL_shutdown(). BIO_reset() is then sent to the next BIO in
the chain: this will typically disconnect the underlying transport.
The SSL BIO is then reset to the initial accept or connect state.
If the close flag is set when an SSL BIO is freed then the internal
SSL structure is also freed using SSL_free().
BIO_set_ssl() sets the internal SSL pointer of BIO B<b> to B<ssl> using
the close flag B<c>.
BIO_get_ssl() retrieves the SSL pointer of BIO B<b>, it can then be
manipulated using the standard SSL library functions.
BIO_set_ssl_mode() sets the SSL BIO mode to B<client>. If B<client>
is 1 client mode is set. If B<client> is 0 server mode is set.
BIO_set_ssl_renegotiate_bytes() sets the renegotiate byte count
to B<num>. When set after every B<num> bytes of I/O (read and write)
the SSL session is automatically renegotiated. B<num> must be at
least 512 bytes.
BIO_set_ssl_renegotiate_timeout() sets the renegotiate timeout to
B<seconds>. When the renegotiate timeout elapses the session is
automatically renegotiated.
BIO_get_num_renegotiates() returns the total number of session
renegotiations due to I/O or timeout.
BIO_new_ssl() allocates an SSL BIO using SSL_CTX B<ctx> and using
client mode if B<client> is non zero.
BIO_new_ssl_connect() creates a new BIO chain consisting of an
SSL BIO (using B<ctx>) followed by a connect BIO.
BIO_new_buffer_ssl_connect() creates a new BIO chain consisting
of a buffering BIO, an SSL BIO (using B<ctx>) and a connect
BIO.
BIO_ssl_copy_session_id() copies an SSL session id between
BIO chains B<from> and B<to>. It does this by locating the
SSL BIOs in each chain and calling SSL_copy_session_id() on
the internal SSL pointer.
BIO_ssl_shutdown() closes down an SSL connection on BIO
chain B<bio>. It does this by locating the SSL BIO in the
chain and calling SSL_shutdown() on its internal SSL
pointer.
BIO_do_handshake() attempts to complete an SSL handshake on the
supplied BIO and establish the SSL connection. It returns 1
if the connection was established successfully. A zero or negative
value is returned if the connection could not be established, the
call BIO_should_retry() should be used for non blocking connect BIOs
to determine if the call should be retried. If an SSL connection has
already been established this call has no effect.
=head1 NOTES
SSL BIOs are exceptional in that if the underlying transport
is non blocking they can still request a retry in exceptional
circumstances. Specifically this will happen if a session
renegotiation takes place during a BIO_read_ex() operation, one
case where this happens is when step up occurs.
The SSL flag SSL_AUTO_RETRY can be
set to disable this behaviour. That is when this flag is set
an SSL BIO using a blocking transport will never request a
retry.
Since unknown BIO_ctrl() operations are sent through filter
BIOs the servers name and port can be set using BIO_set_host()
on the BIO returned by BIO_new_ssl_connect() without having
to locate the connect BIO first.
Applications do not have to call BIO_do_handshake() but may wish
to do so to separate the handshake process from other I/O
processing.
BIO_set_ssl(), BIO_get_ssl(), BIO_set_ssl_mode(),
BIO_set_ssl_renegotiate_bytes(), BIO_set_ssl_renegotiate_timeout(),
BIO_get_num_renegotiates(), and BIO_do_handshake() are implemented as macros.
=head1 EXAMPLE
This SSL/TLS client example, attempts to retrieve a page from an
SSL/TLS web server. The I/O routines are identical to those of the
unencrypted example in L<BIO_s_connect(3)>.
BIO *sbio, *out;
int len;
char tmpbuf[1024];
SSL_CTX *ctx;
SSL *ssl;
/* XXX Seed the PRNG if needed. */
ctx = SSL_CTX_new(TLS_client_method());
/* XXX Set verify paths and mode here. */
sbio = BIO_new_ssl_connect(ctx);
BIO_get_ssl(sbio, &ssl);
if (ssl == NULL) {
fprintf(stderr, "Can't locate SSL pointer\n");
ERR_print_errors_fp(stderr);
exit(1);
}
/* Don't want any retries */
SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY);
/* XXX We might want to do other things with ssl here */
/* An empty host part means the loopback address */
BIO_set_conn_hostname(sbio, ":https");
out = BIO_new_fp(stdout, BIO_NOCLOSE);
if (BIO_do_connect(sbio) <= 0) {
fprintf(stderr, "Error connecting to server\n");
ERR_print_errors_fp(stderr);
exit(1);
}
if (BIO_do_handshake(sbio) <= 0) {
fprintf(stderr, "Error establishing SSL connection\n");
ERR_print_errors_fp(stderr);
exit(1);
}
/* XXX Could examine ssl here to get connection info */
BIO_puts(sbio, "GET / HTTP/1.0\n\n");
for (;;) {
len = BIO_read(sbio, tmpbuf, 1024);
if (len <= 0)
break;
BIO_write(out, tmpbuf, len);
}
BIO_free_all(sbio);
BIO_free(out);
Here is a simple server example. It makes use of a buffering
BIO to allow lines to be read from the SSL BIO using BIO_gets.
It creates a pseudo web page containing the actual request from
a client and also echoes the request to standard output.
BIO *sbio, *bbio, *acpt, *out;
int len;
char tmpbuf[1024];
SSL_CTX *ctx;
SSL *ssl;
/* XXX Seed the PRNG if needed. */
ctx = SSL_CTX_new(TLS_server_method());
if (!SSL_CTX_use_certificate_file(ctx, "server.pem", SSL_FILETYPE_PEM)
|| !SSL_CTX_use_PrivateKey_file(ctx, "server.pem", SSL_FILETYPE_PEM)
|| !SSL_CTX_check_private_key(ctx)) {
fprintf(stderr, "Error setting up SSL_CTX\n");
ERR_print_errors_fp(stderr);
exit(1);
}
/* XXX Other things like set verify locations, EDH temp callbacks. */
/* New SSL BIO setup as server */
sbio = BIO_new_ssl(ctx, 0);
BIO_get_ssl(sbio, &ssl);
if (ssl == NULL) {
fprintf(stderr, "Can't locate SSL pointer\n");
ERR_print_errors_fp(stderr);
exit(1);
}
SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY);
bbio = BIO_new(BIO_f_buffer());
sbio = BIO_push(bbio, sbio);
acpt = BIO_new_accept("4433");
/*
* By doing this when a new connection is established
* we automatically have sbio inserted into it. The
* BIO chain is now 'swallowed' by the accept BIO and
* will be freed when the accept BIO is freed.
*/
BIO_set_accept_bios(acpt, sbio);
out = BIO_new_fp(stdout, BIO_NOCLOSE);
/* Setup accept BIO */
if (BIO_do_accept(acpt) <= 0) {
fprintf(stderr, "Error setting up accept BIO\n");
ERR_print_errors_fp(stderr);
exit(1);
}
/* We only want one connection so remove and free accept BIO */
sbio = BIO_pop(acpt);
BIO_free_all(acpt);
if (BIO_do_handshake(sbio) <= 0) {
fprintf(stderr, "Error in SSL handshake\n");
ERR_print_errors_fp(stderr);
exit(1);
}
BIO_puts(sbio, "HTTP/1.0 200 OK\r\nContent-type: text/plain\r\n\r\n");
BIO_puts(sbio, "\r\nConnection Established\r\nRequest headers:\r\n");
BIO_puts(sbio, "--------------------------------------------------\r\n");
for (;;) {
len = BIO_gets(sbio, tmpbuf, 1024);
if (len <= 0)
break;
BIO_write(sbio, tmpbuf, len);
BIO_write(out, tmpbuf, len);
/* Look for blank line signifying end of headers*/
if (tmpbuf[0] == '\r' || tmpbuf[0] == '\n')
break;
}
BIO_puts(sbio, "--------------------------------------------------\r\n");
BIO_puts(sbio, "\r\n");
BIO_flush(sbio);
BIO_free_all(sbio);
=head1 RETURN VALUES
BIO_f_ssl() returns the SSL B<BIO_METHOD> structure.
BIO_set_ssl(), BIO_get_ssl(), BIO_set_ssl_mode(), BIO_set_ssl_renegotiate_bytes(),
BIO_set_ssl_renegotiate_timeout() and BIO_get_num_renegotiates() return 1 on
success or a value which is less than or equal to 0 if an error occurred.
BIO_new_ssl(), BIO_new_ssl_connect() and BIO_new_buffer_ssl_connect() return
a valid B<BIO> structure on success or B<NULL> if an error occurred.
BIO_ssl_copy_session_id() returns 1 on success or 0 on error.
BIO_do_handshake() returns 1 if the connection was established successfully.
A zero or negative value is returned if the connection could not be established.
=head1 HISTORY
In OpenSSL before 1.0.0 the BIO_pop() call was handled incorrectly,
the I/O BIO reference count was incorrectly incremented (instead of
decremented) and dissociated with the SSL BIO even if the SSL BIO was not
explicitly being popped (e.g. a pop higher up the chain). Applications which
included workarounds for this bug (e.g. freeing BIOs more than once) should
be modified to handle this fix or they may free up an already freed BIO.
=head1 COPYRIGHT
Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

70
doc/man3/BIO_find_type.pod Normal file
View File

@@ -0,0 +1,70 @@
=pod
=head1 NAME
BIO_find_type, BIO_next, BIO_method_type - BIO chain traversal
=head1 SYNOPSIS
#include <openssl/bio.h>
BIO *BIO_find_type(BIO *b, int bio_type);
BIO *BIO_next(BIO *b);
int BIO_method_type(const BIO *b);
=head1 DESCRIPTION
The BIO_find_type() searches for a BIO of a given type in a chain, starting
at BIO B<b>. If B<type> is a specific type (such as B<BIO_TYPE_MEM>) then a search
is made for a BIO of that type. If B<type> is a general type (such as
B<BIO_TYPE_SOURCE_SINK>) then the next matching BIO of the given general type is
searched for. BIO_find_type() returns the next matching BIO or NULL if none is
found.
The following general types are defined:
B<BIO_TYPE_DESCRIPTOR>, B<BIO_TYPE_FILTER>, and B<BIO_TYPE_SOURCE_SINK>.
For a list of the specific types, see the B<openssl/bio.h> header file.
BIO_next() returns the next BIO in a chain. It can be used to traverse all BIOs
in a chain or used in conjunction with BIO_find_type() to find all BIOs of a
certain type.
BIO_method_type() returns the type of a BIO.
=head1 RETURN VALUES
BIO_find_type() returns a matching BIO or NULL for no match.
BIO_next() returns the next BIO in a chain.
BIO_method_type() returns the type of the BIO B<b>.
=head1 EXAMPLE
Traverse a chain looking for digest BIOs:
BIO *btmp;
btmp = in_bio; /* in_bio is chain to search through */
do {
btmp = BIO_find_type(btmp, BIO_TYPE_MD);
if (btmp == NULL)
break; /* Not found */
/* btmp is a digest BIO, do something with it ...*/
...
btmp = BIO_next(btmp);
} while (btmp);
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

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

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

72
doc/man3/BIO_get_ex_new_index.pod Normal file
View File

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

164
doc/man3/BIO_meth_new.pod Normal file
View File

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

71
doc/man3/BIO_new.pod Normal file
View File

@@ -0,0 +1,71 @@
=pod
=head1 NAME
BIO_new, BIO_up_ref, BIO_free, BIO_vfree, BIO_free_all
- BIO allocation and freeing functions
=head1 SYNOPSIS
#include <openssl/bio.h>
BIO * BIO_new(const BIO_METHOD *type);
int BIO_up_ref(BIO *a);
int BIO_free(BIO *a);
void BIO_vfree(BIO *a);
void BIO_free_all(BIO *a);
=head1 DESCRIPTION
The BIO_new() function returns a new BIO using method B<type>.
BIO_up_ref() increments the reference count associated with the BIO object.
BIO_free() frees up a single BIO, BIO_vfree() also frees up a single BIO
but it does not return a value.
If B<a> is NULL nothing is done.
Calling BIO_free() may also have some effect
on the underlying I/O structure, for example it may close the file being
referred to under certain circumstances. For more details see the individual
BIO_METHOD descriptions.
BIO_free_all() frees up an entire BIO chain, it does not halt if an error
occurs freeing up an individual BIO in the chain.
If B<a> is NULL nothing is done.
=head1 RETURN VALUES
BIO_new() returns a newly created BIO or NULL if the call fails.
BIO_up_ref() and BIO_free() return 1 for success and 0 for failure.
BIO_free_all() and BIO_vfree() do not return values.
=head1 NOTES
If BIO_free() is called on a BIO chain it will only free one BIO resulting
in a memory leak.
Calling BIO_free_all() on a single BIO has the same effect as calling BIO_free()
on it other than the discarded return value.
=head1 HISTORY
BIO_set() was removed in OpenSSL 1.1.0 as BIO type is now opaque.
=head1 EXAMPLE
Create a memory BIO:
BIO *mem = BIO_new(BIO_s_mem());
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

75
doc/man3/BIO_new_CMS.pod Normal file
View File

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

78
doc/man3/BIO_parse_hostserv.pod Normal file
View File

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

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

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

89
doc/man3/BIO_push.pod Normal file
View File

@@ -0,0 +1,89 @@
=pod
=head1 NAME
BIO_push, BIO_pop, BIO_set_next - add and remove BIOs from a chain
=head1 SYNOPSIS
#include <openssl/bio.h>
BIO *BIO_push(BIO *b, BIO *append);
BIO *BIO_pop(BIO *b);
void BIO_set_next(BIO *b, BIO *next);
=head1 DESCRIPTION
The BIO_push() function appends the BIO B<append> to B<b>, it returns
B<b>.
BIO_pop() removes the BIO B<b> from a chain and returns the next BIO
in the chain, or NULL if there is no next BIO. The removed BIO then
becomes a single BIO with no association with the original chain,
it can thus be freed or attached to a different chain.
BIO_set_next() replaces the existing next BIO in a chain with the BIO pointed to
by B<next>. The new chain may include some of the same BIOs from the old chain
or it may be completely different.
=head1 NOTES
The names of these functions are perhaps a little misleading. BIO_push()
joins two BIO chains whereas BIO_pop() deletes a single BIO from a chain,
the deleted BIO does not need to be at the end of a chain.
The process of calling BIO_push() and BIO_pop() on a BIO may have additional
consequences (a control call is made to the affected BIOs) any effects will
be noted in the descriptions of individual BIOs.
=head1 EXAMPLES
For these examples suppose B<md1> and B<md2> are digest BIOs, B<b64> is
a base64 BIO and B<f> is a file BIO.
If the call:
BIO_push(b64, f);
is made then the new chain will be B<b64-f>. After making the calls
BIO_push(md2, b64);
BIO_push(md1, md2);
the new chain is B<md1-md2-b64-f>. Data written to B<md1> will be digested
by B<md1> and B<md2>, B<base64> encoded and written to B<f>.
It should be noted that reading causes data to pass in the reverse
direction, that is data is read from B<f>, base64 B<decoded> and digested
by B<md1> and B<md2>. If the call:
BIO_pop(md2);
The call will return B<b64> and the new chain will be B<md1-b64-f> data can
be written to B<md1> as before.
=head1 RETURN VALUES
BIO_push() returns the end of the chain, B<b>.
BIO_pop() returns the next BIO in the chain, or NULL if there is no next
BIO.
=head1 SEE ALSO
L<bio>
=head1 HISTORY
The BIO_set_next() function was added in OpenSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

97
doc/man3/BIO_read.pod Normal file
View File

@@ -0,0 +1,97 @@
=pod
=head1 NAME
BIO_read_ex, BIO_write_ex, BIO_read, BIO_write, BIO_gets, BIO_puts
- BIO I/O functions
=head1 SYNOPSIS
#include <openssl/bio.h>
int BIO_read_ex(BIO *b, void *data, size_t dlen, size_t *readbytes);
int BIO_write_ex(BIO *b, const void *data, size_t dlen, size_t *written);
int BIO_read(BIO *b, void *data, int dlen);
int BIO_gets(BIO *b, char *buf, int size);
int BIO_write(BIO *b, const void *data, int dlen);
int BIO_puts(BIO *b, const char *buf);
=head1 DESCRIPTION
BIO_read_ex() attempts to read B<dlen> bytes from BIO B<b> and places the data
in B<data>. If any bytes were successfully read then the number of bytes read is
stored in B<*readbytes>.
BIO_write_ex() attempts to write B<dlen> bytes from B<data> to BIO B<b>. If
successful then the number of bytes written is stored in B<*written>.
BIO_read() attempts to read B<len> bytes from BIO B<b> and places
the data in B<buf>.
BIO_gets() performs the BIOs "gets" operation and places the data
in B<buf>. Usually this operation will attempt to read a line of data
from the BIO of maximum length B<size-1>. There are exceptions to this,
however; for example, BIO_gets() on a digest BIO will calculate and
return the digest and other BIOs may not support BIO_gets() at all.
The returned string is always NUL-terminated and the '\n' is preserved
if present in the input data.
BIO_write() attempts to write B<len> bytes from B<buf> to BIO B<b>.
BIO_puts() attempts to write a NUL-terminated string B<buf> to BIO B<b>.
=head1 RETURN VALUES
BIO_read_ex() and BIO_write_ex() return 1 if data was successfully read or
written, and 0 otherwise.
All other functions return either the amount of data successfully read or
written (if the return value is positive) or that no data was successfully
read or written if the result is 0 or -1. If the return value is -2 then
the operation is not implemented in the specific BIO type. The trailing
NUL is not included in the length returned by BIO_gets().
=head1 NOTES
A 0 or -1 return is not necessarily an indication of an error. In
particular when the source/sink is non-blocking or of a certain type
it may merely be an indication that no data is currently available and that
the application should retry the operation later.
One technique sometimes used with blocking sockets is to use a system call
(such as select(), poll() or equivalent) to determine when data is available
and then call read() to read the data. The equivalent with BIOs (that is call
select() on the underlying I/O structure and then call BIO_read() to
read the data) should B<not> be used because a single call to BIO_read()
can cause several reads (and writes in the case of SSL BIOs) on the underlying
I/O structure and may block as a result. Instead select() (or equivalent)
should be combined with non blocking I/O so successive reads will request
a retry instead of blocking.
See L<BIO_should_retry(3)> for details of how to
determine the cause of a retry and other I/O issues.
If the BIO_gets() function is not supported by a BIO then it possible to
work around this by adding a buffering BIO L<BIO_f_buffer(3)>
to the chain.
=head1 SEE ALSO
L<BIO_should_retry(3)>
=head1 HISTORY
BIO_gets() on 1.1.0 and older when called on BIO_fd() based BIO does not
keep the '\n' at the end of the line in the buffer.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

234
doc/man3/BIO_s_accept.pod Normal file
View File

@@ -0,0 +1,234 @@
=pod
=head1 NAME
BIO_s_accept, BIO_set_accept_name, BIO_set_accept_port, BIO_get_accept_name,
BIO_get_accept_port, BIO_new_accept, BIO_set_nbio_accept, BIO_set_accept_bios,
BIO_get_peer_name, BIO_get_peer_port,
BIO_get_accept_ip_family, BIO_set_accept_ip_family,
BIO_set_bind_mode, BIO_get_bind_mode, BIO_do_accept - accept BIO
=head1 SYNOPSIS
#include <openssl/bio.h>
const BIO_METHOD *BIO_s_accept(void);
long BIO_set_accept_name(BIO *b, char *name);
char *BIO_get_accept_name(BIO *b);
long BIO_set_accept_port(BIO *b, char *port);
char *BIO_get_accept_port(BIO *b);
BIO *BIO_new_accept(char *host_port);
long BIO_set_nbio_accept(BIO *b, int n);
long BIO_set_accept_bios(BIO *b, char *bio);
char *BIO_get_peer_name(BIO *b);
char *BIO_get_peer_port(BIO *b);
long BIO_get_accept_ip_family(BIO *b);
long BIO_set_accept_ip_family(BIO *b, long family);
long BIO_set_bind_mode(BIO *b, long mode);
long BIO_get_bind_mode(BIO *b);
int BIO_do_accept(BIO *b);
=head1 DESCRIPTION
BIO_s_accept() returns the accept BIO method. This is a wrapper
round the platform's TCP/IP socket accept routines.
Using accept BIOs, TCP/IP connections can be accepted and data
transferred using only BIO routines. In this way any platform
specific operations are hidden by the BIO abstraction.
Read and write operations on an accept BIO will perform I/O
on the underlying connection. If no connection is established
and the port (see below) is set up properly then the BIO
waits for an incoming connection.
Accept BIOs support BIO_puts() but not BIO_gets().
If the close flag is set on an accept BIO then any active
connection on that chain is shutdown and the socket closed when
the BIO is freed.
Calling BIO_reset() on an accept BIO will close any active
connection and reset the BIO into a state where it awaits another
incoming connection.
BIO_get_fd() and BIO_set_fd() can be called to retrieve or set
the accept socket. See L<BIO_s_fd(3)>
BIO_set_accept_name() uses the string B<name> to set the accept
name. The name is represented as a string of the form "host:port",
where "host" is the interface to use and "port" is the port.
The host can be "*" or empty which is interpreted as meaning
any interface. If the host is an IPv6 address, it has to be
enclosed in brackets, for example "[::1]:https". "port" has the
same syntax as the port specified in BIO_set_conn_port() for
connect BIOs, that is it can be a numerical port string or a
string to lookup using getservbyname() and a string table.
BIO_set_accept_port() uses the string B<port> to set the accept
port. "port" has the same syntax as the port specified in
BIO_set_conn_port() for connect BIOs, that is it can be a numerical
port string or a string to lookup using getservbyname() and a string
table.
BIO_new_accept() combines BIO_new() and BIO_set_accept_name() into
a single call: that is it creates a new accept BIO with port
B<host_port>.
BIO_set_nbio_accept() sets the accept socket to blocking mode
(the default) if B<n> is 0 or non blocking mode if B<n> is 1.
BIO_set_accept_bios() can be used to set a chain of BIOs which
will be duplicated and prepended to the chain when an incoming
connection is received. This is useful if, for example, a
buffering or SSL BIO is required for each connection. The
chain of BIOs must not be freed after this call, they will
be automatically freed when the accept BIO is freed.
BIO_set_bind_mode() and BIO_get_bind_mode() set and retrieve
the current bind mode. If B<BIO_BIND_NORMAL> (the default) is set
then another socket cannot be bound to the same port. If
B<BIO_BIND_REUSEADDR> is set then other sockets can bind to the
same port. If B<BIO_BIND_REUSEADDR_IF_UNUSED> is set then and
attempt is first made to use BIO_BIN_NORMAL, if this fails
and the port is not in use then a second attempt is made
using B<BIO_BIND_REUSEADDR>.
BIO_do_accept() serves two functions. When it is first
called, after the accept BIO has been setup, it will attempt
to create the accept socket and bind an address to it. Second
and subsequent calls to BIO_do_accept() will await an incoming
connection, or request a retry in non blocking mode.
=head1 NOTES
When an accept BIO is at the end of a chain it will await an
incoming connection before processing I/O calls. When an accept
BIO is not at then end of a chain it passes I/O calls to the next
BIO in the chain.
When a connection is established a new socket BIO is created for
the connection and appended to the chain. That is the chain is now
accept->socket. This effectively means that attempting I/O on
an initial accept socket will await an incoming connection then
perform I/O on it.
If any additional BIOs have been set using BIO_set_accept_bios()
then they are placed between the socket and the accept BIO,
that is the chain will be accept->otherbios->socket.
If a server wishes to process multiple connections (as is normally
the case) then the accept BIO must be made available for further
incoming connections. This can be done by waiting for a connection and
then calling:
connection = BIO_pop(accept);
After this call B<connection> will contain a BIO for the recently
established connection and B<accept> will now be a single BIO
again which can be used to await further incoming connections.
If no further connections will be accepted the B<accept> can
be freed using BIO_free().
If only a single connection will be processed it is possible to
perform I/O using the accept BIO itself. This is often undesirable
however because the accept BIO will still accept additional incoming
connections. This can be resolved by using BIO_pop() (see above)
and freeing up the accept BIO after the initial connection.
If the underlying accept socket is non-blocking and BIO_do_accept() is
called to await an incoming connection it is possible for
BIO_should_io_special() with the reason BIO_RR_ACCEPT. If this happens
then it is an indication that an accept attempt would block: the application
should take appropriate action to wait until the underlying socket has
accepted a connection and retry the call.
BIO_set_accept_name(), BIO_get_accept_name(), BIO_set_accept_port(),
BIO_get_accept_port(), BIO_set_nbio_accept(), BIO_set_accept_bios(),
BIO_get_peer_name(), BIO_get_peer_port(),
BIO_get_accept_ip_family(), BIO_set_accept_ip_family(),
BIO_set_bind_mode(), BIO_get_bind_mode() and BIO_do_accept() are macros.
=head1 RETURN VALUES
BIO_do_accept(),
BIO_set_accept_name(), BIO_set_accept_port(), BIO_set_nbio_accept(),
BIO_set_accept_bios(), BIO_set_accept_ip_family(), and BIO_set_bind_mode()
return 1 for success and 0 or -1 for failure.
BIO_get_accept_name() returns the accept name or NULL on error.
BIO_get_peer_name() returns the peer name or NULL on error.
BIO_get_accept_port() returns the accept port as a string or NULL on error.
BIO_get_peer_port() returns the peer port as a string or NULL on error.
BIO_get_accept_ip_family() returns the IP family or -1 on error.
BIO_get_bind_mode() returns the set of B<BIO_BIND> flags, or -1 on failure.
BIO_new_accept() returns a BIO or NULL on error.
=head1 EXAMPLE
This example accepts two connections on port 4444, sends messages
down each and finally closes both down.
BIO *abio, *cbio, *cbio2;
/* First call to BIO_accept() sets up accept BIO */
abio = BIO_new_accept("4444");
if (BIO_do_accept(abio) <= 0) {
fprintf(stderr, "Error setting up accept\n");
ERR_print_errors_fp(stderr);
exit(1);
}
/* Wait for incoming connection */
if (BIO_do_accept(abio) <= 0) {
fprintf(stderr, "Error accepting connection\n");
ERR_print_errors_fp(stderr);
exit(1);
}
fprintf(stderr, "Connection 1 established\n");
/* Retrieve BIO for connection */
cbio = BIO_pop(abio);
BIO_puts(cbio, "Connection 1: Sending out Data on initial connection\n");
fprintf(stderr, "Sent out data on connection 1\n");
/* Wait for another connection */
if (BIO_do_accept(abio) <= 0) {
fprintf(stderr, "Error accepting connection\n");
ERR_print_errors_fp(stderr);
exit(1);
}
fprintf(stderr, "Connection 2 established\n");
/* Close accept BIO to refuse further connections */
cbio2 = BIO_pop(abio);
BIO_free(abio);
BIO_puts(cbio2, "Connection 2: Sending out Data on second\n");
fprintf(stderr, "Sent out data on connection 2\n");
BIO_puts(cbio, "Connection 1: Second connection established\n");
/* Close the two established connections */
BIO_free(cbio);
BIO_free(cbio2);
=head1 COPYRIGHT
Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

201
doc/man3/BIO_s_bio.pod Normal file
View File

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

213
doc/man3/BIO_s_connect.pod Normal file
View File

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

98
doc/man3/BIO_s_fd.pod Normal file
View File

@@ -0,0 +1,98 @@
=pod
=head1 NAME
BIO_s_fd, BIO_set_fd, BIO_get_fd, BIO_new_fd - file descriptor BIO
=head1 SYNOPSIS
#include <openssl/bio.h>
const BIO_METHOD *BIO_s_fd(void);
int BIO_set_fd(BIO *b, int fd, int c);
int BIO_get_fd(BIO *b, int *c);
BIO *BIO_new_fd(int fd, int close_flag);
=head1 DESCRIPTION
BIO_s_fd() returns the file descriptor BIO method. This is a wrapper
round the platforms file descriptor routines such as read() and write().
BIO_read_ex() and BIO_write_ex() read or write the underlying descriptor.
BIO_puts() is supported but BIO_gets() is not.
If the close flag is set then close() is called on the underlying
file descriptor when the BIO is freed.
BIO_reset() attempts to change the file pointer to the start of file
such as by using B<lseek(fd, 0, 0)>.
BIO_seek() sets the file pointer to position B<ofs> from start of file
such as by using B<lseek(fd, ofs, 0)>.
BIO_tell() returns the current file position such as by calling
B<lseek(fd, 0, 1)>.
BIO_set_fd() sets the file descriptor of BIO B<b> to B<fd> and the close
flag to B<c>.
BIO_get_fd() places the file descriptor in B<c> if it is not NULL, it also
returns the file descriptor.
BIO_new_fd() returns a file descriptor BIO using B<fd> and B<close_flag>.
=head1 NOTES
The behaviour of BIO_read_ex() and BIO_write_ex() depends on the behavior of the
platforms read() and write() calls on the descriptor. If the underlying
file descriptor is in a non blocking mode then the BIO will behave in the
manner described in the L<BIO_read_ex(3)> and L<BIO_should_retry(3)>
manual pages.
File descriptor BIOs should not be used for socket I/O. Use socket BIOs
instead.
BIO_set_fd() and BIO_get_fd() are implemented as macros.
=head1 RETURN VALUES
BIO_s_fd() returns the file descriptor BIO method.
BIO_set_fd() always returns 1.
BIO_get_fd() returns the file descriptor or -1 if the BIO has not
been initialized.
BIO_new_fd() returns the newly allocated BIO or NULL is an error
occurred.
=head1 EXAMPLE
This is a file descriptor BIO version of "Hello World":
BIO *out;
out = BIO_new_fd(fileno(stdout), BIO_NOCLOSE);
BIO_printf(out, "Hello World\n");
BIO_free(out);
=head1 SEE ALSO
L<BIO_seek(3)>, L<BIO_tell(3)>,
L<BIO_reset(3)>, L<BIO_read_ex(3)>,
L<BIO_write_ex(3)>, L<BIO_puts(3)>,
L<BIO_gets(3)>, L<BIO_printf(3)>,
L<BIO_set_close(3)>, L<BIO_get_close(3)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

168
doc/man3/BIO_s_file.pod Normal file
View File

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

134
doc/man3/BIO_s_mem.pod Normal file
View File

@@ -0,0 +1,134 @@
=pod
=head1 NAME
BIO_s_secmem,
BIO_s_mem, BIO_set_mem_eof_return, BIO_get_mem_data, BIO_set_mem_buf,
BIO_get_mem_ptr, BIO_new_mem_buf - memory BIO
=head1 SYNOPSIS
#include <openssl/bio.h>
const BIO_METHOD *BIO_s_mem(void);
const BIO_METHOD *BIO_s_secmem(void);
BIO_set_mem_eof_return(BIO *b, int v)
long BIO_get_mem_data(BIO *b, char **pp)
BIO_set_mem_buf(BIO *b, BUF_MEM *bm, int c)
BIO_get_mem_ptr(BIO *b, BUF_MEM **pp)
BIO *BIO_new_mem_buf(const void *buf, int len);
=head1 DESCRIPTION
BIO_s_mem() returns the memory BIO method function.
A memory BIO is a source/sink BIO which uses memory for its I/O. Data
written to a memory BIO is stored in a BUF_MEM structure which is extended
as appropriate to accommodate the stored data.
BIO_s_secmem() is like BIO_s_mem() except that the secure heap is used
for buffer storage.
Any data written to a memory BIO can be recalled by reading from it.
Unless the memory BIO is read only any data read from it is deleted from
the BIO.
Memory BIOs support BIO_gets() and BIO_puts().
If the BIO_CLOSE flag is set when a memory BIO is freed then the underlying
BUF_MEM structure is also freed.
Calling BIO_reset() on a read write memory BIO clears any data in it if the
flag BIO_FLAGS_NONCLEAR_RST is not set. On a read only BIO or if the flag
BIO_FLAGS_NONCLEAR_RST is set it restores the BIO to its original state and
the data can be read again.
BIO_eof() is true if no data is in the BIO.
BIO_ctrl_pending() returns the number of bytes currently stored.
BIO_set_mem_eof_return() sets the behaviour of memory BIO B<b> when it is
empty. If the B<v> is zero then an empty memory BIO will return EOF (that is
it will return zero and BIO_should_retry(b) will be false. If B<v> is non
zero then it will return B<v> when it is empty and it will set the read retry
flag (that is BIO_read_retry(b) is true). To avoid ambiguity with a normal
positive return value B<v> should be set to a negative value, typically -1.
BIO_get_mem_data() sets *B<pp> to a pointer to the start of the memory BIOs data
and returns the total amount of data available. It is implemented as a macro.
BIO_set_mem_buf() sets the internal BUF_MEM structure to B<bm> and sets the
close flag to B<c>, that is B<c> should be either BIO_CLOSE or BIO_NOCLOSE.
It is a macro.
BIO_get_mem_ptr() places the underlying BUF_MEM structure in *B<pp>. It is
a macro.
BIO_new_mem_buf() creates a memory BIO using B<len> bytes of data at B<buf>,
if B<len> is -1 then the B<buf> is assumed to be nul terminated and its
length is determined by B<strlen>. The BIO is set to a read only state and
as a result cannot be written to. This is useful when some data needs to be
made available from a static area of memory in the form of a BIO. The
supplied data is read directly from the supplied buffer: it is B<not> copied
first, so the supplied area of memory must be unchanged until the BIO is freed.
=head1 NOTES
Writes to memory BIOs will always succeed if memory is available: that is
their size can grow indefinitely.
Every read from a read write memory BIO will remove the data just read with
an internal copy operation, if a BIO contains a lot of data and it is
read in small chunks the operation can be very slow. The use of a read only
memory BIO avoids this problem. If the BIO must be read write then adding
a buffering BIO to the chain will speed up the process.
Calling BIO_set_mem_buf() on a BIO created with BIO_new_secmem() will
give undefined results, including perhaps a program crash.
=head1 BUGS
There should be an option to set the maximum size of a memory BIO.
=head1 EXAMPLE
Create a memory BIO and write some data to it:
BIO *mem = BIO_new(BIO_s_mem());
BIO_puts(mem, "Hello World\n");
Create a read only memory BIO:
char data[] = "Hello World";
BIO *mem = BIO_new_mem_buf(data, -1);
Extract the BUF_MEM structure from a memory BIO and then free up the BIO:
BUF_MEM *bptr;
BIO_get_mem_ptr(mem, &bptr);
BIO_set_close(mem, BIO_NOCLOSE); /* So BIO_free() leaves BUF_MEM alone */
BIO_free(mem);
=head1 RETURN VALUES
BIO_s_mem() and BIO_s_secmem() return a valid memory B<BIO_METHOD> structure.
BIO_set_mem_eof_return(), BIO_get_mem_data(), BIO_set_mem_buf() and BIO_get_mem_ptr()
return 1 on success or a value which is less than or equal to 0 if an error occurred.
BIO_new_mem_buf() returns a valid B<BIO> structure on success or NULL on error.
=head1 COPYRIGHT
Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

44
doc/man3/BIO_s_null.pod Normal file
View File

@@ -0,0 +1,44 @@
=pod
=head1 NAME
BIO_s_null - null data sink
=head1 SYNOPSIS
#include <openssl/bio.h>
const BIO_METHOD *BIO_s_null(void);
=head1 DESCRIPTION
BIO_s_null() returns the null sink BIO method. Data written to
the null sink is discarded, reads return EOF.
=head1 NOTES
A null sink BIO behaves in a similar manner to the Unix /dev/null
device.
A null bio can be placed on the end of a chain to discard any data
passed through it.
A null sink is useful if, for example, an application wishes to digest some
data by writing through a digest bio but not send the digested data anywhere.
Since a BIO chain must normally include a source/sink BIO this can be achieved
by adding a null sink BIO to the end of the chain
=head1 RETURN VALUES
BIO_s_null() returns the null sink BIO method.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

54
doc/man3/BIO_s_socket.pod Normal file
View File

@@ -0,0 +1,54 @@
=pod
=head1 NAME
BIO_s_socket, BIO_new_socket - socket BIO
=head1 SYNOPSIS
#include <openssl/bio.h>
const BIO_METHOD *BIO_s_socket(void);
BIO *BIO_new_socket(int sock, int close_flag);
=head1 DESCRIPTION
BIO_s_socket() returns the socket BIO method. This is a wrapper
round the platform's socket routines.
BIO_read_ex() and BIO_write_ex() read or write the underlying socket.
BIO_puts() is supported but BIO_gets() is not.
If the close flag is set then the socket is shut down and closed
when the BIO is freed.
BIO_new_socket() returns a socket BIO using B<sock> and B<close_flag>.
=head1 NOTES
Socket BIOs also support any relevant functionality of file descriptor
BIOs.
The reason for having separate file descriptor and socket BIOs is that on some
platforms sockets are not file descriptors and use distinct I/O routines,
Windows is one such platform. Any code mixing the two will not work on
all platforms.
=head1 RETURN VALUES
BIO_s_socket() returns the socket BIO method.
BIO_new_socket() returns the newly allocated BIO or NULL is an error
occurred.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

240
doc/man3/BIO_set_callback.pod Normal file
View File

@@ -0,0 +1,240 @@
=pod
=head1 NAME
BIO_set_callback_ex, BIO_get_callback_ex, BIO_set_callback, BIO_get_callback,
BIO_set_callback_arg, BIO_get_callback_arg, BIO_debug_callback,
BIO_callback_fn_ex, BIO_callback_fn
- BIO callback functions
=head1 SYNOPSIS
#include <openssl/bio.h>
typedef long (*BIO_callback_fn_ex)(BIO *b, int oper, const char *argp,
size_t len, int argi,
long argl, int ret, size_t *processed);
typedef long (*BIO_callback_fn)(BIO *b, int oper, const char *argp, int argi,
long argl, long ret);
void BIO_set_callback_ex(BIO *b, BIO_callback_fn_ex callback);
BIO_callback_fn_ex BIO_get_callback_ex(const BIO *b);
void BIO_set_callback(BIO *b, BIO_callback_fn cb);
BIO_callback_fn BIO_get_callback(BIO *b);
void BIO_set_callback_arg(BIO *b, char *arg);
char *BIO_get_callback_arg(const BIO *b);
long BIO_debug_callback(BIO *bio, int cmd, const char *argp, int argi,
long argl, long ret);
=head1 DESCRIPTION
BIO_set_callback_ex() and BIO_get_callback_ex() set and retrieve the BIO
callback. The callback is called during most high level BIO operations. It can
be used for debugging purposes to trace operations on a BIO or to modify its
operation.
BIO_set_callback() and BIO_get_callback() set and retrieve the old format BIO
callback. New code should not use these functions, but they are retained for
backwards compatibility. Any callback set via BIO_set_callback_ex() will get
called in preference to any set by BIO_set_callback().
BIO_set_callback_arg() and BIO_get_callback_arg() are macros which can be
used to set and retrieve an argument for use in the callback.
BIO_debug_callback() is a standard debugging callback which prints
out information relating to each BIO operation. If the callback
argument is set it is interpreted as a BIO to send the information
to, otherwise stderr is used.
BIO_callback_fn_ex() is the type of the callback function and BIO_callback_fn()
is the type of the old format callback function. The meaning of each argument
is described below:
=over 4
=item B<b>
The BIO the callback is attached to is passed in B<b>.
=item B<oper>
B<oper> is set to the operation being performed. For some operations
the callback is called twice, once before and once after the actual
operation, the latter case has B<oper> or'ed with BIO_CB_RETURN.
=item B<len>
The length of the data requested to be read or written. This is only useful if
B<oper> is BIO_CB_READ, BIO_CB_WRITE or BIO_CB_GETS.
=item B<argp> B<argi> B<argl>
The meaning of the arguments B<argp>, B<argi> and B<argl> depends on
the value of B<oper>, that is the operation being performed.
=item B<processed>
B<processed> is a pointer to a location which will be updated with the amount of
data that was actually read or written. Only used for BIO_CB_READ, BIO_CB_WRITE,
BIO_CB_GETS and BIO_CB_PUTS.
=item B<ret>
B<ret> is the return value that would be returned to the
application if no callback were present. The actual value returned
is the return value of the callback itself. In the case of callbacks
called before the actual BIO operation 1 is placed in B<ret>, if
the return value is not positive it will be immediately returned to
the application and the BIO operation will not be performed.
=back
The callback should normally simply return B<ret> when it has
finished processing, unless it specifically wishes to modify the
value returned to the application.
=head1 CALLBACK OPERATIONS
In the notes below, B<callback> defers to the actual callback
function that is called.
=over 4
=item B<BIO_free(b)>
callback_ex(b, BIO_CB_FREE, NULL, 0, 0, 0L, 1L, NULL)
or
callback(b, BIO_CB_FREE, NULL, 0L, 0L, 1L)
is called before the free operation.
=item B<BIO_read_ex(b, data, dlen, readbytes)>
callback_ex(b, BIO_CB_READ, data, dlen, 0, 0L, 1L, NULL)
or
callback(b, BIO_CB_READ, data, dlen, 0L, 1L)
is called before the read and
callback_ex(b, BIO_CB_READ | BIO_CB_RETURN, data, dlen, 0, 0L, retvalue,
&readbytes)
or
callback(b, BIO_CB_READ|BIO_CB_RETURN, data, dlen, 0L, retvalue)
after.
=item B<BIO_write(b, data, dlen, written)>
callback_ex(b, BIO_CB_WRITE, data, dlen, 0, 0L, 1L, NULL)
or
callback(b, BIO_CB_WRITE, datat, dlen, 0L, 1L)
is called before the write and
callback_ex(b, BIO_CB_WRITE | BIO_CB_RETURN, data, dlen, 0, 0L, retvalue,
&written)
or
callback(b, BIO_CB_WRITE|BIO_CB_RETURN, data, dlen, 0L, retvalue)
after.
=item B<BIO_gets(b, buf, size)>
callback_ex(b, BIO_CB_GETS, buf, size, 0, 0L, 1, NULL, NULL)
or
callback(b, BIO_CB_GETS, buf, size, 0L, 1L)
is called before the operation and
callback_ex(b, BIO_CB_GETS | BIO_CB_RETURN, buf, size, 0, 0L, retvalue,
&readbytes)
or
callback(b, BIO_CB_GETS|BIO_CB_RETURN, buf, size, 0L, retvalue)
after.
=item B<BIO_puts(b, buf)>
callback_ex(b, BIO_CB_PUTS, buf, 0, 0, 0L, 1L, NULL);
or
callback(b, BIO_CB_PUTS, buf, 0, 0L, 1L)
is called before the operation and
callback_ex(b, BIO_CB_PUTS | BIO_CB_RETURN, buf, 0, 0, 0L, retvalue, &written)
or
callback(b, BIO_CB_PUTS|BIO_CB_RETURN, buf, 0, 0L, retvalue)
after.
=item B<BIO_ctrl(BIO *b, int cmd, long larg, void *parg)>
callback_ex(b, BIO_CB_CTRL, parg, 0, cmd, larg, 1L, NULL)
or
callback(b, BIO_CB_CTRL, parg, cmd, larg, 1L)
is called before the call and
callback_ex(b, BIO_CB_CTRL | BIO_CB_RETURN, parg, 0, cmd, larg, ret, NULL)
or
callback(b, BIO_CB_CTRL|BIO_CB_RETURN, parg, cmd, larg, ret)
after.
Note: B<cmd> == B<BIO_CTRL_SET_CALLBACK> is special, because B<parg> is not the
argument of type B<BIO_info_cb> itself. In this case B<parg> is a pointer to
the actual call parameter, see B<BIO_callback_ctrl>.
=back
=head1 EXAMPLE
The BIO_debug_callback() function is a good example, its source is
in crypto/bio/bio_cb.c
=head1 RETURN VALUES
BIO_get_callback_ex() and BIO_get_callback() return the callback function
previously set by a call to BIO_set_callback_ex() and BIO_set_callback()
respectively.
BIO_get_callback_arg() returns a B<char> pointer to the value previously set
via a call to BIO_set_callback_arg().
BIO_debug_callback() returns 1 or B<ret> if it's called after specific BIO
operations.
=head1 COPYRIGHT
Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

147
doc/man3/BIO_should_retry.pod Normal file
View File

@@ -0,0 +1,147 @@
=pod
=head1 NAME
BIO_should_read, BIO_should_write,
BIO_should_io_special, BIO_retry_type, BIO_should_retry,
BIO_get_retry_BIO, BIO_get_retry_reason, BIO_set_retry_reason - BIO retry
functions
=head1 SYNOPSIS
#include <openssl/bio.h>
int BIO_should_read(BIO *b);
int BIO_should_write(BIO *b);
int BIO_should_io_special(iBIO *b);
int BIO_retry_type(BIO *b);
int BIO_should_retry(BIO *b);
BIO *BIO_get_retry_BIO(BIO *bio, int *reason);
int BIO_get_retry_reason(BIO *bio);
void BIO_set_retry_reason(BIO *bio, int reason);
=head1 DESCRIPTION
These functions determine why a BIO is not able to read or write data.
They will typically be called after a failed BIO_read_ex() or BIO_write_ex()
call.
BIO_should_retry() is true if the call that produced this condition
should then be retried at a later time.
If BIO_should_retry() is false then the cause is an error condition.
BIO_should_read() is true if the cause of the condition is that the BIO
has insufficient data to return. Check for readability and/or retry the
last operation.
BIO_should_write() is true if the cause of the condition is that the BIO
has pending data to write. Check for writability and/or retry the
last operation.
BIO_should_io_special() is true if some "special" condition, that is a
reason other than reading or writing is the cause of the condition.
BIO_retry_type() returns a mask of the cause of a retry condition
consisting of the values B<BIO_FLAGS_READ>, B<BIO_FLAGS_WRITE>,
B<BIO_FLAGS_IO_SPECIAL> though current BIO types will only set one of
these.
BIO_get_retry_BIO() determines the precise reason for the special
condition, it returns the BIO that caused this condition and if
B<reason> is not NULL it contains the reason code. The meaning of
the reason code and the action that should be taken depends on
the type of BIO that resulted in this condition.
BIO_get_retry_reason() returns the reason for a special condition if
passed the relevant BIO, for example as returned by BIO_get_retry_BIO().
BIO_set_retry_reason() sets the retry reason for a special condition for a given
BIO. This would usually only be called by BIO implementations.
=head1 NOTES
BIO_should_read(), BIO_should_write(), BIO_should_io_special(),
BIO_retry_type(), and BIO_should_retry(), are implemented as macros.
If BIO_should_retry() returns false then the precise "error condition"
depends on the BIO type that caused it and the return code of the BIO
operation. For example if a call to BIO_read_ex() on a socket BIO returns
0 and BIO_should_retry() is false then the cause will be that the
connection closed. A similar condition on a file BIO will mean that it
has reached EOF. Some BIO types may place additional information on
the error queue. For more details see the individual BIO type manual
pages.
If the underlying I/O structure is in a blocking mode almost all current
BIO types will not request a retry, because the underlying I/O
calls will not. If the application knows that the BIO type will never
signal a retry then it need not call BIO_should_retry() after a failed
BIO I/O call. This is typically done with file BIOs.
SSL BIOs are the only current exception to this rule: they can request a
retry even if the underlying I/O structure is blocking, if a handshake
occurs during a call to BIO_read(). An application can retry the failed
call immediately or avoid this situation by setting SSL_MODE_AUTO_RETRY
on the underlying SSL structure.
While an application may retry a failed non blocking call immediately
this is likely to be very inefficient because the call will fail
repeatedly until data can be processed or is available. An application
will normally wait until the necessary condition is satisfied. How
this is done depends on the underlying I/O structure.
For example if the cause is ultimately a socket and BIO_should_read()
is true then a call to select() may be made to wait until data is
available and then retry the BIO operation. By combining the retry
conditions of several non blocking BIOs in a single select() call
it is possible to service several BIOs in a single thread, though
the performance may be poor if SSL BIOs are present because long delays
can occur during the initial handshake process.
It is possible for a BIO to block indefinitely if the underlying I/O
structure cannot process or return any data. This depends on the behaviour of
the platforms I/O functions. This is often not desirable: one solution
is to use non blocking I/O and use a timeout on the select() (or
equivalent) call.
=head1 BUGS
The OpenSSL ASN1 functions cannot gracefully deal with non blocking I/O:
that is they cannot retry after a partial read or write. This is usually
worked around by only passing the relevant data to ASN1 functions when
the entire structure can be read or written.
=head1 RETURN VALUES
BIO_should_read(), BIO_should_write(), BIO_should_io_special(), and
BIO_should_retry() return either 1 or 0 based on the actual conditions
of the B<BIO>.
BIO_retry_type() returns a flag combination presenting the cause of a retry
condition or false if there is no retry condition.
BIO_get_retry_BIO() returns a valid B<BIO> structure.
BIO_get_retry_reason() returns the reason for a special condition.
=head1 SEE ALSO
L<bio>
=head1 HISTORY
The BIO_get_retry_reason() and BIO_set_retry_reason() functions were added in
OpenSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

126
doc/man3/BN_BLINDING_new.pod Normal file
View File

@@ -0,0 +1,126 @@
=pod
=head1 NAME
BN_BLINDING_new, BN_BLINDING_free, BN_BLINDING_update, BN_BLINDING_convert,
BN_BLINDING_invert, BN_BLINDING_convert_ex, BN_BLINDING_invert_ex,
BN_BLINDING_is_current_thread, BN_BLINDING_set_current_thread,
BN_BLINDING_lock, BN_BLINDING_unlock, BN_BLINDING_get_flags,
BN_BLINDING_set_flags, BN_BLINDING_create_param - blinding related BIGNUM functions
=head1 SYNOPSIS
#include <openssl/bn.h>
BN_BLINDING *BN_BLINDING_new(const BIGNUM *A, const BIGNUM *Ai,
BIGNUM *mod);
void BN_BLINDING_free(BN_BLINDING *b);
int BN_BLINDING_update(BN_BLINDING *b, BN_CTX *ctx);
int BN_BLINDING_convert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx);
int BN_BLINDING_invert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx);
int BN_BLINDING_convert_ex(BIGNUM *n, BIGNUM *r, BN_BLINDING *b,
BN_CTX *ctx);
int BN_BLINDING_invert_ex(BIGNUM *n, const BIGNUM *r, BN_BLINDING *b,
BN_CTX *ctx);
int BN_BLINDING_is_current_thread(BN_BLINDING *b);
void BN_BLINDING_set_current_thread(BN_BLINDING *b);
int BN_BLINDING_lock(BN_BLINDING *b);
int BN_BLINDING_unlock(BN_BLINDING *b);
unsigned long BN_BLINDING_get_flags(const BN_BLINDING *);
void BN_BLINDING_set_flags(BN_BLINDING *, unsigned long);
BN_BLINDING *BN_BLINDING_create_param(BN_BLINDING *b,
const BIGNUM *e, BIGNUM *m, BN_CTX *ctx,
int (*bn_mod_exp)(BIGNUM *r,
const BIGNUM *a,
const BIGNUM *p,
const BIGNUM *m,
BN_CTX *ctx,
BN_MONT_CTX *m_ctx),
BN_MONT_CTX *m_ctx);
=head1 DESCRIPTION
BN_BLINDING_new() allocates a new B<BN_BLINDING> structure and copies
the B<A> and B<Ai> values into the newly created B<BN_BLINDING> object.
BN_BLINDING_free() frees the B<BN_BLINDING> structure.
If B<b> is NULL, nothing is done.
BN_BLINDING_update() updates the B<BN_BLINDING> parameters by squaring
the B<A> and B<Ai> or, after specific number of uses and if the
necessary parameters are set, by re-creating the blinding parameters.
BN_BLINDING_convert_ex() multiplies B<n> with the blinding factor B<A>.
If B<r> is not NULL a copy the inverse blinding factor B<Ai> will be
returned in B<r> (this is useful if a B<RSA> object is shared among
several threads). BN_BLINDING_invert_ex() multiplies B<n> with the
inverse blinding factor B<Ai>. If B<r> is not NULL it will be used as
the inverse blinding.
BN_BLINDING_convert() and BN_BLINDING_invert() are wrapper
functions for BN_BLINDING_convert_ex() and BN_BLINDING_invert_ex()
with B<r> set to NULL.
BN_BLINDING_is_current_thread() returns whether the B<BN_BLINDING>
structure is owned by the current thread. This is to help users
provide proper locking if needed for multi-threaded use.
BN_BLINDING_set_current_thread() sets the current thread as the
owner of the B<BN_BLINDING> structure.
BN_BLINDING_lock() locks the B<BN_BLINDING> structure.
BN_BLINDING_unlock() unlocks the B<BN_BLINDING> structure.
BN_BLINDING_get_flags() returns the BN_BLINDING flags. Currently
there are two supported flags: B<BN_BLINDING_NO_UPDATE> and
B<BN_BLINDING_NO_RECREATE>. B<BN_BLINDING_NO_UPDATE> inhibits the
automatic update of the B<BN_BLINDING> parameters after each use
and B<BN_BLINDING_NO_RECREATE> inhibits the automatic re-creation
of the B<BN_BLINDING> parameters after a fixed number of uses (currently
32). In newly allocated B<BN_BLINDING> objects no flags are set.
BN_BLINDING_set_flags() sets the B<BN_BLINDING> parameters flags.
BN_BLINDING_create_param() creates new B<BN_BLINDING> parameters
using the exponent B<e> and the modulus B<m>. B<bn_mod_exp> and
B<m_ctx> can be used to pass special functions for exponentiation
(normally BN_mod_exp_mont() and B<BN_MONT_CTX>).
=head1 RETURN VALUES
BN_BLINDING_new() returns the newly allocated B<BN_BLINDING> structure
or NULL in case of an error.
BN_BLINDING_update(), BN_BLINDING_convert(), BN_BLINDING_invert(),
BN_BLINDING_convert_ex() and BN_BLINDING_invert_ex() return 1 on
success and 0 if an error occurred.
BN_BLINDING_is_current_thread() returns 1 if the current thread owns
the B<BN_BLINDING> object, 0 otherwise.
BN_BLINDING_set_current_thread() doesn't return anything.
BN_BLINDING_lock(), BN_BLINDING_unlock() return 1 if the operation
succeeded or 0 on error.
BN_BLINDING_get_flags() returns the currently set B<BN_BLINDING> flags
(a B<unsigned long> value).
BN_BLINDING_create_param() returns the newly created B<BN_BLINDING>
parameters or NULL on error.
=head1 HISTORY
BN_BLINDING_thread_id() was first introduced in OpenSSL 1.0.0, and it
deprecates BN_BLINDING_set_thread_id() and BN_BLINDING_get_thread_id().
=head1 COPYRIGHT
Copyright 2005-2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

79
doc/man3/BN_CTX_new.pod Normal file
View File

@@ -0,0 +1,79 @@
=pod
=head1 NAME
BN_CTX_new, BN_CTX_secure_new, BN_CTX_free - allocate and free BN_CTX structures
=head1 SYNOPSIS
#include <openssl/bn.h>
BN_CTX *BN_CTX_new(void);
BN_CTX *BN_CTX_secure_new(void);
void BN_CTX_free(BN_CTX *c);
=head1 DESCRIPTION
A B<BN_CTX> is a structure that holds B<BIGNUM> temporary variables used by
library functions. Since dynamic memory allocation to create B<BIGNUM>s
is rather expensive when used in conjunction with repeated subroutine
calls, the B<BN_CTX> structure is used.
BN_CTX_new() allocates and initializes a B<BN_CTX> structure.
BN_CTX_secure_new() allocates and initializes a B<BN_CTX> structure
but uses the secure heap (see L<CRYPTO_secure_malloc(3)>) to hold the
B<BIGNUM>s.
BN_CTX_free() frees the components of the B<BN_CTX> and the structure itself.
Since BN_CTX_start() is required in order to obtain B<BIGNUM>s from the
B<BN_CTX>, in most cases BN_CTX_end() must be called before the B<BN_CTX> may
be freed by BN_CTX_free(). If B<c> is NULL, nothing is done.
A given B<BN_CTX> must only be used by a single thread of execution. No
locking is performed, and the internal pool allocator will not properly handle
multiple threads of execution.
=head1 RETURN VALUES
BN_CTX_new() and BN_CTX_secure_new() return a pointer to the B<BN_CTX>.
If the allocation fails,
they return B<NULL> and sets an error code that can be obtained by
L<ERR_get_error(3)>.
BN_CTX_free() has no return values.
=head1 REMOVED FUNCTIONALITY
void BN_CTX_init(BN_CTX *c);
BN_CTX_init() is no longer available as of OpenSSL 1.1.0. Applications should
replace use of BN_CTX_init with BN_CTX_new instead:
BN_CTX *ctx;
ctx = BN_CTX_new();
if (!ctx)
/* error */
...
BN_CTX_free(ctx);
=head1 SEE ALSO
L<ERR_get_error(3)>, L<BN_add(3)>,
L<BN_CTX_start(3)>
=head1 HISTORY
BN_CTX_init() was removed in OpenSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

57
doc/man3/BN_CTX_start.pod Normal file
View File

@@ -0,0 +1,57 @@
=pod
=head1 NAME
BN_CTX_start, BN_CTX_get, BN_CTX_end - use temporary BIGNUM variables
=head1 SYNOPSIS
#include <openssl/bn.h>
void BN_CTX_start(BN_CTX *ctx);
BIGNUM *BN_CTX_get(BN_CTX *ctx);
void BN_CTX_end(BN_CTX *ctx);
=head1 DESCRIPTION
These functions are used to obtain temporary B<BIGNUM> variables from
a B<BN_CTX> (which can been created by using L<BN_CTX_new(3)>)
in order to save the overhead of repeatedly creating and
freeing B<BIGNUM>s in functions that are called from inside a loop.
A function must call BN_CTX_start() first. Then, BN_CTX_get() may be
called repeatedly to obtain temporary B<BIGNUM>s. All BN_CTX_get()
calls must be made before calling any other functions that use the
B<ctx> as an argument.
Finally, BN_CTX_end() must be called before returning from the function.
When BN_CTX_end() is called, the B<BIGNUM> pointers obtained from
BN_CTX_get() become invalid.
=head1 RETURN VALUES
BN_CTX_start() and BN_CTX_end() return no values.
BN_CTX_get() returns a pointer to the B<BIGNUM>, or B<NULL> on error.
Once BN_CTX_get() has failed, the subsequent calls will return B<NULL>
as well, so it is sufficient to check the return value of the last
BN_CTX_get() call. In case of an error, an error code is set, which
can be obtained by L<ERR_get_error(3)>.
=head1 SEE ALSO
L<BN_CTX_new(3)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

129
doc/man3/BN_add.pod Normal file
View File

@@ -0,0 +1,129 @@
=pod
=head1 NAME
BN_add, BN_sub, BN_mul, BN_sqr, BN_div, BN_mod, BN_nnmod, BN_mod_add,
BN_mod_sub, BN_mod_mul, BN_mod_sqr, BN_exp, BN_mod_exp, BN_gcd -
arithmetic operations on BIGNUMs
=head1 SYNOPSIS
#include <openssl/bn.h>
int BN_add(BIGNUM *r, const BIGNUM *a, const BIGNUM *b);
int BN_sub(BIGNUM *r, const BIGNUM *a, const BIGNUM *b);
int BN_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx);
int BN_sqr(BIGNUM *r, BIGNUM *a, BN_CTX *ctx);
int BN_div(BIGNUM *dv, BIGNUM *rem, const BIGNUM *a, const BIGNUM *d,
BN_CTX *ctx);
int BN_mod(BIGNUM *rem, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx);
int BN_nnmod(BIGNUM *r, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx);
int BN_mod_add(BIGNUM *r, BIGNUM *a, BIGNUM *b, const BIGNUM *m,
BN_CTX *ctx);
int BN_mod_sub(BIGNUM *r, BIGNUM *a, BIGNUM *b, const BIGNUM *m,
BN_CTX *ctx);
int BN_mod_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b, const BIGNUM *m,
BN_CTX *ctx);
int BN_mod_sqr(BIGNUM *r, BIGNUM *a, const BIGNUM *m, BN_CTX *ctx);
int BN_exp(BIGNUM *r, BIGNUM *a, BIGNUM *p, BN_CTX *ctx);
int BN_mod_exp(BIGNUM *r, BIGNUM *a, const BIGNUM *p,
const BIGNUM *m, BN_CTX *ctx);
int BN_gcd(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx);
=head1 DESCRIPTION
BN_add() adds I<a> and I<b> and places the result in I<r> (C<r=a+b>).
I<r> may be the same B<BIGNUM> as I<a> or I<b>.
BN_sub() subtracts I<b> from I<a> and places the result in I<r> (C<r=a-b>).
I<r> may be the same B<BIGNUM> as I<a> or I<b>.
BN_mul() multiplies I<a> and I<b> and places the result in I<r> (C<r=a*b>).
I<r> may be the same B<BIGNUM> as I<a> or I<b>.
For multiplication by powers of 2, use L<BN_lshift(3)>.
BN_sqr() takes the square of I<a> and places the result in I<r>
(C<r=a^2>). I<r> and I<a> may be the same B<BIGNUM>.
This function is faster than BN_mul(r,a,a).
BN_div() divides I<a> by I<d> and places the result in I<dv> and the
remainder in I<rem> (C<dv=a/d, rem=a%d>). Either of I<dv> and I<rem> may
be B<NULL>, in which case the respective value is not returned.
The result is rounded towards zero; thus if I<a> is negative, the
remainder will be zero or negative.
For division by powers of 2, use BN_rshift(3).
BN_mod() corresponds to BN_div() with I<dv> set to B<NULL>.
BN_nnmod() reduces I<a> modulo I<m> and places the non-negative
remainder in I<r>.
BN_mod_add() adds I<a> to I<b> modulo I<m> and places the non-negative
result in I<r>.
BN_mod_sub() subtracts I<b> from I<a> modulo I<m> and places the
non-negative result in I<r>.
BN_mod_mul() multiplies I<a> by I<b> and finds the non-negative
remainder respective to modulus I<m> (C<r=(a*b) mod m>). I<r> may be
the same B<BIGNUM> as I<a> or I<b>. For more efficient algorithms for
repeated computations using the same modulus, see
L<BN_mod_mul_montgomery(3)> and
L<BN_mod_mul_reciprocal(3)>.
BN_mod_sqr() takes the square of I<a> modulo B<m> and places the
result in I<r>.
BN_exp() raises I<a> to the I<p>-th power and places the result in I<r>
(C<r=a^p>). This function is faster than repeated applications of
BN_mul().
BN_mod_exp() computes I<a> to the I<p>-th power modulo I<m> (C<r=a^p %
m>). This function uses less time and space than BN_exp(). Do not call this
function when B<m> is even and any of the parameters have the
B<BN_FLG_CONSTTIME> flag set.
BN_gcd() computes the greatest common divisor of I<a> and I<b> and
places the result in I<r>. I<r> may be the same B<BIGNUM> as I<a> or
I<b>.
For all functions, I<ctx> is a previously allocated B<BN_CTX> used for
temporary variables; see L<BN_CTX_new(3)>.
Unless noted otherwise, the result B<BIGNUM> must be different from
the arguments.
=head1 RETURN VALUES
For all functions, 1 is returned for success, 0 on error. The return
value should always be checked (e.g., C<if (!BN_add(r,a,b)) goto err;>).
The error codes can be obtained by L<ERR_get_error(3)>.
=head1 SEE ALSO
L<ERR_get_error(3)>, L<BN_CTX_new(3)>,
L<BN_add_word(3)>, L<BN_set_bit(3)>
=head1 COPYRIGHT
Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

61
doc/man3/BN_add_word.pod Normal file
View File

@@ -0,0 +1,61 @@
=pod
=head1 NAME
BN_add_word, BN_sub_word, BN_mul_word, BN_div_word, BN_mod_word - arithmetic
functions on BIGNUMs with integers
=head1 SYNOPSIS
#include <openssl/bn.h>
int BN_add_word(BIGNUM *a, BN_ULONG w);
int BN_sub_word(BIGNUM *a, BN_ULONG w);
int BN_mul_word(BIGNUM *a, BN_ULONG w);
BN_ULONG BN_div_word(BIGNUM *a, BN_ULONG w);
BN_ULONG BN_mod_word(const BIGNUM *a, BN_ULONG w);
=head1 DESCRIPTION
These functions perform arithmetic operations on BIGNUMs with unsigned
integers. They are much more efficient than the normal BIGNUM
arithmetic operations.
BN_add_word() adds B<w> to B<a> (C<a+=w>).
BN_sub_word() subtracts B<w> from B<a> (C<a-=w>).
BN_mul_word() multiplies B<a> and B<w> (C<a*=w>).
BN_div_word() divides B<a> by B<w> (C<a/=w>) and returns the remainder.
BN_mod_word() returns the remainder of B<a> divided by B<w> (C<a%w>).
For BN_div_word() and BN_mod_word(), B<w> must not be 0.
=head1 RETURN VALUES
BN_add_word(), BN_sub_word() and BN_mul_word() return 1 for success, 0
on error. The error codes can be obtained by L<ERR_get_error(3)>.
BN_mod_word() and BN_div_word() return B<a>%B<w> on success and
B<(BN_ULONG)-1> if an error occurred.
=head1 SEE ALSO
L<ERR_get_error(3)>, L<BN_add(3)>
=head1 COPYRIGHT
Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

116
doc/man3/BN_bn2bin.pod Normal file
View File

@@ -0,0 +1,116 @@
=pod
=head1 NAME
BN_bn2binpad,
BN_bn2bin, BN_bin2bn, BN_bn2lebinpad, BN_lebin2bn, BN_bn2hex, BN_bn2dec,
BN_hex2bn, BN_dec2bn, BN_print, BN_print_fp, BN_bn2mpi,
BN_mpi2bn - format conversions
=head1 SYNOPSIS
#include <openssl/bn.h>
int BN_bn2bin(const BIGNUM *a, unsigned char *to);
int BN_bn2binpad(const BIGNUM *a, unsigned char *to, int tolen);
BIGNUM *BN_bin2bn(const unsigned char *s, int len, BIGNUM *ret);
int BN_bn2lebinpad(const BIGNUM *a, unsigned char *to, int tolen);
BIGNUM *BN_lebin2bn(const unsigned char *s, int len, BIGNUM *ret);
char *BN_bn2hex(const BIGNUM *a);
char *BN_bn2dec(const BIGNUM *a);
int BN_hex2bn(BIGNUM **a, const char *str);
int BN_dec2bn(BIGNUM **a, const char *str);
int BN_print(BIO *fp, const BIGNUM *a);
int BN_print_fp(FILE *fp, const BIGNUM *a);
int BN_bn2mpi(const BIGNUM *a, unsigned char *to);
BIGNUM *BN_mpi2bn(unsigned char *s, int len, BIGNUM *ret);
=head1 DESCRIPTION
BN_bn2bin() converts the absolute value of B<a> into big-endian form
and stores it at B<to>. B<to> must point to BN_num_bytes(B<a>) bytes of
memory.
BN_bn2binpad() also converts the absolute value of B<a> into big-endian form
and stores it at B<to>. B<tolen> indicates the length of the output buffer
B<to>. The result is padded with zeroes if necessary. If B<tolen> is less than
BN_num_bytes(B<a>) an error is returned.
BN_bin2bn() converts the positive integer in big-endian form of length
B<len> at B<s> into a B<BIGNUM> and places it in B<ret>. If B<ret> is
NULL, a new B<BIGNUM> is created.
BN_bn2lebinpad() and BN_lebin2bn() are identical to BN_bn2binpad() and
BN_bin2bn() except the buffer is in little-endian format.
BN_bn2hex() and BN_bn2dec() return printable strings containing the
hexadecimal and decimal encoding of B<a> respectively. For negative
numbers, the string is prefaced with a leading '-'. The string must be
freed later using OPENSSL_free().
BN_hex2bn() takes as many characters as possible from the string B<str>,
including the leading character '-' which means negative, to form a valid
hexadecimal number representation and converts them to a B<BIGNUM> and
stores it in **B<a>. If *B<a> is NULL, a new B<BIGNUM> is created. If
B<a> is NULL, it only computes the length of valid representation.
A "negative zero" is converted to zero.
BN_dec2bn() is the same using the decimal system.
BN_print() and BN_print_fp() write the hexadecimal encoding of B<a>,
with a leading '-' for negative numbers, to the B<BIO> or B<FILE>
B<fp>.
BN_bn2mpi() and BN_mpi2bn() convert B<BIGNUM>s from and to a format
that consists of the number's length in bytes represented as a 4-byte
big-endian number, and the number itself in big-endian format, where
the most significant bit signals a negative number (the representation
of numbers with the MSB set is prefixed with null byte).
BN_bn2mpi() stores the representation of B<a> at B<to>, where B<to>
must be large enough to hold the result. The size can be determined by
calling BN_bn2mpi(B<a>, NULL).
BN_mpi2bn() converts the B<len> bytes long representation at B<s> to
a B<BIGNUM> and stores it at B<ret>, or in a newly allocated B<BIGNUM>
if B<ret> is NULL.
=head1 RETURN VALUES
BN_bn2bin() returns the length of the big-endian number placed at B<to>.
BN_bin2bn() returns the B<BIGNUM>, NULL on error.
BN_bn2binpad() returns the number of bytes written or -1 if the supplied
buffer is too small.
BN_bn2hex() and BN_bn2dec() return a null-terminated string, or NULL
on error. BN_hex2bn() and BN_dec2bn() return the number of characters
used in parsing, or 0 on error, in which
case no new B<BIGNUM> will be created.
BN_print_fp() and BN_print() return 1 on success, 0 on write errors.
BN_bn2mpi() returns the length of the representation. BN_mpi2bn()
returns the B<BIGNUM>, and NULL on error.
The error codes can be obtained by L<ERR_get_error(3)>.
=head1 SEE ALSO
L<ERR_get_error(3)>, L<BN_zero(3)>,
L<ASN1_INTEGER_to_BN(3)>,
L<BN_num_bytes(3)>
=head1 COPYRIGHT
Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

47
doc/man3/BN_cmp.pod Normal file
View File

@@ -0,0 +1,47 @@
=pod
=head1 NAME
BN_cmp, BN_ucmp, BN_is_zero, BN_is_one, BN_is_word, BN_is_odd - BIGNUM comparison and test functions
=head1 SYNOPSIS
#include <openssl/bn.h>
int BN_cmp(BIGNUM *a, BIGNUM *b);
int BN_ucmp(BIGNUM *a, BIGNUM *b);
int BN_is_zero(BIGNUM *a);
int BN_is_one(BIGNUM *a);
int BN_is_word(BIGNUM *a, BN_ULONG w);
int BN_is_odd(BIGNUM *a);
=head1 DESCRIPTION
BN_cmp() compares the numbers B<a> and B<b>. BN_ucmp() compares their
absolute values.
BN_is_zero(), BN_is_one() and BN_is_word() test if B<a> equals 0, 1,
or B<w> respectively. BN_is_odd() tests if a is odd.
BN_is_zero(), BN_is_one(), BN_is_word() and BN_is_odd() are macros.
=head1 RETURN VALUES
BN_cmp() returns -1 if B<a> E<lt> B<b>, 0 if B<a> == B<b> and 1 if
B<a> E<gt> B<b>. BN_ucmp() is the same using the absolute values
of B<a> and B<b>.
BN_is_zero(), BN_is_one() BN_is_word() and BN_is_odd() return 1 if
the condition is true, 0 otherwise.
=head1 COPYRIGHT
Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

69
doc/man3/BN_copy.pod Normal file
View File

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

212
doc/man3/BN_generate_prime.pod Normal file
View File

@@ -0,0 +1,212 @@
=pod
=head1 NAME
BN_generate_prime_ex, BN_is_prime_ex, 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
=head1 SYNOPSIS
#include <openssl/bn.h>
int BN_generate_prime_ex(BIGNUM *ret, int bits, int safe, const BIGNUM *add,
const BIGNUM *rem, BN_GENCB *cb);
int BN_is_prime_ex(const BIGNUM *p, int nchecks, BN_CTX *ctx, BN_GENCB *cb);
int BN_is_prime_fasttest_ex(const BIGNUM *p, int nchecks, BN_CTX *ctx,
int do_trial_division, BN_GENCB *cb);
int BN_GENCB_call(BN_GENCB *cb, int a, int b);
BN_GENCB *BN_GENCB_new(void);
void BN_GENCB_free(BN_GENCB *cb);
void BN_GENCB_set_old(BN_GENCB *gencb,
void (*callback)(int, int, void *), void *cb_arg);
void BN_GENCB_set(BN_GENCB *gencb,
int (*callback)(int, int, BN_GENCB *), void *cb_arg);
void *BN_GENCB_get_arg(BN_GENCB *cb);
Deprecated:
#if OPENSSL_API_COMPAT < 0x00908000L
BIGNUM *BN_generate_prime(BIGNUM *ret, int num, int safe, BIGNUM *add,
BIGNUM *rem, void (*callback)(int, int, void *),
void *cb_arg);
int BN_is_prime(const BIGNUM *a, int checks,
void (*callback)(int, int, void *), BN_CTX *ctx, void *cb_arg);
int BN_is_prime_fasttest(const BIGNUM *a, int checks,
void (*callback)(int, int, void *), BN_CTX *ctx,
void *cb_arg, int do_trial_division);
#endif
=head1 DESCRIPTION
BN_generate_prime_ex() generates a pseudo-random prime number of
at least bit length B<bits>.
If B<ret> is not B<NULL>, it will be used to store the number.
If B<cb> is not B<NULL>, it is used as follows:
=over 2
=item *
B<BN_GENCB_call(cb, 0, i)> is called after generating the i-th
potential prime number.
=item *
While the number is being tested for primality,
B<BN_GENCB_call(cb, 1, j)> is called as described below.
=item *
When a prime has been found, B<BN_GENCB_call(cb, 2, i)> is called.
=item *
The callers of BN_generate_prime_ex() may call B<BN_GENCB_call(cb, i, j)> with
other values as described in their respective man pages; see L</SEE ALSO>.
=back
The prime may have to fulfill additional requirements for use in
Diffie-Hellman key exchange:
If B<add> is not B<NULL>, the prime will fulfill the condition p % B<add>
== B<rem> (p % B<add> == 1 if B<rem> == B<NULL>) in order to suit a given
generator.
If B<safe> is true, it will be a safe prime (i.e. a prime p so
that (p-1)/2 is also prime).
The PRNG must be seeded prior to calling BN_generate_prime_ex().
The prime number generation has a negligible error probability.
BN_is_prime_ex() and BN_is_prime_fasttest_ex() test if the number B<p> is
prime. The following tests are performed until one of them shows that
B<p> is composite; if B<p> passes all these tests, it is considered
prime.
BN_is_prime_fasttest_ex(), when called with B<do_trial_division == 1>,
first attempts trial division by a number of small primes;
if no divisors are found by this test and B<cb> is not B<NULL>,
B<BN_GENCB_call(cb, 1, -1)> is called.
If B<do_trial_division == 0>, this test is skipped.
Both BN_is_prime_ex() and BN_is_prime_fasttest_ex() perform a Miller-Rabin
probabilistic primality test with B<nchecks> iterations. If
B<nchecks == BN_prime_checks>, a number of iterations is used that
yields a false positive rate of at most 2^-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.
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<cb> is not B<NULL>, B<BN_GENCB_call(cb, 1, j)> is called
after the j-th iteration (j = 0, 1, ...). B<ctx> is a
pre-allocated B<BN_CTX> (to save the overhead of allocating and
freeing the structure in a loop), or B<NULL>.
BN_GENCB_call() calls the callback function held in the B<BN_GENCB> structure
and passes the ints B<a> and B<b> as arguments. There are two types of
B<BN_GENCB> structure that are supported: "new" style and "old" style. New
programs should prefer the "new" style, whilst the "old" style is provided
for backwards compatibility purposes.
A B<BN_GENCB> structure should be created through a call to BN_GENCB_new(),
and freed through a call to BN_GENCB_free().
For "new" style callbacks a BN_GENCB structure should be initialised with a
call to BN_GENCB_set(), where B<gencb> is a B<BN_GENCB *>, B<callback> is of
type B<int (*callback)(int, int, BN_GENCB *)> and B<cb_arg> is a B<void *>.
"Old" style callbacks are the same except they are initialised with a call
to BN_GENCB_set_old() and B<callback> is of type
B<void (*callback)(int, int, void *)>.
A callback is invoked through a call to B<BN_GENCB_call>. This will check
the type of the callback and will invoke B<callback(a, b, gencb)> for new
style callbacks or B<callback(a, b, cb_arg)> for old style.
It is possible to obtain the argument associated with a BN_GENCB structure
(set via a call to BN_GENCB_set or BN_GENCB_set_old) using BN_GENCB_get_arg.
BN_generate_prime() (deprecated) works in the same way as
BN_generate_prime_ex() but expects an old-style callback function
directly in the B<callback> parameter, and an argument to pass to it in
the B<cb_arg>. BN_is_prime() and BN_is_prime_fasttest()
can similarly be compared to BN_is_prime_ex() and
BN_is_prime_fasttest_ex(), respectively.
=head1 RETURN VALUES
BN_generate_prime_ex() return 1 on success or 0 on error.
BN_is_prime_ex(), BN_is_prime_fasttest_ex(), BN_is_prime() and
BN_is_prime_fasttest() return 0 if the number is composite, 1 if it is
prime with an error probability of less than 0.25^B<nchecks>, and
-1 on error.
BN_generate_prime() returns the prime number on success, B<NULL> otherwise.
BN_GENCB_new returns a pointer to a BN_GENCB structure on success, or B<NULL>
otherwise.
BN_GENCB_get_arg returns the argument previously associated with a BN_GENCB
structure.
Callback functions should return 1 on success or 0 on error.
The error codes can be obtained by L<ERR_get_error(3)>.
=head1 REMOVED FUNCTIONALITY
As of OpenSSL 1.1.0 it is no longer possible to create a BN_GENCB structure
directly, as in:
BN_GENCB callback;
Instead applications should create a BN_GENCB structure using BN_GENCB_new:
BN_GENCB *callback;
callback = BN_GENCB_new();
if (!callback)
/* error */
...
BN_GENCB_free(callback);
=head1 SEE ALSO
L<DH_generate_parameters(3)>, L<DSA_generate_parameters(3)>,
L<RSA_generate_key(3)>, L<ERR_get_error(3)>, L<RAND_bytes(3)>
=head1 HISTORY
BN_GENCB_new(), BN_GENCB_free(),
and BN_GENCB_get_arg() were added in OpenSSL 1.1.0
=head1 COPYRIGHT
Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

41
doc/man3/BN_mod_inverse.pod Normal file
View File

@@ -0,0 +1,41 @@
=pod
=head1 NAME
BN_mod_inverse - compute inverse modulo n
=head1 SYNOPSIS
#include <openssl/bn.h>
BIGNUM *BN_mod_inverse(BIGNUM *r, BIGNUM *a, const BIGNUM *n,
BN_CTX *ctx);
=head1 DESCRIPTION
BN_mod_inverse() computes the inverse of B<a> modulo B<n>
places the result in B<r> (C<(a*r)%n==1>). If B<r> is NULL,
a new B<BIGNUM> is created.
B<ctx> is a previously allocated B<BN_CTX> used for temporary
variables. B<r> may be the same B<BIGNUM> as B<a> or B<n>.
=head1 RETURN VALUES
BN_mod_inverse() returns the B<BIGNUM> containing the inverse, and
NULL on error. The error codes can be obtained by L<ERR_get_error(3)>.
=head1 SEE ALSO
L<ERR_get_error(3)>, L<BN_add(3)>
=head1 COPYRIGHT
Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

90
doc/man3/BN_mod_mul_montgomery.pod Normal file
View File

@@ -0,0 +1,90 @@
=pod
=head1 NAME
BN_mod_mul_montgomery, BN_MONT_CTX_new,
BN_MONT_CTX_free, BN_MONT_CTX_set, BN_MONT_CTX_copy,
BN_from_montgomery, BN_to_montgomery - Montgomery multiplication
=head1 SYNOPSIS
#include <openssl/bn.h>
BN_MONT_CTX *BN_MONT_CTX_new(void);
void BN_MONT_CTX_free(BN_MONT_CTX *mont);
int BN_MONT_CTX_set(BN_MONT_CTX *mont, const BIGNUM *m, BN_CTX *ctx);
BN_MONT_CTX *BN_MONT_CTX_copy(BN_MONT_CTX *to, BN_MONT_CTX *from);
int BN_mod_mul_montgomery(BIGNUM *r, BIGNUM *a, BIGNUM *b,
BN_MONT_CTX *mont, BN_CTX *ctx);
int BN_from_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont,
BN_CTX *ctx);
int BN_to_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont,
BN_CTX *ctx);
=head1 DESCRIPTION
These functions implement Montgomery multiplication. They are used
automatically when L<BN_mod_exp(3)> is called with suitable input,
but they may be useful when several operations are to be performed
using the same modulus.
BN_MONT_CTX_new() allocates and initializes a B<BN_MONT_CTX> structure.
BN_MONT_CTX_set() sets up the I<mont> structure from the modulus I<m>
by precomputing its inverse and a value R.
BN_MONT_CTX_copy() copies the B<BN_MONT_CTX> I<from> to I<to>.
BN_MONT_CTX_free() frees the components of the B<BN_MONT_CTX>, and, if
it was created by BN_MONT_CTX_new(), also the structure itself.
If B<mont> is NULL, nothing is done.
BN_mod_mul_montgomery() computes Mont(I<a>,I<b>):=I<a>*I<b>*R^-1 and places
the result in I<r>.
BN_from_montgomery() performs the Montgomery reduction I<r> = I<a>*R^-1.
BN_to_montgomery() computes Mont(I<a>,R^2), i.e. I<a>*R.
Note that I<a> must be non-negative and smaller than the modulus.
For all functions, I<ctx> is a previously allocated B<BN_CTX> used for
temporary variables.
=head1 RETURN VALUES
BN_MONT_CTX_new() returns the newly allocated B<BN_MONT_CTX>, and NULL
on error.
BN_MONT_CTX_free() has no return value.
For the other functions, 1 is returned for success, 0 on error.
The error codes can be obtained by L<ERR_get_error(3)>.
=head1 WARNING
The inputs must be reduced modulo B<m>, otherwise the result will be
outside the expected range.
=head1 SEE ALSO
L<ERR_get_error(3)>, L<BN_add(3)>,
L<BN_CTX_new(3)>
=head1 HISTORY
BN_MONT_CTX_init() was removed in OpenSSL 1.1.0
=head1 COPYRIGHT
Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

76
doc/man3/BN_mod_mul_reciprocal.pod Normal file
View File

@@ -0,0 +1,76 @@
=pod
=head1 NAME
BN_mod_mul_reciprocal, BN_div_recp, BN_RECP_CTX_new,
BN_RECP_CTX_free, BN_RECP_CTX_set - modular multiplication using
reciprocal
=head1 SYNOPSIS
#include <openssl/bn.h>
BN_RECP_CTX *BN_RECP_CTX_new(void);
void BN_RECP_CTX_free(BN_RECP_CTX *recp);
int BN_RECP_CTX_set(BN_RECP_CTX *recp, const BIGNUM *m, BN_CTX *ctx);
int BN_div_recp(BIGNUM *dv, BIGNUM *rem, BIGNUM *a, BN_RECP_CTX *recp,
BN_CTX *ctx);
int BN_mod_mul_reciprocal(BIGNUM *r, BIGNUM *a, BIGNUM *b,
BN_RECP_CTX *recp, BN_CTX *ctx);
=head1 DESCRIPTION
BN_mod_mul_reciprocal() can be used to perform an efficient
L<BN_mod_mul(3)> operation when the operation will be performed
repeatedly with the same modulus. It computes B<r>=(B<a>*B<b>)%B<m>
using B<recp>=1/B<m>, which is set as described below. B<ctx> is a
previously allocated B<BN_CTX> used for temporary variables.
BN_RECP_CTX_new() allocates and initializes a B<BN_RECP> structure.
BN_RECP_CTX_free() frees the components of the B<BN_RECP>, and, if it
was created by BN_RECP_CTX_new(), also the structure itself.
If B<recp> is NULL, nothing is done.
BN_RECP_CTX_set() stores B<m> in B<recp> and sets it up for computing
1/B<m> and shifting it left by BN_num_bits(B<m>)+1 to make it an
integer. The result and the number of bits it was shifted left will
later be stored in B<recp>.
BN_div_recp() divides B<a> by B<m> using B<recp>. It places the quotient
in B<dv> and the remainder in B<rem>.
The B<BN_RECP_CTX> structure cannot be shared between threads.
=head1 RETURN VALUES
BN_RECP_CTX_new() returns the newly allocated B<BN_RECP_CTX>, and NULL
on error.
BN_RECP_CTX_free() has no return value.
For the other functions, 1 is returned for success, 0 on error.
The error codes can be obtained by L<ERR_get_error(3)>.
=head1 SEE ALSO
L<ERR_get_error(3)>, L<BN_add(3)>,
L<BN_CTX_new(3)>
=head1 HISTORY
BN_RECP_CTX_init() was removed in OpenSSL 1.1.0
=head1 COPYRIGHT
Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

63
doc/man3/BN_new.pod Normal file
View File

@@ -0,0 +1,63 @@
=pod
=head1 NAME
BN_new, BN_secure_new, BN_clear, BN_free, BN_clear_free - allocate and free BIGNUMs
=head1 SYNOPSIS
#include <openssl/bn.h>
BIGNUM *BN_new(void);
BIGNUM *BN_secure_new(void);
void BN_clear(BIGNUM *a);
void BN_free(BIGNUM *a);
void BN_clear_free(BIGNUM *a);
=head1 DESCRIPTION
BN_new() allocates and initializes a B<BIGNUM> structure.
BN_secure_new() does the same except that the secure heap
OPENSSL_secure_malloc(3) is used to store the value.
BN_clear() is used to destroy sensitive data such as keys when they
are no longer needed. It erases the memory used by B<a> and sets it
to the value 0.
BN_free() frees the components of the B<BIGNUM>, and if it was created
by BN_new(), also the structure itself. BN_clear_free() additionally
overwrites the data before the memory is returned to the system.
If B<a> is NULL, nothing is done.
=head1 RETURN VALUES
BN_new() and BN_secure_new()
return a pointer to the B<BIGNUM> initialised to the value 0.
If the allocation fails,
they return B<NULL> and set an error code that can be obtained
by L<ERR_get_error(3)>.
BN_clear(), BN_free() and BN_clear_free() have no return values.
=head1 SEE ALSO
L<ERR_get_error(3)>
=head1 HISTORY
BN_init() was removed in OpenSSL 1.1.0; use BN_new() instead.
=head1 COPYRIGHT
Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

61
doc/man3/BN_num_bytes.pod Normal file
View File

@@ -0,0 +1,61 @@
=pod
=head1 NAME
BN_num_bits, BN_num_bytes, BN_num_bits_word - get BIGNUM size
=head1 SYNOPSIS
#include <openssl/bn.h>
int BN_num_bytes(const BIGNUM *a);
int BN_num_bits(const BIGNUM *a);
int BN_num_bits_word(BN_ULONG w);
=head1 DESCRIPTION
BN_num_bytes() returns the size of a B<BIGNUM> in bytes.
BN_num_bits_word() returns the number of significant bits in a word.
If we take 0x00000432 as an example, it returns 11, not 16, not 32.
Basically, except for a zero, it returns I<floor(log2(w))+1>.
BN_num_bits() returns the number of significant bits in a B<BIGNUM>,
following the same principle as BN_num_bits_word().
BN_num_bytes() is a macro.
=head1 RETURN VALUES
The size.
=head1 NOTES
Some have tried using BN_num_bits() on individual numbers in RSA keys,
DH keys and DSA keys, and found that they don't always come up with
the number of bits they expected (something like 512, 1024, 2048,
...). This is because generating a number with some specific number
of bits doesn't always set the highest bits, thereby making the number
of I<significant> bits a little lower. If you want to know the "key
size" of such a key, either use functions like RSA_size(), DH_size()
and DSA_size(), or use BN_num_bytes() and multiply with 8 (although
there's no real guarantee that will match the "key size", just a lot
more probability).
=head1 SEE ALSO
L<DH_size(3)>, L<DSA_size(3)>,
L<RSA_size(3)>
=head1 COPYRIGHT
Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

98
doc/man3/BN_rand.pod Normal file
View File

@@ -0,0 +1,98 @@
=pod
=head1 NAME
BN_rand, BN_priv_rand, BN_pseudo_rand,
BN_rand_range, BN_priv_rand_range, BN_pseudo_rand_range
- generate pseudo-random number
=head1 SYNOPSIS
#include <openssl/bn.h>
int BN_rand(BIGNUM *rnd, int bits, int top, int bottom);
int BN_priv_rand(BIGNUM *rnd, int bits, int top, int bottom);
int BN_pseudo_rand(BIGNUM *rnd, int bits, int top, int bottom);
int BN_rand_range(BIGNUM *rnd, BIGNUM *range);
int BN_priv_rand_range(BIGNUM *rnd, BIGNUM *range);
int BN_pseudo_rand_range(BIGNUM *rnd, BIGNUM *range);
=head1 DESCRIPTION
BN_rand() generates a cryptographically strong pseudo-random number of
B<bits> in length and stores it in B<rnd>.
If B<bits> is less than zero, or too small to
accommodate the requirements specified by the B<top> and B<bottom>
parameters, an error is returned.
The B<top> parameters specifies
requirements on the most significant bit of the generated number.
If it is B<BN_RAND_TOP_ANY>, there is no constraint.
If it is B<BN_RAND_TOP_ONE>, the top bit must be one.
If it is B<BN_RAND_TOP_TWO>, the two most significant bits of
the number will be set to 1, so that the product of two such random
numbers will always have 2*B<bits> length.
If B<bottom> is B<BN_RAND_BOTTOM_ODD>, the number will be odd; if it
is B<BN_RAND_BOTTOM_ANY> it can be odd or even.
If B<bits> is 1 then B<top> cannot also be B<BN_RAND_FLG_TOPTWO>.
BN_rand_range() generates a cryptographically strong pseudo-random
number B<rnd> in the range 0 E<lt>= B<rnd> E<lt> B<range>.
BN_priv_rand() and BN_priv_rand_range() have the same semantics as
BN_rand() and BN_rand_range() respectively. They are intended to be
used for generating values that should remain private, and mirror the
same difference between L<RAND_bytes(3)> and L<RAND_priv_bytes(3)>.
=head1 NOTES
Always check the error return value of these functions and do not take
randomness for granted: an error occurs if the CSPRNG has not been
seeded with enough randomness to ensure an unpredictable byte sequence.
=head1 RETURN VALUES
The functions return 1 on success, 0 on error.
The error codes can be obtained by L<ERR_get_error(3)>.
=head1 HISTORY
=over 2
=item *
Starting with OpenSSL release 1.1.0, BN_pseudo_rand() has been identical
to BN_rand() and BN_pseudo_rand_range() has been identical to
BN_rand_range().
The "pseudo" functions should not be used and may be deprecated in
a future release.
=item *
BN_priv_rand() and BN_priv_rand_range() were added in OpenSSL 1.1.1.
=back
=head1 SEE ALSO
L<ERR_get_error(3)>,
L<RAND_add(3)>,
L<RAND_bytes(3)>,
L<RAND_priv_bytes(3)>,
L<RAND(7)>,
L<RAND_DRBG(7)>
=head1 COPYRIGHT
Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

51
doc/man3/BN_security_bits.pod Normal file
View File

@@ -0,0 +1,51 @@
=pod
=head1 NAME
BN_security_bits - returns bits of security based on given numbers
=head1 SYNOPSIS
#include <openssl/bn.h>
int BN_security_bits(int L, int N);
=head1 DESCRIPTION
BN_security_bits() returns the number of bits of security provided by a
specific algorithm and a particular key size. The bits of security is
defined in NIST SP800-57. Currently, BN_security_bits() support two types
of asymmetric algorithms: the FFC (Finite Field Cryptography) and IFC
(Integer Factorization Cryptography). For FFC, e.g., DSA and DH, both
parameters B<L> and B<N> are used to decide the bits of security, where
B<L> is the size of the public key and B<N> is the size of the private
key. For IFC, e.g., RSA, only B<L> is used and it's commonly considered
to be the key size (modulus).
=head1 RETURN VALUES
Number of security bits.
=head1 NOTES
ECC (Elliptic Curve Cryptography) is not covered by the BN_security_bits()
function. The symmetric algorithms are not covered neither.
=head1 HISTORY
BN_security_bits() was added in OpenSSL 1.1.0.
=head1 SEE ALSO
L<DH_security_bits(3)>, L<DSA_security_bits(3)>, L<RSA_security_bits(3)>
=head1 COPYRIGHT
Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

69
doc/man3/BN_set_bit.pod Normal file
View File

@@ -0,0 +1,69 @@
=pod
=head1 NAME
BN_set_bit, BN_clear_bit, BN_is_bit_set, BN_mask_bits, BN_lshift,
BN_lshift1, BN_rshift, BN_rshift1 - bit operations on BIGNUMs
=head1 SYNOPSIS
#include <openssl/bn.h>
int BN_set_bit(BIGNUM *a, int n);
int BN_clear_bit(BIGNUM *a, int n);
int BN_is_bit_set(const BIGNUM *a, int n);
int BN_mask_bits(BIGNUM *a, int n);
int BN_lshift(BIGNUM *r, const BIGNUM *a, int n);
int BN_lshift1(BIGNUM *r, BIGNUM *a);
int BN_rshift(BIGNUM *r, BIGNUM *a, int n);
int BN_rshift1(BIGNUM *r, BIGNUM *a);
=head1 DESCRIPTION
BN_set_bit() sets bit B<n> in B<a> to 1 (C<a|=(1E<lt>E<lt>n)>). The
number is expanded if necessary.
BN_clear_bit() sets bit B<n> in B<a> to 0 (C<a&=~(1E<lt>E<lt>n)>). An
error occurs if B<a> is shorter than B<n> bits.
BN_is_bit_set() tests if bit B<n> in B<a> is set.
BN_mask_bits() truncates B<a> to an B<n> bit number
(C<a&=~((~0)E<gt>E<gt>n)>). An error occurs if B<a> already is
shorter than B<n> bits.
BN_lshift() shifts B<a> left by B<n> bits and places the result in
B<r> (C<r=a*2^n>). Note that B<n> must be non-negative. BN_lshift1() shifts
B<a> left by one and places the result in B<r> (C<r=2*a>).
BN_rshift() shifts B<a> right by B<n> bits and places the result in
B<r> (C<r=a/2^n>). Note that B<n> must be non-negative. BN_rshift1() shifts
B<a> right by one and places the result in B<r> (C<r=a/2>).
For the shift functions, B<r> and B<a> may be the same variable.
=head1 RETURN VALUES
BN_is_bit_set() returns 1 if the bit is set, 0 otherwise.
All other functions return 1 for success, 0 on error. The error codes
can be obtained by L<ERR_get_error(3)>.
=head1 SEE ALSO
L<BN_num_bytes(3)>, L<BN_add(3)>
=head1 COPYRIGHT
Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

30
doc/man3/BN_swap.pod Normal file
View File

@@ -0,0 +1,30 @@
=pod
=head1 NAME
BN_swap - exchange BIGNUMs
=head1 SYNOPSIS
#include <openssl/bn.h>
void BN_swap(BIGNUM *a, BIGNUM *b);
=head1 DESCRIPTION
BN_swap() exchanges the values of I<a> and I<b>.
=head1 RETURN VALUES
BN_swap() does not return a value.
=head1 COPYRIGHT
Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

68
doc/man3/BN_zero.pod Normal file
View File

@@ -0,0 +1,68 @@
=pod
=head1 NAME
BN_zero, BN_one, BN_value_one, BN_set_word, BN_get_word - BIGNUM assignment
operations
=head1 SYNOPSIS
#include <openssl/bn.h>
void BN_zero(BIGNUM *a);
int BN_one(BIGNUM *a);
const BIGNUM *BN_value_one(void);
int BN_set_word(BIGNUM *a, BN_ULONG w);
unsigned BN_ULONG BN_get_word(BIGNUM *a);
=head1 DESCRIPTION
B<BN_ULONG> is a macro that will be an unsigned integral type optimized
for the most efficient implementation on the local platform.
BN_zero(), BN_one() and BN_set_word() set B<a> to the values 0, 1 and
B<w> respectively. BN_zero() and BN_one() are macros.
BN_value_one() returns a B<BIGNUM> constant of value 1. This constant
is useful for use in comparisons and assignment.
BN_get_word() returns B<a>, if it can be represented as a B<BN_ULONG>.
=head1 RETURN VALUES
BN_get_word() returns the value B<a>, or all-bits-set if B<a> cannot
be represented as a single integer.
BN_one() and BN_set_word() return 1 on success, 0 otherwise.
BN_value_one() returns the constant.
BN_zero() never fails and returns no value.
=head1 BUGS
If a B<BIGNUM> is equal to the value of all-bits-set, it will collide
with the error condition returned by BN_get_word() which uses that
as an error value.
B<BN_ULONG> should probably be a typedef.
=head1 SEE ALSO
L<BN_bn2bin(3)>
=head1 HISTORY
In OpenSSL 0.9.8, BN_zero() was changed to not return a value; previous
versions returned an int.
=head1 COPYRIGHT
Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

75
doc/man3/BUF_MEM_new.pod Normal file
View File

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

70
doc/man3/CMS_add0_cert.pod Normal file
View File

@@ -0,0 +1,70 @@
=pod
=head1 NAME
CMS_add0_cert, CMS_add1_cert, CMS_get1_certs, CMS_add0_crl, CMS_add1_crl, CMS_get1_crls
- CMS certificate and CRL utility functions
=head1 SYNOPSIS
#include <openssl/cms.h>
int CMS_add0_cert(CMS_ContentInfo *cms, X509 *cert);
int CMS_add1_cert(CMS_ContentInfo *cms, X509 *cert);
STACK_OF(X509) *CMS_get1_certs(CMS_ContentInfo *cms);
int CMS_add0_crl(CMS_ContentInfo *cms, X509_CRL *crl);
int CMS_add1_crl(CMS_ContentInfo *cms, X509_CRL *crl);
STACK_OF(X509_CRL) *CMS_get1_crls(CMS_ContentInfo *cms);
=head1 DESCRIPTION
CMS_add0_cert() and CMS_add1_cert() add certificate B<cert> to B<cms>.
must be of type signed data or enveloped data.
CMS_get1_certs() returns all certificates in B<cms>.
CMS_add0_crl() and CMS_add1_crl() add CRL B<crl> to B<cms>. CMS_get1_crls()
returns any CRLs in B<cms>.
=head1 NOTES
The CMS_ContentInfo structure B<cms> must be of type signed data or enveloped
data or an error will be returned.
For signed data certificates and CRLs are added to the B<certificates> and
B<crls> fields of SignedData structure. For enveloped data they are added to
B<OriginatorInfo>.
As the B<0> implies CMS_add0_cert() adds B<cert> internally to B<cms> and it
must not be freed up after the call as opposed to CMS_add1_cert() where B<cert>
must be freed up.
The same certificate or CRL must not be added to the same cms structure more
than once.
=head1 RETURN VALUES
CMS_add0_cert(), CMS_add1_cert() and CMS_add0_crl() and CMS_add1_crl() return
1 for success and 0 for failure.
CMS_get1_certs() and CMS_get1_crls() return the STACK of certificates or CRLs
or NULL if there are none or an error occurs. The only error which will occur
in practice is if the B<cms> type is invalid.
=head1 SEE ALSO
L<ERR_get_error(3)>,
L<CMS_sign(3)>,
L<CMS_encrypt(3)>
=head1 COPYRIGHT
Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

72
doc/man3/CMS_add1_recipient_cert.pod Normal file
View File

@@ -0,0 +1,72 @@
=pod
=head1 NAME
CMS_add1_recipient_cert, CMS_add0_recipient_key - add recipients to a CMS enveloped data structure
=head1 SYNOPSIS
#include <openssl/cms.h>
CMS_RecipientInfo *CMS_add1_recipient_cert(CMS_ContentInfo *cms,
X509 *recip, unsigned int flags);
CMS_RecipientInfo *CMS_add0_recipient_key(CMS_ContentInfo *cms, int nid,
unsigned char *key, size_t keylen,
unsigned char *id, size_t idlen,
ASN1_GENERALIZEDTIME *date,
ASN1_OBJECT *otherTypeId,
ASN1_TYPE *otherType);
=head1 DESCRIPTION
CMS_add1_recipient_cert() adds recipient B<recip> to CMS_ContentInfo enveloped
data structure B<cms> as a KeyTransRecipientInfo structure.
CMS_add0_recipient_key() adds symmetric key B<key> of length B<keylen> using
wrapping algorithm B<nid>, identifier B<id> of length B<idlen> and optional
values B<date>, B<otherTypeId> and B<otherType> to CMS_ContentInfo enveloped
data structure B<cms> as a KEKRecipientInfo structure.
The CMS_ContentInfo structure should be obtained from an initial call to
CMS_encrypt() with the flag B<CMS_PARTIAL> set.
=head1 NOTES
The main purpose of this function is to provide finer control over a CMS
enveloped data structure where the simpler CMS_encrypt() function defaults are
not appropriate. For example if one or more KEKRecipientInfo structures
need to be added. New attributes can also be added using the returned
CMS_RecipientInfo structure and the CMS attribute utility functions.
OpenSSL will by default identify recipient certificates using issuer name
and serial number. If B<CMS_USE_KEYID> is set it will use the subject key
identifier value instead. An error occurs if all recipient certificates do not
have a subject key identifier extension.
Currently only AES based key wrapping algorithms are supported for B<nid>,
specifically: NID_id_aes128_wrap, NID_id_aes192_wrap and NID_id_aes256_wrap.
If B<nid> is set to B<NID_undef> then an AES wrap algorithm will be used
consistent with B<keylen>.
=head1 RETURN VALUES
CMS_add1_recipient_cert() and CMS_add0_recipient_key() return an internal
pointer to the CMS_RecipientInfo structure just added or NULL if an error
occurs.
=head1 SEE ALSO
L<ERR_get_error(3)>, L<CMS_decrypt(3)>,
L<CMS_final(3)>,
=head1 COPYRIGHT
Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

107
doc/man3/CMS_add1_signer.pod Normal file
View File

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

81
doc/man3/CMS_compress.pod Normal file
View File

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

82
doc/man3/CMS_decrypt.pod Normal file
View File

@@ -0,0 +1,82 @@
=pod
=head1 NAME
CMS_decrypt - decrypt content from a CMS envelopedData structure
=head1 SYNOPSIS
#include <openssl/cms.h>
int CMS_decrypt(CMS_ContentInfo *cms, EVP_PKEY *pkey, X509 *cert,
BIO *dcont, BIO *out, unsigned int flags);
=head1 DESCRIPTION
CMS_decrypt() extracts and decrypts the content from a CMS EnvelopedData
structure. B<pkey> is the private key of the recipient, B<cert> is the
recipient's certificate, B<out> is a BIO to write the content to and
B<flags> is an optional set of flags.
The B<dcont> parameter is used in the rare case where the encrypted content
is detached. It will normally be set to NULL.
=head1 NOTES
Although the recipients certificate is not needed to decrypt the data it is
needed to locate the appropriate (of possible several) recipients in the CMS
structure.
If B<cert> is set to NULL all possible recipients are tried. This case however
is problematic. To thwart the MMA attack (Bleichenbacher's attack on
PKCS #1 v1.5 RSA padding) all recipients are tried whether they succeed or
not. If no recipient succeeds then a random symmetric key is used to decrypt
the content: this will typically output garbage and may (but is not guaranteed
to) ultimately return a padding error only. If CMS_decrypt() just returned an
error when all recipient encrypted keys failed to decrypt an attacker could
use this in a timing attack. If the special flag B<CMS_DEBUG_DECRYPT> is set
then the above behaviour is modified and an error B<is> returned if no
recipient encrypted key can be decrypted B<without> generating a random
content encryption key. Applications should use this flag with
B<extreme caution> especially in automated gateways as it can leave them
open to attack.
It is possible to determine the correct recipient key by other means (for
example looking them up in a database) and setting them in the CMS structure
in advance using the CMS utility functions such as CMS_set1_pkey(). In this
case both B<cert> and B<pkey> should be set to NULL.
To process KEKRecipientInfo types CMS_set1_key() or CMS_RecipientInfo_set0_key()
and CMS_RecipientInfo_decrypt() should be called before CMS_decrypt() and
B<cert> and B<pkey> set to NULL.
The following flags can be passed in the B<flags> parameter.
If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are deleted
from the content. If the content is not of type B<text/plain> then an error is
returned.
=head1 RETURN VALUES
CMS_decrypt() returns either 1 for success or 0 for failure.
The error can be obtained from ERR_get_error(3)
=head1 BUGS
The lack of single pass processing and the need to hold all data in memory as
mentioned in CMS_verify() also applies to CMS_decrypt().
=head1 SEE ALSO
L<ERR_get_error(3)>, L<CMS_encrypt(3)>
=head1 COPYRIGHT
Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

104
doc/man3/CMS_encrypt.pod Normal file
View File

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

46
doc/man3/CMS_final.pod Normal file
View File

@@ -0,0 +1,46 @@
=pod
=head1 NAME
CMS_final - finalise a CMS_ContentInfo structure
=head1 SYNOPSIS
#include <openssl/cms.h>
int CMS_final(CMS_ContentInfo *cms, BIO *data, BIO *dcont, unsigned int flags);
=head1 DESCRIPTION
CMS_final() finalises the structure B<cms>. It's purpose is to perform any
operations necessary on B<cms> (digest computation for example) and set the
appropriate fields. The parameter B<data> contains the content to be
processed. The B<dcont> parameter contains a BIO to write content to after
processing: this is only used with detached data and will usually be set to
NULL.
=head1 NOTES
This function will normally be called when the B<CMS_PARTIAL> flag is used. It
should only be used when streaming is not performed because the streaming
I/O functions perform finalisation operations internally.
=head1 RETURN VALUES
CMS_final() returns 1 for success or 0 for failure.
=head1 SEE ALSO
L<ERR_get_error(3)>, L<CMS_sign(3)>,
L<CMS_encrypt(3)>
=head1 COPYRIGHT
Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

139
doc/man3/CMS_get0_RecipientInfos.pod Normal file
View File

@@ -0,0 +1,139 @@
=pod
=head1 NAME
CMS_get0_RecipientInfos, CMS_RecipientInfo_type,
CMS_RecipientInfo_ktri_get0_signer_id, CMS_RecipientInfo_ktri_cert_cmp,
CMS_RecipientInfo_set0_pkey, CMS_RecipientInfo_kekri_get0_id,
CMS_RecipientInfo_kekri_id_cmp, CMS_RecipientInfo_set0_key,
CMS_RecipientInfo_decrypt, CMS_RecipientInfo_encrypt
- CMS envelopedData RecipientInfo routines
=head1 SYNOPSIS
#include <openssl/cms.h>
STACK_OF(CMS_RecipientInfo) *CMS_get0_RecipientInfos(CMS_ContentInfo *cms);
int CMS_RecipientInfo_type(CMS_RecipientInfo *ri);
int CMS_RecipientInfo_ktri_get0_signer_id(CMS_RecipientInfo *ri,
ASN1_OCTET_STRING **keyid,
X509_NAME **issuer,
ASN1_INTEGER **sno);
int CMS_RecipientInfo_ktri_cert_cmp(CMS_RecipientInfo *ri, X509 *cert);
int CMS_RecipientInfo_set0_pkey(CMS_RecipientInfo *ri, EVP_PKEY *pkey);
int CMS_RecipientInfo_kekri_get0_id(CMS_RecipientInfo *ri, X509_ALGOR **palg,
ASN1_OCTET_STRING **pid,
ASN1_GENERALIZEDTIME **pdate,
ASN1_OBJECT **potherid,
ASN1_TYPE **pothertype);
int CMS_RecipientInfo_kekri_id_cmp(CMS_RecipientInfo *ri,
const unsigned char *id, size_t idlen);
int CMS_RecipientInfo_set0_key(CMS_RecipientInfo *ri,
unsigned char *key, size_t keylen);
int CMS_RecipientInfo_decrypt(CMS_ContentInfo *cms, CMS_RecipientInfo *ri);
int CMS_RecipientInfo_encrypt(CMS_ContentInfo *cms, CMS_RecipientInfo *ri);
=head1 DESCRIPTION
The function CMS_get0_RecipientInfos() returns all the CMS_RecipientInfo
structures associated with a CMS EnvelopedData structure.
CMS_RecipientInfo_type() returns the type of CMS_RecipientInfo structure B<ri>.
It will currently return CMS_RECIPINFO_TRANS, CMS_RECIPINFO_AGREE,
CMS_RECIPINFO_KEK, CMS_RECIPINFO_PASS, or CMS_RECIPINFO_OTHER.
CMS_RecipientInfo_ktri_get0_signer_id() retrieves the certificate recipient
identifier associated with a specific CMS_RecipientInfo structure B<ri>, which
must be of type CMS_RECIPINFO_TRANS. Either the keyidentifier will be set in
B<keyid> or B<both> issuer name and serial number in B<issuer> and B<sno>.
CMS_RecipientInfo_ktri_cert_cmp() compares the certificate B<cert> against the
CMS_RecipientInfo structure B<ri>, which must be of type CMS_RECIPINFO_TRANS.
It returns zero if the comparison is successful and non zero if not.
CMS_RecipientInfo_set0_pkey() associates the private key B<pkey> with
the CMS_RecipientInfo structure B<ri>, which must be of type
CMS_RECIPINFO_TRANS.
CMS_RecipientInfo_kekri_get0_id() retrieves the key information from the
CMS_RecipientInfo structure B<ri> which must be of type CMS_RECIPINFO_KEK. Any
of the remaining parameters can be NULL if the application is not interested in
the value of a field. Where a field is optional and absent NULL will be written
to the corresponding parameter. The keyEncryptionAlgorithm field is written to
B<palg>, the B<keyIdentifier> field is written to B<pid>, the B<date> field if
present is written to B<pdate>, if the B<other> field is present the components
B<keyAttrId> and B<keyAttr> are written to parameters B<potherid> and
B<pothertype>.
CMS_RecipientInfo_kekri_id_cmp() compares the ID in the B<id> and B<idlen>
parameters against the B<keyIdentifier> CMS_RecipientInfo structure B<ri>,
which must be of type CMS_RECIPINFO_KEK. It returns zero if the comparison is
successful and non zero if not.
CMS_RecipientInfo_set0_key() associates the symmetric key B<key> of length
B<keylen> with the CMS_RecipientInfo structure B<ri>, which must be of type
CMS_RECIPINFO_KEK.
CMS_RecipientInfo_decrypt() attempts to decrypt CMS_RecipientInfo structure
B<ri> in structure B<cms>. A key must have been associated with the structure
first.
CMS_RecipientInfo_encrypt() attempts to encrypt CMS_RecipientInfo structure
B<ri> in structure B<cms>. A key must have been associated with the structure
first and the content encryption key must be available: for example by a
previous call to CMS_RecipientInfo_decrypt().
=head1 NOTES
The main purpose of these functions is to enable an application to lookup
recipient keys using any appropriate technique when the simpler method
of CMS_decrypt() is not appropriate.
In typical usage and application will retrieve all CMS_RecipientInfo structures
using CMS_get0_RecipientInfos() and check the type of each using
CMS_RecipientInfo_type(). Depending on the type the CMS_RecipientInfo structure
can be ignored or its key identifier data retrieved using an appropriate
function. Then if the corresponding secret or private key can be obtained by
any appropriate means it can then associated with the structure and
CMS_RecipientInfo_decrypt() called. If successful CMS_decrypt() can be called
with a NULL key to decrypt the enveloped content.
The CMS_RecipientInfo_encrypt() can be used to add a new recipient to an
existing enveloped data structure. Typically an application will first decrypt
an appropriate CMS_RecipientInfo structure to make the content encrypt key
available, it will then add a new recipient using a function such as
CMS_add1_recipient_cert() and finally encrypt the content encryption key
using CMS_RecipientInfo_encrypt().
=head1 RETURN VALUES
CMS_get0_RecipientInfos() returns all CMS_RecipientInfo structures, or NULL if
an error occurs.
CMS_RecipientInfo_ktri_get0_signer_id(), CMS_RecipientInfo_set0_pkey(),
CMS_RecipientInfo_kekri_get0_id(), CMS_RecipientInfo_set0_key() and
CMS_RecipientInfo_decrypt() return 1 for success or 0 if an error occurs.
CMS_RecipientInfo_encrypt() return 1 for success or 0 if an error occurs.
CMS_RecipientInfo_ktri_cert_cmp() and CMS_RecipientInfo_kekri_cmp() return 0
for a successful comparison and non zero otherwise.
Any error can be obtained from L<ERR_get_error(3)>.
=head1 SEE ALSO
L<ERR_get_error(3)>, L<CMS_decrypt(3)>
=head1 COPYRIGHT
Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

90
doc/man3/CMS_get0_SignerInfos.pod Normal file
View File

@@ -0,0 +1,90 @@
=pod
=head1 NAME
CMS_SignerInfo_set1_signer_cert,
CMS_get0_SignerInfos, CMS_SignerInfo_get0_signer_id,
CMS_SignerInfo_get0_signature, CMS_SignerInfo_cert_cmp
- CMS signedData signer functions
=head1 SYNOPSIS
#include <openssl/cms.h>
STACK_OF(CMS_SignerInfo) *CMS_get0_SignerInfos(CMS_ContentInfo *cms);
int CMS_SignerInfo_get0_signer_id(CMS_SignerInfo *si, ASN1_OCTET_STRING **keyid,
X509_NAME **issuer, ASN1_INTEGER **sno);
ASN1_OCTET_STRING *CMS_SignerInfo_get0_signature(CMS_SignerInfo *si);
int CMS_SignerInfo_cert_cmp(CMS_SignerInfo *si, X509 *cert);
void CMS_SignerInfo_set1_signer_cert(CMS_SignerInfo *si, X509 *signer);
=head1 DESCRIPTION
The function CMS_get0_SignerInfos() returns all the CMS_SignerInfo structures
associated with a CMS signedData structure.
CMS_SignerInfo_get0_signer_id() retrieves the certificate signer identifier
associated with a specific CMS_SignerInfo structure B<si>. Either the
keyidentifier will be set in B<keyid> or B<both> issuer name and serial number
in B<issuer> and B<sno>.
CMS_SignerInfo_get0_signature() retrieves the signature associated with
B<si> in a pointer to an ASN1_OCTET_STRING structure. This pointer returned
corresponds to the internal signature value if B<si> so it may be read or
modified.
CMS_SignerInfo_cert_cmp() compares the certificate B<cert> against the signer
identifier B<si>. It returns zero if the comparison is successful and non zero
if not.
CMS_SignerInfo_set1_signer_cert() sets the signers certificate of B<si> to
B<signer>.
=head1 NOTES
The main purpose of these functions is to enable an application to lookup
signers certificates using any appropriate technique when the simpler method
of CMS_verify() is not appropriate.
In typical usage and application will retrieve all CMS_SignerInfo structures
using CMS_get0_SignerInfo() and retrieve the identifier information using
CMS. It will then obtain the signer certificate by some unspecified means
(or return and error if it cannot be found) and set it using
CMS_SignerInfo_set1_signer_cert().
Once all signer certificates have been set CMS_verify() can be used.
Although CMS_get0_SignerInfos() can return NULL if an error occurs B<or> if
there are no signers this is not a problem in practice because the only
error which can occur is if the B<cms> structure is not of type signedData
due to application error.
=head1 RETURN VALUES
CMS_get0_SignerInfos() returns all CMS_SignerInfo structures, or NULL there
are no signers or an error occurs.
CMS_SignerInfo_get0_signer_id() returns 1 for success and 0 for failure.
CMS_SignerInfo_cert_cmp() returns 0 for a successful comparison and non
zero otherwise.
CMS_SignerInfo_set1_signer_cert() does not return a value.
Any error can be obtained from L<ERR_get_error(3)>
=head1 SEE ALSO
L<ERR_get_error(3)>, L<CMS_verify(3)>
=head1 COPYRIGHT
Copyright 2008-2018 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

81
doc/man3/CMS_get0_type.pod Normal file
View File

@@ -0,0 +1,81 @@
=pod
=head1 NAME
CMS_get0_type, CMS_set1_eContentType, CMS_get0_eContentType, CMS_get0_content - get and set CMS content types and content
=head1 SYNOPSIS
#include <openssl/cms.h>
const ASN1_OBJECT *CMS_get0_type(const CMS_ContentInfo *cms);
int CMS_set1_eContentType(CMS_ContentInfo *cms, const ASN1_OBJECT *oid);
const ASN1_OBJECT *CMS_get0_eContentType(CMS_ContentInfo *cms);
ASN1_OCTET_STRING **CMS_get0_content(CMS_ContentInfo *cms);
=head1 DESCRIPTION
CMS_get0_type() returns the content type of a CMS_ContentInfo structure as
and ASN1_OBJECT pointer. An application can then decide how to process the
CMS_ContentInfo structure based on this value.
CMS_set1_eContentType() sets the embedded content type of a CMS_ContentInfo
structure. It should be called with CMS functions with the B<CMS_PARTIAL>
flag and B<before> the structure is finalised, otherwise the results are
undefined.
ASN1_OBJECT *CMS_get0_eContentType() returns a pointer to the embedded
content type.
CMS_get0_content() returns a pointer to the B<ASN1_OCTET_STRING> pointer
containing the embedded content.
=head1 NOTES
As the B<0> implies CMS_get0_type(), CMS_get0_eContentType() and
CMS_get0_content() return internal pointers which should B<not> be freed up.
CMS_set1_eContentType() copies the supplied OID and it B<should> be freed up
after use.
The B<ASN1_OBJECT> values returned can be converted to an integer B<NID> value
using OBJ_obj2nid(). For the currently supported content types the following
values are returned:
NID_pkcs7_data
NID_pkcs7_signed
NID_pkcs7_digest
NID_id_smime_ct_compressedData:
NID_pkcs7_encrypted
NID_pkcs7_enveloped
The return value of CMS_get0_content() is a pointer to the B<ASN1_OCTET_STRING>
content pointer. That means that for example:
ASN1_OCTET_STRING **pconf = CMS_get0_content(cms);
B<*pconf> could be NULL if there is no embedded content. Applications can
access, modify or create the embedded content in a B<CMS_ContentInfo> structure
using this function. Applications usually will not need to modify the
embedded content as it is normally set by higher level functions.
=head1 RETURN VALUES
CMS_get0_type() and CMS_get0_eContentType() return and ASN1_OBJECT structure.
CMS_set1_eContentType() returns 1 for success or 0 if an error occurred. The
error can be obtained from ERR_get_error(3).
=head1 SEE ALSO
L<ERR_get_error(3)>
=head1 COPYRIGHT
Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

78
doc/man3/CMS_get1_ReceiptRequest.pod Normal file
View File

@@ -0,0 +1,78 @@
=pod
=head1 NAME
CMS_ReceiptRequest_create0, CMS_add1_ReceiptRequest, CMS_get1_ReceiptRequest, CMS_ReceiptRequest_get0_values - CMS signed receipt request functions
=head1 SYNOPSIS
#include <openssl/cms.h>
CMS_ReceiptRequest *CMS_ReceiptRequest_create0(unsigned char *id, int idlen,
int allorfirst,
STACK_OF(GENERAL_NAMES) *receiptList,
STACK_OF(GENERAL_NAMES) *receiptsTo);
int CMS_add1_ReceiptRequest(CMS_SignerInfo *si, CMS_ReceiptRequest *rr);
int CMS_get1_ReceiptRequest(CMS_SignerInfo *si, CMS_ReceiptRequest **prr);
void CMS_ReceiptRequest_get0_values(CMS_ReceiptRequest *rr, ASN1_STRING **pcid,
int *pallorfirst,
STACK_OF(GENERAL_NAMES) **plist,
STACK_OF(GENERAL_NAMES) **prto);
=head1 DESCRIPTION
CMS_ReceiptRequest_create0() creates a signed receipt request structure. The
B<signedContentIdentifier> field is set using B<id> and B<idlen>, or it is set
to 32 bytes of pseudo random data if B<id> is NULL. If B<receiptList> is NULL
the allOrFirstTier option in B<receiptsFrom> is used and set to the value of
the B<allorfirst> parameter. If B<receiptList> is not NULL the B<receiptList>
option in B<receiptsFrom> is used. The B<receiptsTo> parameter specifies the
B<receiptsTo> field value.
The CMS_add1_ReceiptRequest() function adds a signed receipt request B<rr>
to SignerInfo structure B<si>.
int CMS_get1_ReceiptRequest() looks for a signed receipt request in B<si>, if
any is found it is decoded and written to B<prr>.
CMS_ReceiptRequest_get0_values() retrieves the values of a receipt request.
The signedContentIdentifier is copied to B<pcid>. If the B<allOrFirstTier>
option of B<receiptsFrom> is used its value is copied to B<pallorfirst>
otherwise the B<receiptList> field is copied to B<plist>. The B<receiptsTo>
parameter is copied to B<prto>.
=head1 NOTES
For more details of the meaning of the fields see RFC2634.
The contents of a signed receipt should only be considered meaningful if the
corresponding CMS_ContentInfo structure can be successfully verified using
CMS_verify().
=head1 RETURN VALUES
CMS_ReceiptRequest_create0() returns a signed receipt request structure or
NULL if an error occurred.
CMS_add1_ReceiptRequest() returns 1 for success or 0 if an error occurred.
CMS_get1_ReceiptRequest() returns 1 is a signed receipt request is found and
decoded. It returns 0 if a signed receipt request is not present and -1 if
it is present but malformed.
=head1 SEE ALSO
L<ERR_get_error(3)>, L<CMS_sign(3)>,
L<CMS_sign_receipt(3)>, L<CMS_verify(3)>
L<CMS_verify_receipt(3)>
=head1 COPYRIGHT
Copyright 2008-2018 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

129
doc/man3/CMS_sign.pod Normal file
View File

@@ -0,0 +1,129 @@
=pod
=head1 NAME
CMS_sign - create a CMS SignedData structure
=head1 SYNOPSIS
#include <openssl/cms.h>
CMS_ContentInfo *CMS_sign(X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs,
BIO *data, unsigned int flags);
=head1 DESCRIPTION
CMS_sign() creates and returns a CMS SignedData structure. B<signcert> is
the certificate to sign with, B<pkey> is the corresponding private key.
B<certs> is an optional additional set of certificates to include in the CMS
structure (for example any intermediate CAs in the chain). Any or all of
these parameters can be B<NULL>, see B<NOTES> below.
The data to be signed is read from BIO B<data>.
B<flags> is an optional set of flags.
=head1 NOTES
Any of the following flags (ored together) can be passed in the B<flags>
parameter.
Many S/MIME clients expect the signed content to include valid MIME headers. If
the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are prepended
to the data.
If B<CMS_NOCERTS> is set the signer's certificate will not be included in the
CMS_ContentInfo structure, the signer's certificate must still be supplied in
the B<signcert> parameter though. This can reduce the size of the signature if
the signers certificate can be obtained by other means: for example a
previously signed message.
The data being signed is included in the CMS_ContentInfo structure, unless
B<CMS_DETACHED> is set in which case it is omitted. This is used for
CMS_ContentInfo detached signatures which are used in S/MIME plaintext signed
messages for example.
Normally the supplied content is translated into MIME canonical format (as
required by the S/MIME specifications) if B<CMS_BINARY> is set no translation
occurs. This option should be used if the supplied data is in binary format
otherwise the translation will corrupt it.
The SignedData structure includes several CMS signedAttributes including the
signing time, the CMS content type and the supported list of ciphers in an
SMIMECapabilities attribute. If B<CMS_NOATTR> is set then no signedAttributes
will be used. If B<CMS_NOSMIMECAP> is set then just the SMIMECapabilities are
omitted.
If present the SMIMECapabilities attribute indicates support for the following
algorithms in preference order: 256 bit AES, Gost R3411-94, Gost 28147-89, 192
bit AES, 128 bit AES, triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2.
If any of these algorithms is not available then it will not be included: for example the GOST algorithms will not be included if the GOST ENGINE is
not loaded.
OpenSSL will by default identify signing certificates using issuer name
and serial number. If B<CMS_USE_KEYID> is set it will use the subject key
identifier value instead. An error occurs if the signing certificate does not
have a subject key identifier extension.
If the flags B<CMS_STREAM> is set then the returned B<CMS_ContentInfo>
structure is just initialized ready to perform the signing operation. The
signing is however B<not> performed and the data to be signed is not read from
the B<data> parameter. Signing is deferred until after the data has been
written. In this way data can be signed in a single pass.
If the B<CMS_PARTIAL> flag is set a partial B<CMS_ContentInfo> structure is
output to which additional signers and capabilities can be added before
finalization.
If the flag B<CMS_STREAM> is set the returned B<CMS_ContentInfo> structure is
B<not> complete and outputting its contents via a function that does not
properly finalize the B<CMS_ContentInfo> structure will give unpredictable
results.
Several functions including SMIME_write_CMS(), i2d_CMS_bio_stream(),
PEM_write_bio_CMS_stream() finalize the structure. Alternatively finalization
can be performed by obtaining the streaming ASN1 B<BIO> directly using
BIO_new_CMS().
If a signer is specified it will use the default digest for the signing
algorithm. This is B<SHA1> for both RSA and DSA keys.
If B<signcert> and B<pkey> are NULL then a certificates only CMS structure is
output.
The function CMS_sign() is a basic CMS signing function whose output will be
suitable for many purposes. For finer control of the output format the
B<certs>, B<signcert> and B<pkey> parameters can all be B<NULL> and the
B<CMS_PARTIAL> flag set. Then one or more signers can be added using the
function CMS_sign_add1_signer(), non default digests can be used and custom
attributes added. CMS_final() must then be called to finalize the
structure if streaming is not enabled.
=head1 BUGS
Some attributes such as counter signatures are not supported.
=head1 RETURN VALUES
CMS_sign() returns either a valid CMS_ContentInfo structure or NULL if an error
occurred. The error can be obtained from ERR_get_error(3).
=head1 SEE ALSO
L<ERR_get_error(3)>, L<CMS_verify(3)>
=head1 HISTORY
The B<CMS_STREAM> flag is only supported for detached data in OpenSSL 0.9.8,
it is supported for embedded data in OpenSSL 1.0.0 and later.
=head1 COPYRIGHT
Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

52
doc/man3/CMS_sign_receipt.pod Normal file
View File

@@ -0,0 +1,52 @@
=pod
=head1 NAME
CMS_sign_receipt - create a CMS signed receipt
=head1 SYNOPSIS
#include <openssl/cms.h>
CMS_ContentInfo *CMS_sign_receipt(CMS_SignerInfo *si, X509 *signcert,
EVP_PKEY *pkey, STACK_OF(X509) *certs,
unsigned int flags);
=head1 DESCRIPTION
CMS_sign_receipt() creates and returns a CMS signed receipt structure. B<si> is
the B<CMS_SignerInfo> structure containing the signed receipt request.
B<signcert> is the certificate to sign with, B<pkey> is the corresponding
private key. B<certs> is an optional additional set of certificates to include
in the CMS structure (for example any intermediate CAs in the chain).
B<flags> is an optional set of flags.
=head1 NOTES
This functions behaves in a similar way to CMS_sign() except the flag values
B<CMS_DETACHED>, B<CMS_BINARY>, B<CMS_NOATTR>, B<CMS_TEXT> and B<CMS_STREAM>
are not supported since they do not make sense in the context of signed
receipts.
=head1 RETURN VALUES
CMS_sign_receipt() returns either a valid CMS_ContentInfo structure or NULL if
an error occurred. The error can be obtained from ERR_get_error(3).
=head1 SEE ALSO
L<ERR_get_error(3)>,
L<CMS_verify_receipt(3)>,
L<CMS_sign(3)>
=head1 COPYRIGHT
Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

59
doc/man3/CMS_uncompress.pod Normal file
View File

@@ -0,0 +1,59 @@
=pod
=head1 NAME
CMS_uncompress - uncompress a CMS CompressedData structure
=head1 SYNOPSIS
#include <openssl/cms.h>
int CMS_uncompress(CMS_ContentInfo *cms, BIO *dcont, BIO *out, unsigned int flags);
=head1 DESCRIPTION
CMS_uncompress() extracts and uncompresses the content from a CMS
CompressedData structure B<cms>. B<data> is a BIO to write the content to and
B<flags> is an optional set of flags.
The B<dcont> parameter is used in the rare case where the compressed content
is detached. It will normally be set to NULL.
=head1 NOTES
The only currently supported compression algorithm is zlib: if the structure
indicates the use of any other algorithm an error is returned.
If zlib support is not compiled into OpenSSL then CMS_uncompress() will always
return an error.
The following flags can be passed in the B<flags> parameter.
If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are deleted
from the content. If the content is not of type B<text/plain> then an error is
returned.
=head1 RETURN VALUES
CMS_uncompress() returns either 1 for success or 0 for failure. The error can
be obtained from ERR_get_error(3)
=head1 BUGS
The lack of single pass processing and the need to hold all data in memory as
mentioned in CMS_verify() also applies to CMS_decompress().
=head1 SEE ALSO
L<ERR_get_error(3)>, L<CMS_compress(3)>
=head1 COPYRIGHT
Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

132
doc/man3/CMS_verify.pod Normal file
View File

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

54
doc/man3/CMS_verify_receipt.pod Normal file
View File

@@ -0,0 +1,54 @@
=pod
=head1 NAME
CMS_verify_receipt - verify a CMS signed receipt
=head1 SYNOPSIS
#include <openssl/cms.h>
int CMS_verify_receipt(CMS_ContentInfo *rcms, CMS_ContentInfo *ocms,
STACK_OF(X509) *certs, X509_STORE *store,
unsigned int flags);
=head1 DESCRIPTION
CMS_verify_receipt() verifies a CMS signed receipt. B<rcms> is the signed
receipt to verify. B<ocms> is the original SignedData structure containing the
receipt request. B<certs> is a set of certificates in which to search for the
signing certificate. B<store> is a trusted certificate store (used for chain
verification).
B<flags> is an optional set of flags, which can be used to modify the verify
operation.
=head1 NOTES
This functions behaves in a similar way to CMS_verify() except the flag values
B<CMS_DETACHED>, B<CMS_BINARY>, B<CMS_TEXT> and B<CMS_STREAM> are not
supported since they do not make sense in the context of signed receipts.
=head1 RETURN VALUES
CMS_verify_receipt() returns 1 for a successful verification and zero if an
error occurred.
The error can be obtained from L<ERR_get_error(3)>
=head1 SEE ALSO
L<ERR_get_error(3)>,
L<CMS_sign_receipt(3)>,
L<CMS_verify(3)>,
=head1 COPYRIGHT
Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

58
doc/man3/CONF_modules_free.pod Normal file
View File

@@ -0,0 +1,58 @@
=pod
=head1 NAME
CONF_modules_free, CONF_modules_finish, CONF_modules_unload -
OpenSSL configuration cleanup functions
=head1 SYNOPSIS
#include <openssl/conf.h>
void CONF_modules_finish(void);
void CONF_modules_unload(int all);
Deprecated:
#if OPENSSL_API_COMPAT < 0x10100000L
void CONF_modules_free(void)
#endif
=head1 DESCRIPTION
CONF_modules_free() closes down and frees up all memory allocated by all
configuration modules. Normally, in versions of OpenSSL prior to 1.1.0,
applications called
CONF_modules_free() at exit to tidy up any configuration performed.
CONF_modules_finish() calls each configuration modules B<finish> handler
to free up any configuration that module may have performed.
CONF_modules_unload() finishes and unloads configuration modules. If
B<all> is set to B<0> only modules loaded from DSOs will be unloads. If
B<all> is B<1> all modules, including builtin modules will be unloaded.
=head1 RETURN VALUES
None of the functions return a value.
=head1 SEE ALSO
L<config(5)>, L<OPENSSL_config(3)>,
L<CONF_modules_load_file(3)>
=head1 HISTORY
CONF_modules_free() was deprecated in OpenSSL 1.1.0; do not use it.
For more information see L<OPENSSL_init_crypto(3)>.
=head1 COPYRIGHT
Copyright 2004-2018 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

136
doc/man3/CONF_modules_load_file.pod Normal file
View File

@@ -0,0 +1,136 @@
=pod
=head1 NAME
CONF_modules_load_file, CONF_modules_load - OpenSSL configuration functions
=head1 SYNOPSIS
#include <openssl/conf.h>
int CONF_modules_load_file(const char *filename, const char *appname,
unsigned long flags);
int CONF_modules_load(const CONF *cnf, const char *appname,
unsigned long flags);
=head1 DESCRIPTION
The function CONF_modules_load_file() configures OpenSSL using file
B<filename> and application name B<appname>. If B<filename> is NULL
the standard OpenSSL configuration file is used. If B<appname> is
NULL the standard OpenSSL application name B<openssl_conf> is used.
The behaviour can be customized using B<flags>.
CONF_modules_load() is identical to CONF_modules_load_file() except it
reads configuration information from B<cnf>.
=head1 NOTES
The following B<flags> are currently recognized:
B<CONF_MFLAGS_IGNORE_ERRORS> if set errors returned by individual
configuration modules are ignored. If not set the first module error is
considered fatal and no further modules are loaded.
Normally any modules errors will add error information to the error queue. If
B<CONF_MFLAGS_SILENT> is set no error information is added.
If B<CONF_MFLAGS_NO_DSO> is set configuration module loading from DSOs is
disabled.
B<CONF_MFLAGS_IGNORE_MISSING_FILE> if set will make CONF_load_modules_file()
ignore missing configuration files. Normally a missing configuration file
return an error.
B<CONF_MFLAGS_DEFAULT_SECTION> if set and B<appname> is not NULL will use the
default section pointed to by B<openssl_conf> if B<appname> does not exist.
By using CONF_modules_load_file() with appropriate flags an application can
customise application configuration to best suit its needs. In some cases the
use of a configuration file is optional and its absence is not an error: in
this case B<CONF_MFLAGS_IGNORE_MISSING_FILE> would be set.
Errors during configuration may also be handled differently by different
applications. For example in some cases an error may simply print out a warning
message and the application continue. In other cases an application might
consider a configuration file error as fatal and exit immediately.
Applications can use the CONF_modules_load() function if they wish to load a
configuration file themselves and have finer control over how errors are
treated.
=head1 EXAMPLES
Load a configuration file and print out any errors and exit (missing file
considered fatal):
if (CONF_modules_load_file(NULL, NULL, 0) <= 0) {
fprintf(stderr, "FATAL: error loading configuration file\n");
ERR_print_errors_fp(stderr);
exit(1);
}
Load default configuration file using the section indicated by "myapp",
tolerate missing files, but exit on other errors:
if (CONF_modules_load_file(NULL, "myapp",
CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) {
fprintf(stderr, "FATAL: error loading configuration file\n");
ERR_print_errors_fp(stderr);
exit(1);
}
Load custom configuration file and section, only print warnings on error,
missing configuration file ignored:
if (CONF_modules_load_file("/something/app.cnf", "myapp",
CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) {
fprintf(stderr, "WARNING: error loading configuration file\n");
ERR_print_errors_fp(stderr);
}
Load and parse configuration file manually, custom error handling:
FILE *fp;
CONF *cnf = NULL;
long eline;
fp = fopen("/somepath/app.cnf", "r");
if (fp == NULL) {
fprintf(stderr, "Error opening configuration file\n");
/* Other missing configuration file behaviour */
} else {
cnf = NCONF_new(NULL);
if (NCONF_load_fp(cnf, fp, &eline) == 0) {
fprintf(stderr, "Error on line %ld of configuration file\n", eline);
ERR_print_errors_fp(stderr);
/* Other malformed configuration file behaviour */
} else if (CONF_modules_load(cnf, "appname", 0) <= 0) {
fprintf(stderr, "Error configuring application\n");
ERR_print_errors_fp(stderr);
/* Other configuration error behaviour */
}
fclose(fp);
NCONF_free(cnf);
}
=head1 RETURN VALUES
These functions return 1 for success and a zero or negative value for
failure. If module errors are not ignored the return code will reflect the
return value of the failing module (this will always be zero or negative).
=head1 SEE ALSO
L<config(5)>, L<OPENSSL_config(3)>
=head1 COPYRIGHT
Copyright 2004-2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

171
doc/man3/CRYPTO_THREAD_run_once.pod Normal file
View File

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

167
doc/man3/CRYPTO_get_ex_new_index.pod Normal file
View File

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

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

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

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

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

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

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

128
doc/man3/CT_POLICY_EVAL_CTX_new.pod Normal file
View File

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

271
doc/man3/DEFINE_STACK_OF.pod Normal file
View File

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

321
doc/man3/DES_random_key.pod Normal file
View File

@@ -0,0 +1,321 @@
=pod
=head1 NAME
DES_random_key, DES_set_key, DES_key_sched, DES_set_key_checked,
DES_set_key_unchecked, DES_set_odd_parity, DES_is_weak_key,
DES_ecb_encrypt, DES_ecb2_encrypt, DES_ecb3_encrypt, DES_ncbc_encrypt,
DES_cfb_encrypt, DES_ofb_encrypt, DES_pcbc_encrypt, DES_cfb64_encrypt,
DES_ofb64_encrypt, DES_xcbc_encrypt, DES_ede2_cbc_encrypt,
DES_ede2_cfb64_encrypt, DES_ede2_ofb64_encrypt, DES_ede3_cbc_encrypt,
DES_ede3_cfb64_encrypt, DES_ede3_ofb64_encrypt,
DES_cbc_cksum, DES_quad_cksum, DES_string_to_key, DES_string_to_2keys,
DES_fcrypt, DES_crypt - DES encryption
=head1 SYNOPSIS
#include <openssl/des.h>
void DES_random_key(DES_cblock *ret);
int DES_set_key(const_DES_cblock *key, DES_key_schedule *schedule);
int DES_key_sched(const_DES_cblock *key, DES_key_schedule *schedule);
int DES_set_key_checked(const_DES_cblock *key, DES_key_schedule *schedule);
void DES_set_key_unchecked(const_DES_cblock *key, DES_key_schedule *schedule);
void DES_set_odd_parity(DES_cblock *key);
int DES_is_weak_key(const_DES_cblock *key);
void DES_ecb_encrypt(const_DES_cblock *input, DES_cblock *output,
DES_key_schedule *ks, int enc);
void DES_ecb2_encrypt(const_DES_cblock *input, DES_cblock *output,
DES_key_schedule *ks1, DES_key_schedule *ks2, int enc);
void DES_ecb3_encrypt(const_DES_cblock *input, DES_cblock *output,
DES_key_schedule *ks1, DES_key_schedule *ks2,
DES_key_schedule *ks3, int enc);
void DES_ncbc_encrypt(const unsigned char *input, unsigned char *output,
long length, DES_key_schedule *schedule, DES_cblock *ivec,
int enc);
void DES_cfb_encrypt(const unsigned char *in, unsigned char *out,
int numbits, long length, DES_key_schedule *schedule,
DES_cblock *ivec, int enc);
void DES_ofb_encrypt(const unsigned char *in, unsigned char *out,
int numbits, long length, DES_key_schedule *schedule,
DES_cblock *ivec);
void DES_pcbc_encrypt(const unsigned char *input, unsigned char *output,
long length, DES_key_schedule *schedule, DES_cblock *ivec,
int enc);
void DES_cfb64_encrypt(const unsigned char *in, unsigned char *out,
long length, DES_key_schedule *schedule, DES_cblock *ivec,
int *num, int enc);
void DES_ofb64_encrypt(const unsigned char *in, unsigned char *out,
long length, DES_key_schedule *schedule, DES_cblock *ivec,
int *num);
void DES_xcbc_encrypt(const unsigned char *input, unsigned char *output,
long length, DES_key_schedule *schedule, DES_cblock *ivec,
const_DES_cblock *inw, const_DES_cblock *outw, int enc);
void DES_ede2_cbc_encrypt(const unsigned char *input, unsigned char *output,
long length, DES_key_schedule *ks1,
DES_key_schedule *ks2, DES_cblock *ivec, int enc);
void DES_ede2_cfb64_encrypt(const unsigned char *in, unsigned char *out,
long length, DES_key_schedule *ks1,
DES_key_schedule *ks2, DES_cblock *ivec,
int *num, int enc);
void DES_ede2_ofb64_encrypt(const unsigned char *in, unsigned char *out,
long length, DES_key_schedule *ks1,
DES_key_schedule *ks2, DES_cblock *ivec, int *num);
void DES_ede3_cbc_encrypt(const unsigned char *input, unsigned char *output,
long length, DES_key_schedule *ks1,
DES_key_schedule *ks2, DES_key_schedule *ks3,
DES_cblock *ivec, int enc);
void DES_ede3_cfb64_encrypt(const unsigned char *in, unsigned char *out,
long length, DES_key_schedule *ks1,
DES_key_schedule *ks2, DES_key_schedule *ks3,
DES_cblock *ivec, int *num, int enc);
void DES_ede3_ofb64_encrypt(const unsigned char *in, unsigned char *out,
long length, DES_key_schedule *ks1,
DES_key_schedule *ks2, DES_key_schedule *ks3,
DES_cblock *ivec, int *num);
DES_LONG DES_cbc_cksum(const unsigned char *input, DES_cblock *output,
long length, DES_key_schedule *schedule,
const_DES_cblock *ivec);
DES_LONG DES_quad_cksum(const unsigned char *input, DES_cblock output[],
long length, int out_count, DES_cblock *seed);
void DES_string_to_key(const char *str, DES_cblock *key);
void DES_string_to_2keys(const char *str, DES_cblock *key1, DES_cblock *key2);
char *DES_fcrypt(const char *buf, const char *salt, char *ret);
char *DES_crypt(const char *buf, const char *salt);
=head1 DESCRIPTION
This library contains a fast implementation of the DES encryption
algorithm.
There are two phases to the use of DES encryption. The first is the
generation of a I<DES_key_schedule> from a key, the second is the
actual encryption. A DES key is of type I<DES_cblock>. This type
consists of 8 bytes with odd parity. The least significant bit in
each byte is the parity bit. The key schedule is an expanded form of
the key; it is used to speed the encryption process.
DES_random_key() generates a random key. The PRNG must be seeded
prior to using this function (see L<RAND_bytes(3)>). If the PRNG
could not generate a secure key, 0 is returned.
Before a DES key can be used, it must be converted into the
architecture dependent I<DES_key_schedule> via the
DES_set_key_checked() or DES_set_key_unchecked() function.
DES_set_key_checked() will check that the key passed is of odd parity
and is not a weak or semi-weak key. If the parity is wrong, then -1
is returned. If the key is a weak key, then -2 is returned. If an
error is returned, the key schedule is not generated.
DES_set_key() works like
DES_set_key_checked() if the I<DES_check_key> flag is non-zero,
otherwise like DES_set_key_unchecked(). These functions are available
for compatibility; it is recommended to use a function that does not
depend on a global variable.
DES_set_odd_parity() sets the parity of the passed I<key> to odd.
DES_is_weak_key() returns 1 if the passed key is a weak key, 0 if it
is ok.
The following routines mostly operate on an input and output stream of
I<DES_cblock>s.
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>
(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
ciphertext) is decrypted into the I<output> (now cleartext). Input
and output may overlap. DES_ecb_encrypt() does not return a value.
DES_ecb3_encrypt() encrypts/decrypts the I<input> block by using
three-key Triple-DES encryption in ECB mode. This involves encrypting
the input with I<ks1>, decrypting with the key schedule I<ks2>, and
then encrypting with I<ks3>. This routine greatly reduces the chances
of brute force breaking of DES and has the advantage of if I<ks1>,
I<ks2> and I<ks3> are the same, it is equivalent to just encryption
using ECB mode and I<ks1> as the key.
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
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,
and initialization vector provided by the I<ivec> argument. If the
I<length> argument is not an integral multiple of eight bytes, the
last block is copied to a temporary area and zero filled. The output
is always an integral multiple of eight bytes.
DES_xcbc_encrypt() is RSA's DESX mode of DES. It uses I<inw> and
I<outw> to 'whiten' the encryption. I<inw> and I<outw> are secret
(unlike the iv) and are as such, part of the key. So the key is sort
of 24 bytes. This is much better than CBC DES.
DES_ede3_cbc_encrypt() implements outer triple CBC DES encryption with
three keys. This means that each DES operation inside the CBC mode is
C<C=E(ks3,D(ks2,E(ks1,M)))>. This mode is used by SSL.
The DES_ede2_cbc_encrypt() macro implements two-key Triple-DES by
reusing I<ks1> for the final encryption. C<C=E(ks1,D(ks2,E(ks1,M)))>.
This form of Triple-DES is used by the RSAREF library.
DES_pcbc_encrypt() encrypts/decrypts using the propagating cipher block
chaining mode used by Kerberos v4. Its parameters are the same as
DES_ncbc_encrypt().
DES_cfb_encrypt() encrypts/decrypts using cipher feedback mode. This
method takes an array of characters as input and outputs an array of
characters. It does not require any padding to 8 character groups.
Note: the I<ivec> variable is changed and the new changed value needs to
be passed to the next call to this function. Since this function runs
a complete DES ECB encryption per I<numbits>, this function is only
suggested for use when sending a small number of characters.
DES_cfb64_encrypt()
implements CFB mode of DES with 64-bit feedback. Why is this
useful you ask? Because this routine will allow you to encrypt an
arbitrary number of bytes, without 8 byte padding. Each call to this
routine will encrypt the input bytes to output and then update ivec
and num. num contains 'how far' we are though ivec. If this does
not make much sense, read more about CFB mode of DES.
DES_ede3_cfb64_encrypt() and DES_ede2_cfb64_encrypt() is the same as
DES_cfb64_encrypt() except that Triple-DES is used.
DES_ofb_encrypt() encrypts using output feedback mode. This method
takes an array of characters as input and outputs an array of
characters. It does not require any padding to 8 character groups.
Note: the I<ivec> variable is changed and the new changed value needs to
be passed to the next call to this function. Since this function runs
a complete DES ECB encryption per I<numbits>, this function is only
suggested for use when sending a small number of characters.
DES_ofb64_encrypt() is the same as DES_cfb64_encrypt() using Output
Feed Back mode.
DES_ede3_ofb64_encrypt() and DES_ede2_ofb64_encrypt() is the same as
DES_ofb64_encrypt(), using Triple-DES.
The following functions are included in the DES library for
compatibility with the MIT Kerberos library.
DES_cbc_cksum() produces an 8 byte checksum based on the input stream
(via CBC encryption). The last 4 bytes of the checksum are returned
and the complete 8 bytes are placed in I<output>. This function is
used by Kerberos v4. Other applications should use
L<EVP_DigestInit(3)> etc. instead.
DES_quad_cksum() is a Kerberos v4 function. It returns a 4 byte
checksum from the input bytes. The algorithm can be iterated over the
input, depending on I<out_count>, 1, 2, 3 or 4 times. If I<output> is
non-NULL, the 8 bytes generated by each pass are written into
I<output>.
The following are DES-based transformations:
DES_fcrypt() is a fast version of the Unix crypt(3) function. This
version takes only a small amount of space relative to other fast
crypt() implementations. This is different to the normal crypt() in
that the third parameter is the buffer that the return value is
written into. It needs to be at least 14 bytes long. This function
is thread safe, unlike the normal crypt().
DES_crypt() is a faster replacement for the normal system crypt().
This function calls DES_fcrypt() with a static array passed as the
third parameter. This mostly emulates the normal non-thread-safe semantics
of crypt(3).
The B<salt> must be two ASCII characters.
The values returned by DES_fcrypt() and DES_crypt() are terminated by NUL
character.
DES_enc_write() writes I<len> bytes to file descriptor I<fd> from
buffer I<buf>. The data is encrypted via I<pcbc_encrypt> (default)
using I<sched> for the key and I<iv> as a starting vector. The actual
data send down I<fd> consists of 4 bytes (in network byte order)
containing the length of the following encrypted data. The encrypted
data then follows, padded with random data out to a multiple of 8
bytes.
=head1 BUGS
DES_cbc_encrypt() does not modify B<ivec>; use DES_ncbc_encrypt()
instead.
DES_cfb_encrypt() and DES_ofb_encrypt() operates on input of 8 bits.
What this means is that if you set numbits to 12, and length to 2, the
first 12 bits will come from the 1st input byte and the low half of
the second input byte. The second 12 bits will have the low 8 bits
taken from the 3rd input byte and the top 4 bits taken from the 4th
input byte. The same holds for output. This function has been
implemented this way because most people will be using a multiple of 8
and because once you get into pulling bytes input bytes apart things
get ugly!
DES_string_to_key() is available for backward compatibility with the
MIT library. New applications should use a cryptographic hash function.
The same applies for DES_string_to_2key().
=head1 NOTES
The B<des> library was written to be source code compatible with
the MIT Kerberos library.
Applications should use the higher level functions
L<EVP_EncryptInit(3)> etc. instead of calling these
functions directly.
Single-key DES is insecure due to its short key size. ECB mode is
not suitable for most applications; see L<des_modes(7)>.
=head1 RETURN VALUES
DES_set_key(), DES_key_sched(), DES_set_key_checked() and DES_is_weak_key()
return 0 on success or negative values on error.
DES_cbc_cksum() and DES_quad_cksum() return 4-byte integer representing the
last 4 bytes of the checksum of the input.
DES_fcrypt() returns a pointer to the caller-provided buffer and DES_crypt() -
to a static buffer on success; otherwise they return NULL.
=head1 HISTORY
The requirement that the B<salt> parameter to DES_crypt() and DES_fcrypt()
be two ASCII characters was first enforced in
OpenSSL 1.1.0. Previous versions tried to use the letter uppercase B<A>
if both character were not present, and could crash when given non-ASCII
on some platforms.
=head1 SEE ALSO
L<des_modes(7)>,
L<EVP_EncryptInit(3)>
=head1 COPYRIGHT
Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

54
doc/man3/DH_generate_key.pod Normal file
View File

@@ -0,0 +1,54 @@
=pod
=head1 NAME
DH_generate_key, DH_compute_key - perform Diffie-Hellman key exchange
=head1 SYNOPSIS
#include <openssl/dh.h>
int DH_generate_key(DH *dh);
int DH_compute_key(unsigned char *key, BIGNUM *pub_key, DH *dh);
=head1 DESCRIPTION
DH_generate_key() performs the first step of a Diffie-Hellman key
exchange by generating private and public DH values. By calling
DH_compute_key(), these are combined with the other party's public
value to compute the shared key.
DH_generate_key() expects B<dh> to contain the shared parameters
B<dh-E<gt>p> and B<dh-E<gt>g>. It generates a random private DH value
unless B<dh-E<gt>priv_key> is already set, and computes the
corresponding public value B<dh-E<gt>pub_key>, which can then be
published.
DH_compute_key() computes the shared secret from the private DH value
in B<dh> and the other party's public value in B<pub_key> and stores
it in B<key>. B<key> must point to B<DH_size(dh)> bytes of memory.
=head1 RETURN VALUES
DH_generate_key() returns 1 on success, 0 otherwise.
DH_compute_key() returns the size of the shared secret on success, -1
on error.
The error codes can be obtained by L<ERR_get_error(3)>.
=head1 SEE ALSO
L<DH_new(3)>, L<ERR_get_error(3)>, L<RAND_bytes(3)>, L<DH_size(3)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

151
doc/man3/DH_generate_parameters.pod Normal file
View File

@@ -0,0 +1,151 @@
=pod
=head1 NAME
DH_generate_parameters_ex, DH_generate_parameters,
DH_check, DH_check_params,
DH_check_ex, DH_check_params_ex, DH_check_pub_key_ex
- generate and check Diffie-Hellman
parameters
=head1 SYNOPSIS
#include <openssl/dh.h>
int DH_generate_parameters_ex(DH *dh, int prime_len, int generator, BN_GENCB *cb);
int DH_check(DH *dh, int *codes);
int DH_check_params(DH *dh, int *codes);
int DH_check_ex(const DH *dh);
int DH_check_params_ex(const DH *dh);
int DH_check_pub_key_ex(const DH *dh, const BIGNUM *pub_key);
Deprecated:
#if OPENSSL_API_COMPAT < 0x00908000L
DH *DH_generate_parameters(int prime_len, int generator,
void (*callback)(int, int, void *), void *cb_arg);
#endif
=head1 DESCRIPTION
DH_generate_parameters_ex() generates Diffie-Hellman parameters that can
be shared among a group of users, and stores them in the provided B<DH>
structure. The pseudo-random number generator must be
seeded before calling it.
The parameters generated by DH_generate_parameters_ex() should not be used in
signature schemes.
B<prime_len> is the length in bits of the safe prime to be generated.
B<generator> is a small number E<gt> 1, typically 2 or 5.
A callback function may be used to provide feedback about the progress
of the key generation. If B<cb> is not B<NULL>, it will be
called as described in L<BN_generate_prime(3)> while a random prime
number is generated, and when a prime has been found, B<BN_GENCB_call(cb, 3, 0)>
is called. See L<BN_generate_prime_ex(3)> for information on
the BN_GENCB_call() function.
DH_generate_parameters() is similar to DH_generate_prime_ex() but
expects an old-style callback function; see
L<BN_generate_prime(3)> for information on the old-style callback.
DH_check_params() confirms that the B<p> and B<g> are likely enough to
be valid.
This is a lightweight check, if a more thorough check is needed, use
DH_check().
The value of B<*codes> is updated with any problems found.
If B<*codes> is zero then no problems were found, otherwise the
following bits may be set:
=over 4
=item DH_CHECK_P_NOT_PRIME
The parameter B<p> has been determined to not being an odd prime.
Note that the lack of this bit doesn't guarantee that B<p> is a
prime.
=item DH_NOT_SUITABLE_GENERATOR
The generator B<g> is not suitable.
Note that the lack of this bit doesn't guarantee that B<g> is
suitable, unless B<p> is known to be a strong prime.
=back
DH_check() confirms that the Diffie-Hellman parameters B<dh> are valid. The
value of B<*codes> is updated with any problems found. If B<*codes> is zero then
no problems were found, otherwise the following bits may be set:
=over 4
=item DH_CHECK_P_NOT_PRIME
The parameter B<p> is not prime.
=item DH_CHECK_P_NOT_SAFE_PRIME
The parameter B<p> is not a safe prime and no B<q> value is present.
=item DH_UNABLE_TO_CHECK_GENERATOR
The generator B<g> cannot be checked for suitability.
=item DH_NOT_SUITABLE_GENERATOR
The generator B<g> is not suitable.
=item DH_CHECK_Q_NOT_PRIME
The parameter B<q> is not prime.
=item DH_CHECK_INVALID_Q_VALUE
The parameter B<q> is invalid.
=item DH_CHECK_INVALID_J_VALUE
The parameter B<j> is invalid.
=back
DH_check_ex(), DH_check_params() and DH_check_pub_key_ex() are similar to
DH_check() and DH_check_params() respectively, but the error reasons are added
to the thread's error queue instead of provided as return values from the
function.
=head1 RETURN VALUES
DH_generate_parameters_ex(), DH_check() and DH_check_params() return 1
if the check could be performed, 0 otherwise.
DH_generate_parameters() returns a pointer to the DH structure or NULL if
the parameter generation fails.
DH_check_ex(), DH_check_params() and DH_check_pub_key_ex() return 1 if the
check is successful, 0 for failed.
The error codes can be obtained by L<ERR_get_error(3)>.
=head1 SEE ALSO
L<DH_new(3)>, L<ERR_get_error(3)>, L<RAND_bytes(3)>,
L<DH_free(3)>
=head1 HISTORY
DH_generate_parameters() was deprecated in OpenSSL 0.9.8; use
DH_generate_parameters_ex() instead.
=head1 COPYRIGHT
Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

128
doc/man3/DH_get0_pqg.pod Normal file
View File

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

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

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

167
doc/man3/DH_meth_new.pod Normal file
View File

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

46
doc/man3/DH_new.pod Normal file
View File

@@ -0,0 +1,46 @@
=pod
=head1 NAME
DH_new, DH_free - allocate and free DH objects
=head1 SYNOPSIS
#include <openssl/dh.h>
DH* DH_new(void);
void DH_free(DH *dh);
=head1 DESCRIPTION
DH_new() allocates and initializes a B<DH> structure.
DH_free() frees the B<DH> structure and its components. The values are
erased before the memory is returned to the system.
If B<dh> is NULL nothing is done.
=head1 RETURN VALUES
If the allocation fails, DH_new() returns B<NULL> and sets an error
code that can be obtained by L<ERR_get_error(3)>. Otherwise it returns
a pointer to the newly allocated structure.
DH_free() returns no value.
=head1 SEE ALSO
L<DH_new(3)>, L<ERR_get_error(3)>,
L<DH_generate_parameters(3)>,
L<DH_generate_key(3)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

39
doc/man3/DH_new_by_nid.pod Normal file
View File

@@ -0,0 +1,39 @@
=pod
=head1 NAME
DH_new_by_nid, DH_get_nid - get or find DH named parameters
=head1 SYNOPSIS
#include <openssl/dh.h>
DH *DH_new_by_nid(int nid);
int *DH_get_nid(const DH *dh);
=head1 DESCRIPTION
DH_new_by_nid() creates and returns a DH structure containing named parameters
B<nid>. Currently B<nid> must be B<NID_ffdhe2048>, B<NID_ffdhe3072>,
B<NID_ffdhe4096>, B<NID_ffdhe6144> or B<NID_ffdhe8192>.
DH_get_nid() determines if the parameters contained in B<dh> match
any named set. It returns the NID corresponding to the matching parameters or
B<NID_undef> if there is no match.
=head1 RETURN VALUES
DH_new_by_nid() returns a set of DH parameters or B<NULL> if an error occurred.
DH_get_nid() returns the NID of the matching set of parameters or
B<NID_undef> if there is no match.
=head1 COPYRIGHT
Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

88
doc/man3/DH_set_method.pod Normal file
View File

@@ -0,0 +1,88 @@
=pod
=head1 NAME
DH_set_default_method, DH_get_default_method,
DH_set_method, DH_new_method, DH_OpenSSL - select DH method
=head1 SYNOPSIS
#include <openssl/dh.h>
void DH_set_default_method(const DH_METHOD *meth);
const DH_METHOD *DH_get_default_method(void);
int DH_set_method(DH *dh, const DH_METHOD *meth);
DH *DH_new_method(ENGINE *engine);
const DH_METHOD *DH_OpenSSL(void);
=head1 DESCRIPTION
A B<DH_METHOD> specifies the functions that OpenSSL uses for Diffie-Hellman
operations. By modifying the method, alternative implementations
such as hardware accelerators may be used. IMPORTANT: See the NOTES section for
important information about how these DH API functions are affected by the use
of B<ENGINE> API calls.
Initially, the default DH_METHOD is the OpenSSL internal implementation, as
returned by DH_OpenSSL().
DH_set_default_method() makes B<meth> the default method for all DH
structures created later.
B<NB>: This is true only whilst no ENGINE has been set
as a default for DH, so this function is no longer recommended.
This function is not thread-safe and should not be called at the same time
as other OpenSSL functions.
DH_get_default_method() returns a pointer to the current default DH_METHOD.
However, the meaningfulness of this result is dependent on whether the ENGINE
API is being used, so this function is no longer recommended.
DH_set_method() selects B<meth> to perform all operations using the key B<dh>.
This will replace the DH_METHOD used by the DH key and if the previous method
was supplied by an ENGINE, the handle to that ENGINE will be released during the
change. It is possible to have DH keys that only work with certain DH_METHOD
implementations (eg. from an ENGINE module that supports embedded
hardware-protected keys), and in such cases attempting to change the DH_METHOD
for the key can have unexpected results.
DH_new_method() allocates and initializes a DH structure so that B<engine> will
be used for the DH operations. If B<engine> is NULL, the default ENGINE for DH
operations is used, and if no default ENGINE is set, the DH_METHOD controlled by
DH_set_default_method() is used.
A new DH_METHOD object may be constructed using DH_meth_new() (see
L<DH_meth_new(3)>).
=head1 RETURN VALUES
DH_OpenSSL() and DH_get_default_method() return pointers to the respective
B<DH_METHOD>s.
DH_set_default_method() returns no value.
DH_set_method() returns non-zero if the provided B<meth> was successfully set as
the method for B<dh> (including unloading the ENGINE handle if the previous
method was supplied by an ENGINE).
DH_new_method() returns NULL and sets an error code that can be obtained by
L<ERR_get_error(3)> if the allocation fails. Otherwise it
returns a pointer to the newly allocated structure.
=head1 SEE ALSO
L<DH_new(3)>, L<DH_new(3)>, L<DH_meth_new(3)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

57
doc/man3/DH_size.pod Normal file
View File

@@ -0,0 +1,57 @@
=pod
=head1 NAME
DH_size, DH_bits, DH_security_bits - get Diffie-Hellman prime size and
security bits
=head1 SYNOPSIS
#include <openssl/dh.h>
int DH_size(const DH *dh);
int DH_bits(const DH *dh);
int DH_security_bits(const DH *dh);
=head1 DESCRIPTION
DH_size() returns the Diffie-Hellman prime size in bytes. It can be used
to determine how much memory must be allocated for the shared secret
computed by L<DH_compute_key(3)>.
DH_bits() returns the number of significant bits.
B<dh> and B<dh-E<gt>p> must not be B<NULL>.
DH_security_bits() returns the number of security bits of the given B<dh>
key. See L<BN_security_bits(3)>.
=head1 RETURN VALUES
DH_size() returns the prime size of Diffie-Hellman in bytes.
DH_bits() returns the number of bits in the key.
DH_security_bits() returns the number of security bits.
=head1 SEE ALSO
L<DH_new(3)>, L<DH_generate_key(3)>,
L<BN_num_bits(3)>
=head1 HISTORY
DH_bits() was added in OpenSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

58
doc/man3/DSA_SIG_new.pod Normal file
View File

@@ -0,0 +1,58 @@
=pod
=head1 NAME
DSA_SIG_get0, DSA_SIG_set0,
DSA_SIG_new, DSA_SIG_free - allocate and free DSA signature objects
=head1 SYNOPSIS
#include <openssl/dsa.h>
DSA_SIG *DSA_SIG_new(void);
void DSA_SIG_free(DSA_SIG *a);
void DSA_SIG_get0(const DSA_SIG *sig, const BIGNUM **pr, const BIGNUM **ps);
int DSA_SIG_set0(DSA_SIG *sig, BIGNUM *r, BIGNUM *s);
=head1 DESCRIPTION
DSA_SIG_new() allocates an empty B<DSA_SIG> structure.
DSA_SIG_free() frees the B<DSA_SIG> structure and its components. The
values are erased before the memory is returned to the system.
DSA_SIG_get0() returns internal pointers to the B<r> and B<s> values contained
in B<sig>.
The B<r> and B<s> values can be set by calling DSA_SIG_set0() and passing the
new values for B<r> and B<s> as parameters to the function. Calling this
function transfers the memory management of the values to the DSA_SIG object,
and therefore the values that have been passed in should not be freed directly
after this function has been called.
=head1 RETURN VALUES
If the allocation fails, DSA_SIG_new() returns B<NULL> and sets an
error code that can be obtained by
L<ERR_get_error(3)>. Otherwise it returns a pointer
to the newly allocated structure.
DSA_SIG_free() returns no value.
DSA_SIG_set0() returns 1 on success or 0 on failure.
=head1 SEE ALSO
L<DSA_new(3)>, L<ERR_get_error(3)>,
L<DSA_do_sign(3)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

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