system/freebsd-src
system/freebsd-src
1
0
Fork 0
mirror of https://github.com/freebsd/freebsd-src synced 2024-10-06 16:40:47 +00:00
Code Issues Packages Projects Releases Wiki Activity

Regen manual pages.

Browse source 
Note the manual pages are not automatically generated for now.
This commit is contained in:
Jung-uk Kim 2018-09-13 23:14:57 +00:00
parent 9b21da0ecb
commit 54967a4e95
Notes: svn2git 2020-12-20 02:59:44 +00:00 
svn path=/projects/openssl111/; revision=338671
545 changed files with 58950 additions and 18567 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3394
secure/lib/libcrypto/Makefile.man
View file

File diff suppressed because it is too large Load diff

276
secure/lib/libcrypto/man/ADMISSIONS.3 Normal file
View file

@ -0,0 +1,276 @@
.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "ADMISSIONS 3"
.TH ADMISSIONS 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "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
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 5
\& 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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \fB\s-1PROFESSION_INFOS\s0\fR, \fB\s-1ADMISSION_SYNTAX\s0\fR, \fB\s-1ADMISSIONS\s0\fR, and
\&\fB\s-1PROFESSION_INFO\s0\fR types are opaque structures representing the
analogous types defined in the Common \s-1PKI\s0 Specification published
by <https://www.t7ev.org>.
Knowledge of those structures and their semantics is assumed.
.PP
The conventional routines to convert between \s-1DER\s0 and the local format
are described in \fId2i_X509\fR\|(3).
The conventional routines to allocate and free the types are defined
in \fIX509_dup\fR\|(3).
.PP
The \fB\s-1PROFESSION_INFOS\s0\fR type is a stack of \fB\s-1PROFESSION_INFO\s0\fR; see
\&\s-1\fIDEFINE_STACK_OF\s0\fR\|(3) for details.
.PP
The \fB\s-1NAMING_AUTHORITY\s0\fR type has an authority \s-1ID\s0 and \s-1URL,\s0 and text fields.
The \fINAMING_AUTHORITY_get0_authorityId()\fR,
\&\fINAMING_AUTHORITY_get0_get0_authorityURL()\fR, and
\&\fINAMING_AUTHORITY_get0_get0_authorityText()\fR, functions return pointers
to those values within the object.
The \fINAMING_AUTHORITY_set0_authorityId()\fR,
\&\fINAMING_AUTHORITY_set0_get0_authorityURL()\fR, and
\&\fINAMING_AUTHORITY_set0_get0_authorityText()\fR,
functions free any existing value and set the pointer to the specified value.
.PP
The \fB\s-1ADMISSION_SYNTAX\s0\fR type has an authority name and a stack of
\&\fB\s-1ADMISSION\s0\fR objects.
The \fIADMISSION_SYNTAX_get0_admissionAuthority()\fR
and \fIADMISSION_SYNTAX_get0_contentsOfAdmissions()\fR functions return pointers
to those values within the object.
The
\&\fIADMISSION_SYNTAX_set0_admissionAuthority()\fR and
\&\fIADMISSION_SYNTAX_set0_contentsOfAdmissions()\fR
functions free any existing value and set the pointer to the specified value.
.PP
The \fB\s-1ADMISSION\s0\fR type has an authority name, authority object, and a
stack of \fB\s-1PROFSSION_INFO\s0\fR items.
The \fIADMISSIONS_get0_admissionAuthority()\fR, \fIADMISSIONS_get0_namingAuthority()\fR,
and \fIADMISSIONS_get0_professionInfos()\fR
functions return pointers to those values within the object.
The
\&\fIADMISSIONS_set0_admissionAuthority()\fR,
\&\fIADMISSIONS_set0_namingAuthority()\fR, and
\&\fIADMISSIONS_set0_professionInfos()\fR
functions free any existing value and set the pointer to the specified value.
.PP
The \fB\s-1PROFESSION_INFO\s0\fR type has a name authority, stacks of
profession Items and OIDs, a registration number, and additional
profession info.
The functions \fIPROFESSION_INFO_get0_addProfessionInfo()\fR,
\&\fIPROFESSION_INFO_get0_namingAuthority()\fR, \fIPROFESSION_INFO_get0_professionItems()\fR,
\&\fIPROFESSION_INFO_get0_professionOIDs()\fR, and
\&\fIPROFESSION_INFO_get0_registrationNumber()\fR
functions return pointers to those values within the object.
The
\&\fIPROFESSION_INFO_set0_addProfessionInfo()\fR,
\&\fIPROFESSION_INFO_set0_namingAuthority()\fR,
\&\fIPROFESSION_INFO_set0_professionItems()\fR,
\&\fIPROFESSION_INFO_set0_professionOIDs()\fR, and
\&\fIPROFESSION_INFO_set0_registrationNumber()\fR
functions free any existing value and set the pointer to the specified value.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
Described above.
Note that all of the \fIget0\fR functions return a pointer to the internal data
structure and must not be freed.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIX509_dup\fR\|(3),
\&\fId2i_X509\fR\|(3),
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2017\-2018 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

256
secure/lib/libcrypto/man/ASN1_INTEGER_get_int64.3 Normal file
View file

@ -0,0 +1,256 @@
.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "ASN1_INTEGER_GET_INT64 3"
.TH ASN1_INTEGER_GET_INT64 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "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
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
These functions convert to and from \fB\s-1ASN1_INTEGER\s0\fR and \fB\s-1ASN1_ENUMERATED\s0\fR
structures.
.PP
\&\fIASN1_INTEGER_get_int64()\fR converts an \fB\s-1ASN1_INTEGER\s0\fR into an \fBint64_t\fR type
If successful it returns 1 and sets \fB*pr\fR to the value of \fBa\fR. If it fails
(due to invalid type or the value being too big to fit into an \fBint64_t\fR type)
it returns 0.
.PP
\&\fIASN1_INTEGER_get_uint64()\fR is similar to \fIASN1_INTEGER_get_int64_t()\fR except it
converts to a \fBuint64_t\fR type and an error is returned if the passed integer
is negative.
.PP
\&\fIASN1_INTEGER_get()\fR also returns the value of \fBa\fR but it returns 0 if \fBa\fR is
\&\s-1NULL\s0 and \-1 on error (which is ambiguous because \-1 is a legitimate value for
an \fB\s-1ASN1_INTEGER\s0\fR). New applications should use \fIASN1_INTEGER_get_int64()\fR
instead.
.PP
\&\fIASN1_INTEGER_set_int64()\fR sets the value of \fB\s-1ASN1_INTEGER\s0\fR \fBa\fR to the
\&\fBint64_t\fR value \fBr\fR.
.PP
\&\fIASN1_INTEGER_set_uint64()\fR sets the value of \fB\s-1ASN1_INTEGER\s0\fR \fBa\fR to the
\&\fBuint64_t\fR value \fBr\fR.
.PP
\&\fIASN1_INTEGER_set()\fR sets the value of \fB\s-1ASN1_INTEGER\s0\fR \fBa\fR to the \fBlong\fR value
\&\fBv\fR.
.PP
\&\fIBN_to_ASN1_INTEGER()\fR converts \fB\s-1BIGNUM\s0\fR \fBbn\fR to an \fB\s-1ASN1_INTEGER\s0\fR. If \fBai\fR
is \s-1NULL\s0 a new \fB\s-1ASN1_INTEGER\s0\fR structure is returned. If \fBai\fR is not \s-1NULL\s0 then
the existing structure will be used instead.
.PP
\&\fIASN1_INTEGER_to_BN()\fR converts \s-1ASN1_INTEGER\s0 \fBai\fR into a \fB\s-1BIGNUM\s0\fR. If \fBbn\fR is
\&\s-1NULL\s0 a new \fB\s-1BIGNUM\s0\fR structure is returned. If \fBbn\fR is not \s-1NULL\s0 then the
existing structure will be used instead.
.PP
\&\fIASN1_ENUMERATED_get_int64()\fR, \fIASN1_ENUMERATED_set_int64()\fR,
\&\fIASN1_ENUMERATED_set()\fR, \fIBN_to_ASN1_ENUMERATED()\fR and \fIASN1_ENUMERATED_to_BN()\fR
behave in an identical way to their \s-1ASN1_INTEGER\s0 counterparts except they
operate on an \fB\s-1ASN1_ENUMERATED\s0\fR value.
.PP
\&\fIASN1_ENUMERATED_get()\fR returns the value of \fBa\fR in a similar way to
\&\fIASN1_INTEGER_get()\fR but it returns \fB0xffffffffL\fR if the value of \fBa\fR will not
fit in a long type. New applications should use \fIASN1_ENUMERATED_get_int64()\fR
instead.
.SH "NOTES"
.IX Header "NOTES"
In general an \fB\s-1ASN1_INTEGER\s0\fR or \fB\s-1ASN1_ENUMERATED\s0\fR type can contain an
integer of almost arbitrary size and so cannot always be represented by a C
\&\fBint64_t\fR 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.
.SH "BUGS"
.IX Header "BUGS"
The ambiguous return values of \fIASN1_INTEGER_get()\fR and \fIASN1_ENUMERATED_get()\fR
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.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fIASN1_INTEGER_set_int64()\fR, \fIASN1_INTEGER_set()\fR, \fIASN1_ENUMERATED_set_int64()\fR and
\&\fIASN1_ENUMERATED_set()\fR return 1 for success and 0 for failure. They will only
fail if a memory allocation error occurs.
.PP
\&\fIASN1_INTEGER_get_int64()\fR and \fIASN1_ENUMERATED_get_int64()\fR 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 \fBint64_t\fR type.
.PP
\&\fIBN_to_ASN1_INTEGER()\fR and \fIBN_to_ASN1_ENUMERATED()\fR return an \fB\s-1ASN1_INTEGER\s0\fR or
\&\fB\s-1ASN1_ENUMERATED\s0\fR structure respectively or \s-1NULL\s0 if an error occurs. They will
only fail due to a memory allocation error.
.PP
\&\fIASN1_INTEGER_to_BN()\fR and \fIASN1_ENUMERATED_to_BN()\fR return a \fB\s-1BIGNUM\s0\fR structure
of \s-1NULL\s0 if an error occurs. They can fail if the passed type is incorrect
(due to programming error) or due to a memory allocation failure.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIERR_get_error\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fIASN1_INTEGER_set_int64()\fR, \fIASN1_INTEGER_get_int64()\fR,
\&\fIASN1_ENUMERATED_set_int64()\fR and \fIASN1_ENUMERATED_get_int64()\fR
were added to OpenSSL 1.1.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2015\-2018 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

167
secure/lib/libcrypto/man/ASN1_ITEM_lookup.3 Normal file
View file

@ -0,0 +1,167 @@
.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "ASN1_ITEM_LOOKUP 3"
.TH ASN1_ITEM_LOOKUP 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
ASN1_ITEM_lookup, ASN1_ITEM_get \- lookup ASN.1 structures
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/asn1.h>
\&
\& const ASN1_ITEM *ASN1_ITEM_lookup(const char *name);
\& const ASN1_ITEM *ASN1_ITEM_get(size_t i);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fIASN1_ITEM_lookup()\fR returns the \fB\s-1ASN1_ITEM\s0 name\fR.
.PP
\&\fIASN1_ITEM_get()\fR returns the \fB\s-1ASN1_ITEM\s0\fR with index \fBi\fR. This function
returns \fB\s-1NULL\s0\fR if the index \fBi\fR is out of range.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fIASN1_ITEM_lookup()\fR and \fIASN1_ITEM_get()\fR return a valid \fB\s-1ASN1_ITEM\s0\fR structure
or \fB\s-1NULL\s0\fR if an error occurred.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIERR_get_error\fR\|(3)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

20
secure/lib/libcrypto/man/ASN1_OBJECT_new.3
View file

@ -128,14 +128,14 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "ASN1_OBJECT_new 3"
.TH ASN1_OBJECT_new 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "ASN1_OBJECT_NEW 3"
.TH ASN1_OBJECT_NEW 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
ASN1_OBJECT_new, ASN1_OBJECT_free, \- object allocation functions
ASN1_OBJECT_new, ASN1_OBJECT_free \- object allocation functions
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
@ -149,9 +149,10 @@ ASN1_OBJECT_new, ASN1_OBJECT_free, \- object allocation functions
The \s-1ASN1_OBJECT\s0 allocation routines, allocate and free an
\&\s-1ASN1_OBJECT\s0 structure, which represents an \s-1ASN1 OBJECT IDENTIFIER.\s0
.PP
\&\fIASN1_OBJECT_new()\fR allocates and initializes a \s-1ASN1_OBJECT\s0 structure.
\&\fIASN1_OBJECT_new()\fR allocates and initializes an \s-1ASN1_OBJECT\s0 structure.
.PP
\&\fIASN1_OBJECT_free()\fR frees up the \fB\s-1ASN1_OBJECT\s0\fR structure \fBa\fR.
If \fBa\fR is \s-1NULL,\s0 nothing is done.
.SH "NOTES"
.IX Header "NOTES"
Although \fIASN1_OBJECT_new()\fR allocates a new \s-1ASN1_OBJECT\s0 structure it
@ -167,6 +168,11 @@ Otherwise it returns a pointer to the newly allocated structure.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIERR_get_error\fR\|(3), \fId2i_ASN1_OBJECT\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fIASN1_OBJECT_new()\fR and \fIASN1_OBJECT_free()\fR are available in all versions of SSLeay and OpenSSL.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2002\-2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

191
secure/lib/libcrypto/man/ASN1_STRING_TABLE_add.3 Normal file
View file

@ -0,0 +1,191 @@
.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "ASN1_STRING_TABLE_ADD 3"
.TH ASN1_STRING_TABLE_ADD 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
ASN1_STRING_TABLE, ASN1_STRING_TABLE_add, ASN1_STRING_TABLE_get, ASN1_STRING_TABLE_cleanup \- ASN1_STRING_TABLE manipulation functions
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
.SS "Types"
.IX Subsection "Types"
\&\fB\s-1ASN1_STRING_TABLE\s0\fR is a table which holds string information
(basically minimum size, maximum size, type and etc) for a \s-1NID\s0 object.
.SS "Functions"
.IX Subsection "Functions"
\&\fIASN1_STRING_TABLE_add()\fR adds a new \fB\s-1ASN1_STRING_TABLE\s0\fR item into the
local \s-1ASN1\s0 string table based on the \fBnid\fR along with other parameters.
.PP
If the item is already in the table, fields of \fB\s-1ASN1_STRING_TABLE\s0\fR are
updated (depending on the values of those parameters, e.g., \fBminsize\fR
and \fBmaxsize\fR >= 0, \fBmask\fR and \fBflags\fR != 0). If the \fBnid\fR is standard,
a copy of the standard \fB\s-1ASN1_STRING_TABLE\s0\fR is created and updated with
other parameters.
.PP
\&\fIASN1_STRING_TABLE_get()\fR searches for an \fB\s-1ASN1_STRING_TABLE\s0\fR item based
on \fBnid\fR. It will search the local table first, then the standard one.
.PP
\&\fIASN1_STRING_TABLE_cleanup()\fR frees all \fB\s-1ASN1_STRING_TABLE\s0\fR items added
by \fIASN1_STRING_TABLE_add()\fR.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fIASN1_STRING_TABLE_add()\fR returns 1 on success, 0 if an error occurred.
.PP
\&\fIASN1_STRING_TABLE_get()\fR returns a valid \fB\s-1ASN1_STRING_TABLE\s0\fR structure
or \fB\s-1NULL\s0\fR if nothing is found.
.PP
\&\fIASN1_STRING_TABLE_cleanup()\fR does not return a value.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIERR_get_error\fR\|(3)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

50
secure/lib/libcrypto/man/ASN1_STRING_length.3
View file

@ -128,22 +128,21 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "ASN1_STRING_length 3"
.TH ASN1_STRING_length 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "ASN1_STRING_LENGTH 3"
.TH ASN1_STRING_LENGTH 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
ASN1_STRING_dup, ASN1_STRING_cmp, ASN1_STRING_set, ASN1_STRING_length,
ASN1_STRING_length_set, ASN1_STRING_type, ASN1_STRING_data, ASN1_STRING_to_UTF8 \-
ASN1_STRING utility functions
ASN1_STRING_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
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #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);
@ -152,9 +151,9 @@ ASN1_STRING utility functions
\&
\& int ASN1_STRING_set(ASN1_STRING *str, const void *data, int len);
\&
\& int ASN1_STRING_type(ASN1_STRING *x);
\& int ASN1_STRING_type(const ASN1_STRING *x);
\&
\& int ASN1_STRING_to_UTF8(unsigned char **out, ASN1_STRING *in);
\& int ASN1_STRING_to_UTF8(unsigned char **out, const ASN1_STRING *in);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
@ -162,10 +161,14 @@ These functions allow an \fB\s-1ASN1_STRING\s0\fR structure to be manipulated.
.PP
\&\fIASN1_STRING_length()\fR returns the length of the content of \fBx\fR.
.PP
\&\fIASN1_STRING_data()\fR returns an internal pointer to the data of \fBx\fR.
\&\fIASN1_STRING_get0_data()\fR returns an internal pointer to the data of \fBx\fR.
Since this is an internal pointer it should \fBnot\fR be freed or
modified in any way.
.PP
\&\fIASN1_STRING_data()\fR is similar to \fIASN1_STRING_get0_data()\fR except the
returned value is not constant. This function is deprecated:
applications should use \fIASN1_STRING_get0_data()\fR instead.
.PP
\&\fIASN1_STRING_dup()\fR returns a copy of the structure \fBa\fR.
.PP
\&\fIASN1_STRING_cmp()\fR compares \fBa\fR and \fBb\fR returning 0 if the two
@ -181,11 +184,11 @@ such as \fBV_ASN1_OCTET_STRING\fR.
\&\fIASN1_STRING_to_UTF8()\fR converts the string \fBin\fR to \s-1UTF8\s0 format, the
converted data is allocated in a buffer in \fB*out\fR. The length of
\&\fBout\fR is returned or a negative error code. The buffer \fB*out\fR
should be free using \fIOPENSSL_free()\fR.
should be freed using \fIOPENSSL_free()\fR.
.SH "NOTES"
.IX Header "NOTES"
Almost all \s-1ASN1\s0 types in OpenSSL are represented as an \fB\s-1ASN1_STRING\s0\fR
structure. Other types such as \fB\s-1ASN1_OCTET_STRING\s0\fR are simply typedefed
structure. Other types such as \fB\s-1ASN1_OCTET_STRING\s0\fR are simply typedef'ed
to \fB\s-1ASN1_STRING\s0\fR and the functions call the \fB\s-1ASN1_STRING\s0\fR equivalents.
\&\fB\s-1ASN1_STRING\s0\fR is also used for some \fB\s-1CHOICE\s0\fR types which consist
entirely of primitive string types such as \fBDirectoryString\fR and
@ -205,8 +208,31 @@ Similar care should be take to ensure the data is in the correct format
when calling \fIASN1_STRING_set()\fR.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fIASN1_STRING_length()\fR returns the length of the content of \fBx\fR.
.PP
\&\fIASN1_STRING_get0_data()\fR and \fIASN1_STRING_data()\fR return an internal pointer to
the data of \fBx\fR.
.PP
\&\fIASN1_STRING_dup()\fR returns a valid \fB\s-1ASN1_STRING\s0\fR structure or \fB\s-1NULL\s0\fR if an
error occurred.
.PP
\&\fIASN1_STRING_cmp()\fR returns an integer greater than, equal to, or less than 0,
according to whether \fBa\fR is greater than, equal to, or less than \fBb\fR.
.PP
\&\fIASN1_STRING_set()\fR returns 1 on success or 0 on error.
.PP
\&\fIASN1_STRING_type()\fR returns the type of \fBx\fR.
.PP
\&\fIASN1_STRING_to_UTF8()\fR returns the number of bytes in output string \fBout\fR or a
negative value if an error occurred.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIERR_get_error\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2002\-2018 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

19
secure/lib/libcrypto/man/ASN1_STRING_new.3
View file

@ -128,15 +128,14 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "ASN1_STRING_new 3"
.TH ASN1_STRING_new 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "ASN1_STRING_NEW 3"
.TH ASN1_STRING_NEW 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
ASN1_STRING_new, ASN1_STRING_type_new, ASN1_STRING_free \-
ASN1_STRING allocation functions
ASN1_STRING_new, ASN1_STRING_type_new, ASN1_STRING_free \- ASN1_STRING allocation functions
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
@ -155,6 +154,7 @@ is undefined.
type \fBtype\fR.
.PP
\&\fIASN1_STRING_free()\fR frees up \fBa\fR.
If \fBa\fR is \s-1NULL\s0 nothing is done.
.SH "NOTES"
.IX Header "NOTES"
Other string types call the \fB\s-1ASN1_STRING\s0\fR functions. For example
@ -168,6 +168,11 @@ Other string types call the \fB\s-1ASN1_STRING\s0\fR functions. For example
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIERR_get_error\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\s-1TBA\s0
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2002\-2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

42
secure/lib/libcrypto/man/ASN1_STRING_print_ex.3
View file

@ -128,22 +128,24 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "ASN1_STRING_print_ex 3"
.TH ASN1_STRING_print_ex 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "ASN1_STRING_PRINT_EX 3"
.TH ASN1_STRING_PRINT_EX 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
ASN1_STRING_print_ex, ASN1_STRING_print_ex_fp, ASN1_STRING_print \- ASN1_STRING output routines.
ASN1_tag2str, ASN1_STRING_print_ex, ASN1_STRING_print_ex_fp, ASN1_STRING_print \&\- ASN1_STRING output routines
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/asn1.h>
\&
\& int ASN1_STRING_print_ex(BIO *out, ASN1_STRING *str, unsigned long flags);
\& int ASN1_STRING_print_ex_fp(FILE *fp, ASN1_STRING *str, unsigned long flags);
\& int ASN1_STRING_print(BIO *out, ASN1_STRING *str);
\& int ASN1_STRING_print_ex(BIO *out, const ASN1_STRING *str, unsigned long flags);
\& int ASN1_STRING_print_ex_fp(FILE *fp, const ASN1_STRING *str, unsigned long flags);
\& int ASN1_STRING_print(BIO *out, const ASN1_STRING *str);
\&
\& const char *ASN1_tag2str(int tag);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
@ -157,11 +159,14 @@ to \fBfp\fR instead.
\&\fIASN1_STRING_print()\fR prints \fBstr\fR to \fBout\fR but using a different format to
\&\fIASN1_STRING_print_ex()\fR. It replaces unprintable characters (other than \s-1CR, LF\s0)
with '.'.
.PP
\&\fIASN1_tag2str()\fR returns a human-readable name of the specified \s-1ASN.1\s0 \fBtag\fR.
.SH "NOTES"
.IX Header "NOTES"
\&\fIASN1_STRING_print()\fR is a legacy function which should be avoided in new applications.
\&\fIASN1_STRING_print()\fR is a deprecated function which should be avoided; use
\&\fIASN1_STRING_print_ex()\fR instead.
.PP
Although there are a large number of options frequently \fB\s-1ASN1_STRFLGS_RFC2253\s0\fR is
Although there are a large number of options frequently \fB\s-1ASN1_STRFLGS_RFC2253\s0\fR is
suitable, or on \s-1UTF8\s0 terminals \fB\s-1ASN1_STRFLGS_RFC2253 &\s0 ~ASN1_STRFLGS_ESC_MSB\fR.
.PP
The complete set of supported options for \fBflags\fR is listed below.
@ -206,7 +211,7 @@ Normally non character string types (such as \s-1OCTET STRING\s0) are assumed to
one byte per character, if \fB\s-1ASN1_STRFLGS_DUMP_UNKNOWN\s0\fR is set then they will
be dumped instead.
.PP
When a type is dumped normally just the content octets are printed, if
When a type is dumped normally just the content octets are printed, if
\&\fB\s-1ASN1_STRFLGS_DUMP_DER\s0\fR is set then the complete encoding is dumped
instead (including tag and length octets).
.PP
@ -214,10 +219,23 @@ instead (including tag and length octets).
equivalent to:
\s-1ASN1_STRFLGS_ESC_2253\s0 | \s-1ASN1_STRFLGS_ESC_CTRL\s0 | \s-1ASN1_STRFLGS_ESC_MSB\s0 |
\s-1ASN1_STRFLGS_UTF8_CONVERT\s0 | \s-1ASN1_STRFLGS_DUMP_UNKNOWN ASN1_STRFLGS_DUMP_DER\s0
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fIASN1_STRING_print_ex()\fR and \fIASN1_STRING_print_ex_fp()\fR return the number of
characters written or \-1 if an error occurred.
.PP
\&\fIASN1_STRING_print()\fR returns 1 on success or 0 on error.
.PP
\&\fIASN1_tag2str()\fR returns a human-readable name of the specified \s-1ASN.1\s0 \fBtag\fR.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIX509_NAME_print_ex\fR\|(3),
\&\fIASN1_tag2str\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\s-1TBA\s0
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2002\-2018 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

200
secure/lib/libcrypto/man/ASN1_TIME_set.3
View file

@ -128,52 +128,110 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "ASN1_TIME_set 3"
.TH ASN1_TIME_set 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "ASN1_TIME_SET 3"
.TH ASN1_TIME_SET 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
ASN1_TIME_set, ASN1_TIME_adj, ASN1_TIME_check, ASN1_TIME_set_string,
ASN1_TIME_print, ASN1_TIME_diff \- ASN.1 Time functions.
ASN1_TIME_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
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 6
.Vb 4
\& ASN1_TIME *ASN1_TIME_set(ASN1_TIME *s, time_t t);
\& ASN1_TIME *ASN1_TIME_adj(ASN1_TIME *s, time_t t,
\& int offset_day, long offset_sec);
\& int ASN1_TIME_set_string(ASN1_TIME *s, const char *str);
\& int ASN1_TIME_check(const ASN1_TIME *t);
\& int ASN1_TIME_print(BIO *b, const ASN1_TIME *s);
\& ASN1_UTCTIME *ASN1_UTCTIME_set(ASN1_UTCTIME *s, time_t t);
\& ASN1_GENERALIZEDTIME *ASN1_GENERALIZEDTIME_set(ASN1_GENERALIZEDTIME *s,
\& time_t t);
\&
\& int ASN1_TIME_diff(int *pday, int *psec,
\& const ASN1_TIME *from, const ASN1_TIME *to);
\& 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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The function \fIASN1_TIME_set()\fR sets the \s-1ASN1_TIME\s0 structure \fBs\fR to the
time represented by the time_t value \fBt\fR. If \fBs\fR is \s-1NULL\s0 a new \s-1ASN1_TIME\s0
structure is allocated and returned.
The \fIASN1_TIME_set()\fR, \fIASN1_UTCTIME_set()\fR and \fIASN1_GENERALIZEDTIME_set()\fR
functions set the structure \fBs\fR to the time represented by the time_t
value \fBt\fR. If \fBs\fR is \s-1NULL\s0 a new time structure is allocated and returned.
.PP
\&\fIASN1_TIME_adj()\fR sets the \s-1ASN1_TIME\s0 structure \fBs\fR to the time represented
The \fIASN1_TIME_adj()\fR, \fIASN1_UTCTIME_adj()\fR and \fIASN1_GENERALIZEDTIME_adj()\fR
functions set the time structure \fBs\fR to the time represented
by the time \fBoffset_day\fR and \fBoffset_sec\fR after the time_t value \fBt\fR.
The values of \fBoffset_day\fR or \fBoffset_sec\fR can be negative to set a
time before \fBt\fR. The \fBoffset_sec\fR value can also exceed the number of
seconds in a day. If \fBs\fR is \s-1NULL\s0 a new \s-1ASN1_TIME\s0 structure is allocated
seconds in a day. If \fBs\fR is \s-1NULL\s0 a new structure is allocated
and returned.
.PP
\&\fIASN1_TIME_set_string()\fR sets \s-1ASN1_TIME\s0 structure \fBs\fR to the time
represented by string \fBstr\fR which must be in appropriate \s-1ASN.1\s0 time
format (for example \s-1YYMMDDHHMMSSZ\s0 or \s-1YYYYMMDDHHMMSSZ\s0).
The \fIASN1_TIME_set_string()\fR, \fIASN1_UTCTIME_set_string()\fR and
\&\fIASN1_GENERALIZEDTIME_set_string()\fR functions set the time structure \fBs\fR
to the time represented by string \fBstr\fR which must be in appropriate \s-1ASN.1\s0
time format (for example \s-1YYMMDDHHMMSSZ\s0 or \s-1YYYYMMDDHHMMSSZ\s0). If \fBs\fR is \s-1NULL\s0
this function performs a format check on \fBstr\fR only. The string \fBstr\fR
is copied into \fBs\fR.
.PP
\&\fIASN1_TIME_check()\fR checks the syntax of \s-1ASN1_TIME\s0 structure \fBs\fR.
\&\fIASN1_TIME_set_string_X509()\fR sets \s-1ASN1_TIME\s0 structure \fBs\fR to the time
represented by string \fBstr\fR which must be in appropriate time format
that \s-1RFC 5280\s0 requires, which means it only allows \s-1YYMMDDHHMMSSZ\s0 and
\&\s-1YYYYMMDDHHMMSSZ\s0 (leap second is rejected), all other \s-1ASN.1\s0 time format
are not allowed. If \fBs\fR is \s-1NULL\s0 this function performs a format check
on \fBstr\fR only.
.PP
\&\fIASN1_TIME_print()\fR prints out the time \fBs\fR to \s-1BIO\s0 \fBb\fR in human readable
The \fIASN1_TIME_normalize()\fR function converts an \s-1ASN1_GENERALIZEDTIME\s0 or
\&\s-1ASN1_UTCTIME\s0 into a time value that can be used in a certificate. It
should be used after the \fIASN1_TIME_set_string()\fR functions and before
\&\fIASN1_TIME_print()\fR functions to get consistent (i.e. \s-1GMT\s0) results.
.PP
The \fIASN1_TIME_check()\fR, \fIASN1_UTCTIME_check()\fR and \fIASN1_GENERALIZEDTIME_check()\fR
functions check the syntax of the time structure \fBs\fR.
.PP
The \fIASN1_TIME_print()\fR, \fIASN1_UTCTIME_print()\fR and \fIASN1_GENERALIZEDTIME_print()\fR
functions print the time structure \fBs\fR to \s-1BIO\s0 \fBb\fR in human readable
format. It will be of the format \s-1MMM DD HH:MM:SS YYYY\s0 [\s-1GMT\s0], for example
\&\*(L"Feb 3 00:55:52 2015 \s-1GMT\*(R"\s0 it does not include a newline. If the time
structure has invalid format it prints out \*(L"Bad time value\*(R" and returns
an error.
an error. The output for generalized time may include a fractional part
following the second.
.PP
\&\fIASN1_TIME_to_tm()\fR converts the time \fBs\fR to the standard \fBtm\fR structure.
If \fBs\fR is \s-1NULL,\s0 then the current time is converted. The output time is \s-1GMT.\s0
The \fBtm_sec\fR, \fBtm_min\fR, \fBtm_hour\fR, \fBtm_mday\fR, \fBtm_wday\fR, \fBtm_yday\fR,
\&\fBtm_mon\fR and \fBtm_year\fR fields of \fBtm\fR structure are set to proper values,
whereas all other fields are set to 0. If \fBtm\fR is \s-1NULL\s0 this function performs
a format check on \fBs\fR only. If \fBs\fR is in Generalized format with fractional
seconds, e.g. \s-1YYYYMMDDHHMMSS.SSSZ,\s0 the fractional seconds will be lost while
converting \fBs\fR to \fBtm\fR structure.
.PP
\&\fIASN1_TIME_diff()\fR sets \fB*pday\fR and \fB*psec\fR to the time difference between
\&\fBfrom\fR and \fBto\fR. If \fBto\fR represents a time later than \fBfrom\fR then
@ -184,6 +242,16 @@ represent the same time then \fB*pday\fR and \fB*psec\fR will both be zero.
If both \fB*pday\fR and \fB*psec\fR are non-zero they will always have the same
sign. The value of \fB*psec\fR will always be less than the number of seconds
in a day. If \fBfrom\fR or \fBto\fR is \s-1NULL\s0 the current time is used.
.PP
The \fIASN1_TIME_cmp_time_t()\fR and \fIASN1_UTCTIME_cmp_time_t()\fR functions compare
the two times represented by the time structure \fBs\fR and the time_t \fBt\fR.
.PP
The \fIASN1_TIME_compare()\fR function compares the two times represented by the
time structures \fBa\fR and \fBb\fR.
.PP
The \fIASN1_TIME_to_generalizedtime()\fR function converts an \s-1ASN1_TIME\s0 to an
\&\s-1ASN1_GENERALIZEDTIME,\s0 regardless of year. If either \fBout\fR or
\&\fB*out\fR are \s-1NULL,\s0 then a new object is allocated and must be freed after use.
.SH "NOTES"
.IX Header "NOTES"
The \s-1ASN1_TIME\s0 structure corresponds to the \s-1ASN.1\s0 structure \fBTime\fR
@ -191,34 +259,51 @@ defined in \s-1RFC5280\s0 et al. The time setting functions obey the rules outli
in \s-1RFC5280:\s0 if the date can be represented by UTCTime it is used, else
GeneralizedTime is used.
.PP
The \s-1ASN1_TIME\s0 structure is represented as an \s-1ASN1_STRING\s0 internally and can
be freed up using \fIASN1_STRING_free()\fR.
The \s-1ASN1_TIME, ASN1_UTCTIME\s0 and \s-1ASN1_GENERALIZEDTIME\s0 structures are represented
as an \s-1ASN1_STRING\s0 internally and can be freed up using \fIASN1_STRING_free()\fR.
.PP
The \s-1ASN1_TIME\s0 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).
.PP
\&\s-1ASN1_UTCTIME\s0 is limited to a year range of 1950 through 2049.
.PP
Some applications add offset times directly to a time_t value and pass the
results to \fIASN1_TIME_set()\fR (or equivalent). This can cause problems as the
time_t value can overflow on some systems resulting in unexpected results.
New applications should use \fIASN1_TIME_adj()\fR instead and pass the offset value
in the \fBoffset_sec\fR and \fBoffset_day\fR parameters instead of directly
manipulating a time_t value.
.PP
\&\fIASN1_TIME_adj()\fR may change the type from \s-1ASN1_GENERALIZEDTIME\s0 to \s-1ASN1_UTCTIME,\s0
or vice versa, based on the resulting year. The \fIASN1_GENERALIZEDTIME_adj()\fR and
\&\fIASN1_UTCTIME_adj()\fR functions will not modify the type of the return structure.
.PP
It is recommended that functions starting with \s-1ASN1_TIME\s0 be used instead of
those starting with \s-1ASN1_UTCTIME\s0 or \s-1ASN1_GENERALIZEDTIME.\s0 The functions
starting with \s-1ASN1_UTCTIME\s0 and \s-1ASN1_GENERALIZEDTIME\s0 act only on that specific
time format. The functions starting with \s-1ASN1_TIME\s0 will operate on either
format.
.SH "BUGS"
.IX Header "BUGS"
\&\fIASN1_TIME_print()\fR currently does not print out the time zone: it either prints
out \*(L"\s-1GMT\*(R"\s0 or nothing. But all certificates complying with \s-1RFC5280\s0 et al use \s-1GMT\s0
anyway.
\&\fIASN1_TIME_print()\fR, \fIASN1_UTCTIME_print()\fR and \fIASN1_GENERALIZEDTIME_print()\fR
do not print out the time zone: it either prints out \*(L"\s-1GMT\*(R"\s0 or nothing. But all
certificates complying with \s-1RFC5280\s0 et al use \s-1GMT\s0 anyway.
.PP
Use the \fIASN1_TIME_normalize()\fR function to normalize the time value before
printing to get \s-1GMT\s0 results.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
Set a time structure to one hour after the current time and print it out:
.PP
.Vb 11
.Vb 2
\& #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);
@ -233,28 +318,59 @@ Determine if one time is later or sooner than the current time:
\& int day, sec;
\&
\& if (!ASN1_TIME_diff(&day, &sec, NULL, to))
\& /* Invalid time format */
\& /* Invalid time format */
\&
\& if (day > 0 || sec > 0)
\& printf("Later\en");
\& printf("Later\en");
\& else if (day < 0 || sec < 0)
\& printf("Sooner\en");
\& printf("Sooner\en");
\& else
\& printf("Same\en");
\& printf("Same\en");
.Ve
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fIASN1_TIME_set()\fR and \fIASN1_TIME_adj()\fR return a pointer to an \s-1ASN1_TIME\s0 structure
\&\fIASN1_TIME_set()\fR, \fIASN1_UTCTIME_set()\fR, \fIASN1_GENERALIZEDTIME_set()\fR, \fIASN1_TIME_adj()\fR,
ASN1_UTCTIME_adj and ASN1_GENERALIZEDTIME_set return a pointer to a time structure
or \s-1NULL\s0 if an error occurred.
.PP
\&\fIASN1_TIME_set_string()\fR returns 1 if the time value is successfully set and
0 otherwise.
\&\fIASN1_TIME_set_string()\fR, \fIASN1_UTCTIME_set_string()\fR, \fIASN1_GENERALIZEDTIME_set_string()\fR
\&\fIASN1_TIME_set_string_X509()\fR return 1 if the time value is successfully set and 0 otherwise.
.PP
\&\fIASN1_TIME_check()\fR returns 1 if the structure is syntactically correct and 0
otherwise.
\&\fIASN1_TIME_normalize()\fR returns 1 on success, and 0 on error.
.PP
\&\fIASN1_TIME_print()\fR returns 1 if the time is successfully printed out and 0 if
an error occurred (I/O error or invalid time format).
\&\fIASN1_TIME_check()\fR, ASN1_UTCTIME_check and \fIASN1_GENERALIZEDTIME_check()\fR return 1
if the structure is syntactically correct and 0 otherwise.
.PP
\&\fIASN1_TIME_diff()\fR returns 1 for sucess and 0 for failure. It can fail if the
pass \s-1ASN1_TIME\s0 structure has invalid syntax for example.
\&\fIASN1_TIME_print()\fR, \fIASN1_UTCTIME_print()\fR and \fIASN1_GENERALIZEDTIME_print()\fR return 1
if the time is successfully printed out and 0 if an error occurred (I/O error or
invalid time format).
.PP
\&\fIASN1_TIME_to_tm()\fR returns 1 if the time is successfully parsed and 0 if an
error occurred (invalid time format).
.PP
\&\fIASN1_TIME_diff()\fR returns 1 for success and 0 for failure. It can fail if the
passed-in time structure has invalid syntax, for example.
.PP
\&\fIASN1_TIME_cmp_time_t()\fR and \fIASN1_UTCTIME_cmp_time_t()\fR return \-1 if \fBs\fR is
before \fBt\fR, 0 if \fBs\fR equals \fBt\fR, or 1 if \fBs\fR is after \fBt\fR. \-2 is returned
on error.
.PP
\&\fIASN1_TIME_compare()\fR returns \-1 if \fBa\fR is before \fBb\fR, 0 if \fBa\fR equals \fBb\fR, or 1 if \fBa\fR is after \fBb\fR. \-2 is returned on error.
.PP
\&\fIASN1_TIME_to_generalizedtime()\fR returns a pointer to
the appropriate time structure on success or \s-1NULL\s0 if an error occurred.
.SH "HISTORY"
.IX Header "HISTORY"
The \fIASN1_TIME_to_tm()\fR function was added in OpenSSL 1.1.1.
The \fIASN1_TIME_set_string_X509()\fR function was added in OpenSSL 1.1.1.
The \fIASN1_TIME_normalize()\fR function was added in OpenSSL 1.1.1.
The \fIASN1_TIME_cmp_time_t()\fR function was added in OpenSSL 1.1.1.
The \fIASN1_TIME_compare()\fR function was added in OpenSSL 1.1.1.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2015\-2018 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

227
secure/lib/libcrypto/man/ASN1_TYPE_get.3 Normal file
View file

@ -0,0 +1,227 @@
.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "ASN1_TYPE_GET 3"
.TH ASN1_TYPE_GET 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "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
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
These functions allow an \s-1ASN1_TYPE\s0 structure to be manipulated. The
\&\s-1ASN1_TYPE\s0 structure can contain any \s-1ASN.1\s0 type or constructed type
such as a \s-1SEQUENCE:\s0 it is effectively equivalent to the \s-1ASN.1 ANY\s0 type.
.PP
\&\fIASN1_TYPE_get()\fR returns the type of \fBa\fR.
.PP
\&\fIASN1_TYPE_set()\fR sets the value of \fBa\fR to \fBtype\fR and \fBvalue\fR. This
function uses the pointer \fBvalue\fR internally so it must \fBnot\fR be freed
up after the call.
.PP
\&\fIASN1_TYPE_set1()\fR sets the value of \fBa\fR to \fBtype\fR a copy of \fBvalue\fR.
.PP
\&\fIASN1_TYPE_cmp()\fR compares \s-1ASN.1\s0 types \fBa\fR and \fBb\fR and returns 0 if
they are identical and non-zero otherwise.
.PP
\&\fIASN1_TYPE_unpack_sequence()\fR attempts to parse the \s-1SEQUENCE\s0 present in
\&\fBt\fR using the \s-1ASN.1\s0 structure \fBit\fR. If successful it returns a pointer
to the \s-1ASN.1\s0 structure corresponding to \fBit\fR which must be freed by the
caller. If it fails it return \s-1NULL.\s0
.PP
\&\fIASN1_TYPE_pack_sequence()\fR attempts to encode the \s-1ASN.1\s0 structure \fBs\fR
corresponding to \fBit\fR into an \s-1ASN1_TYPE.\s0 If successful the encoded
\&\s-1ASN1_TYPE\s0 is returned. If \fBt\fR and \fB*t\fR are not \s-1NULL\s0 the encoded type
is written to \fBt\fR overwriting any existing data. If \fBt\fR is not \s-1NULL\s0
but \fB*t\fR is \s-1NULL\s0 the returned \s-1ASN1_TYPE\s0 is written to \fB*t\fR.
.SH "NOTES"
.IX Header "NOTES"
The type and meaning of the \fBvalue\fR parameter for \fIASN1_TYPE_set()\fR and
\&\fIASN1_TYPE_set1()\fR is determined by the \fBtype\fR parameter.
If \fBtype\fR is V_ASN1_NULL \fBvalue\fR is ignored. If \fBtype\fR is V_ASN1_BOOLEAN
then the boolean is set to \s-1TRUE\s0 if \fBvalue\fR is not \s-1NULL.\s0 If \fBtype\fR is
V_ASN1_OBJECT then value is an \s-1ASN1_OBJECT\s0 structure. Otherwise \fBtype\fR
is and \s-1ASN1_STRING\s0 structure. If \fBtype\fR corresponds to a primitive type
(or a string type) then the contents of the \s-1ASN1_STRING\s0 contain the content
octets of the type. If \fBtype\fR corresponds to a constructed type or
a tagged type (V_ASN1_SEQUENCE, V_ASN1_SET or V_ASN1_OTHER) then the
\&\s-1ASN1_STRING\s0 contains the entire \s-1ASN.1\s0 encoding verbatim (including tag and
length octets).
.PP
\&\fIASN1_TYPE_cmp()\fR may not return zero if two types are equivalent but have
different encodings. For example the single content octet of the boolean \s-1TRUE\s0
value under \s-1BER\s0 can have any non-zero encoding but \fIASN1_TYPE_cmp()\fR will
only return zero if the values are the same.
.PP
If either or both of the parameters passed to \fIASN1_TYPE_cmp()\fR is \s-1NULL\s0 the
return value is non-zero. Technically if both parameters are \s-1NULL\s0 the two
types could be absent \s-1OPTIONAL\s0 fields and so should match, however passing
\&\s-1NULL\s0 values could also indicate a programming error (for example an
unparseable type which returns \s-1NULL\s0) for types which do \fBnot\fR match. So
applications should handle the case of two absent values separately.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fIASN1_TYPE_get()\fR returns the type of the \s-1ASN1_TYPE\s0 argument.
.PP
\&\fIASN1_TYPE_set()\fR does not return a value.
.PP
\&\fIASN1_TYPE_set1()\fR returns 1 for success and 0 for failure.
.PP
\&\fIASN1_TYPE_cmp()\fR returns 0 if the types are identical and non-zero otherwise.
.PP
\&\fIASN1_TYPE_unpack_sequence()\fR returns a pointer to an \s-1ASN.1\s0 structure or
\&\s-1NULL\s0 on failure.
.PP
\&\fIASN1_TYPE_pack_sequence()\fR return an \s-1ASN1_TYPE\s0 structure if it succeeds or
\&\s-1NULL\s0 on failure.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2015\-2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

63
secure/lib/libcrypto/man/ASN1_generate_nconf.3
View file

@ -128,8 +128,8 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "ASN1_generate_nconf 3"
.TH ASN1_generate_nconf 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "ASN1_GENERATE_NCONF 3"
.TH ASN1_GENERATE_NCONF 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
@ -141,8 +141,8 @@ ASN1_generate_nconf, ASN1_generate_v3 \- ASN1 generation functions
.Vb 1
\& #include <openssl/asn1.h>
\&
\& ASN1_TYPE *ASN1_generate_nconf(char *str, CONF *nconf);
\& ASN1_TYPE *ASN1_generate_v3(char *str, X509V3_CTX *cnf);
\& ASN1_TYPE *ASN1_generate_nconf(const char *str, CONF *nconf);
\& ASN1_TYPE *ASN1_generate_v3(const char *str, X509V3_CTX *cnf);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
@ -152,7 +152,7 @@ in an \fB\s-1ASN1_TYPE\s0\fR structure.
\&\fBstr\fR contains the string to encode \fBnconf\fR or \fBcnf\fR contains
the optional configuration information where additional strings
will be read from. \fBnconf\fR will typically come from a config
file wherease \fBcnf\fR is obtained from an \fBX509V3_CTX\fR structure
file whereas \fBcnf\fR is obtained from an \fBX509V3_CTX\fR structure
which will typically be used by X509 v3 certificate extension
functions. \fBcnf\fR or \fBnconf\fR can be set to \fB\s-1NULL\s0\fR if no additional
configuration will be used.
@ -161,53 +161,53 @@ configuration will be used.
The actual data encoded is determined by the string \fBstr\fR and
the configuration information. The general format of the string
is:
.IP "\fB[modifier,]type[:value]\fR" 2
.IP "\fB[modifier,]type[:value]\fR" 4
.IX Item "[modifier,]type[:value]"
.PP
That is zero or more comma separated modifiers followed by a type
followed by an optional colon and a value. The formats of \fBtype\fR,
\&\fBvalue\fR and \fBmodifier\fR are explained below.
.SS "\s-1SUPPORTED TYPES\s0"
.IX Subsection "SUPPORTED TYPES"
.SS "Supported Types"
.IX Subsection "Supported Types"
The supported types are listed below. Unless otherwise specified
only the \fB\s-1ASCII\s0\fR format is permissible.
.IP "\fB\s-1BOOLEAN\s0\fR, \fB\s-1BOOL\s0\fR" 2
.IP "\fB\s-1BOOLEAN\s0\fR, \fB\s-1BOOL\s0\fR" 4
.IX Item "BOOLEAN, BOOL"
This encodes a boolean type. The \fBvalue\fR string is mandatory and
should be \fB\s-1TRUE\s0\fR or \fB\s-1FALSE\s0\fR. Additionally \fB\s-1TRUE\s0\fR, \fBtrue\fR, \fBY\fR,
\&\fBy\fR, \fB\s-1YES\s0\fR, \fByes\fR, \fB\s-1FALSE\s0\fR, \fBfalse\fR, \fBN\fR, \fBn\fR, \fB\s-1NO\s0\fR and \fBno\fR
are acceptable.
.IP "\fB\s-1NULL\s0\fR" 2
.IP "\fB\s-1NULL\s0\fR" 4
.IX Item "NULL"
Encode the \fB\s-1NULL\s0\fR type, the \fBvalue\fR string must not be present.
.IP "\fB\s-1INTEGER\s0\fR, \fB\s-1INT\s0\fR" 2
.IP "\fB\s-1INTEGER\s0\fR, \fB\s-1INT\s0\fR" 4
.IX Item "INTEGER, INT"
Encodes an \s-1ASN1\s0 \fB\s-1INTEGER\s0\fR type. The \fBvalue\fR 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 \fB0x\fR
is included.
.IP "\fB\s-1ENUMERATED\s0\fR, \fB\s-1ENUM\s0\fR" 2
.IP "\fB\s-1ENUMERATED\s0\fR, \fB\s-1ENUM\s0\fR" 4
.IX Item "ENUMERATED, ENUM"
Encodes the \s-1ASN1\s0 \fB\s-1ENUMERATED\s0\fR type, it is otherwise identical to
\&\fB\s-1INTEGER\s0\fR.
.IP "\fB\s-1OBJECT\s0\fR, \fB\s-1OID\s0\fR" 2
.IP "\fB\s-1OBJECT\s0\fR, \fB\s-1OID\s0\fR" 4
.IX Item "OBJECT, OID"
Encodes an \s-1ASN1\s0 \fB\s-1OBJECT IDENTIFIER\s0\fR, the \fBvalue\fR string can be
a short name, a long name or numerical format.
.IP "\fB\s-1UTCTIME\s0\fR, \fB\s-1UTC\s0\fR" 2
.IP "\fB\s-1UTCTIME\s0\fR, \fB\s-1UTC\s0\fR" 4
.IX Item "UTCTIME, UTC"
Encodes an \s-1ASN1\s0 \fBUTCTime\fR structure, the value should be in
the format \fB\s-1YYMMDDHHMMSSZ\s0\fR.
.IP "\fB\s-1GENERALIZEDTIME\s0\fR, \fB\s-1GENTIME\s0\fR" 2
.IP "\fB\s-1GENERALIZEDTIME\s0\fR, \fB\s-1GENTIME\s0\fR" 4
.IX Item "GENERALIZEDTIME, GENTIME"
Encodes an \s-1ASN1\s0 \fBGeneralizedTime\fR structure, the value should be in
the format \fB\s-1YYYYMMDDHHMMSSZ\s0\fR.
.IP "\fB\s-1OCTETSTRING\s0\fR, \fB\s-1OCT\s0\fR" 2
.IP "\fB\s-1OCTETSTRING\s0\fR, \fB\s-1OCT\s0\fR" 4
.IX Item "OCTETSTRING, OCT"
Encodes an \s-1ASN1\s0 \fB\s-1OCTET STRING\s0\fR. \fBvalue\fR represents the contents
of this structure, the format strings \fB\s-1ASCII\s0\fR and \fB\s-1HEX\s0\fR can be
used to specify the format of \fBvalue\fR.
.IP "\fB\s-1BITSTRING\s0\fR, \fB\s-1BITSTR\s0\fR" 2
.IP "\fB\s-1BITSTRING\s0\fR, \fB\s-1BITSTR\s0\fR" 4
.IX Item "BITSTRING, BITSTR"
Encodes an \s-1ASN1\s0 \fB\s-1BIT STRING\s0\fR. \fBvalue\fR represents the contents
of this structure, the format strings \fB\s-1ASCII\s0\fR, \fB\s-1HEX\s0\fR and \fB\s-1BITLIST\s0\fR
@ -215,24 +215,24 @@ can be used to specify the format of \fBvalue\fR.
.Sp
If the format is anything other than \fB\s-1BITLIST\s0\fR the number of unused
bits is set to zero.
.IP "\fB\s-1UNIVERSALSTRING\s0\fR, \fB\s-1UNIV\s0\fR, \fB\s-1IA5\s0\fR, \fB\s-1IA5STRING\s0\fR, \fB\s-1UTF8\s0\fR, \fBUTF8String\fR, \fB\s-1BMP\s0\fR, \fB\s-1BMPSTRING\s0\fR, \fB\s-1VISIBLESTRING\s0\fR, \fB\s-1VISIBLE\s0\fR, \fB\s-1PRINTABLESTRING\s0\fR, \fB\s-1PRINTABLE\s0\fR, \fBT61\fR, \fBT61STRING\fR, \fB\s-1TELETEXSTRING\s0\fR, \fBGeneralString\fR, \fB\s-1NUMERICSTRING\s0\fR, \fB\s-1NUMERIC\s0\fR" 2
.IP "\fB\s-1UNIVERSALSTRING\s0\fR, \fB\s-1UNIV\s0\fR, \fB\s-1IA5\s0\fR, \fB\s-1IA5STRING\s0\fR, \fB\s-1UTF8\s0\fR, \fBUTF8String\fR, \fB\s-1BMP\s0\fR, \fB\s-1BMPSTRING\s0\fR, \fB\s-1VISIBLESTRING\s0\fR, \fB\s-1VISIBLE\s0\fR, \fB\s-1PRINTABLESTRING\s0\fR, \fB\s-1PRINTABLE\s0\fR, \fBT61\fR, \fBT61STRING\fR, \fB\s-1TELETEXSTRING\s0\fR, \fBGeneralString\fR, \fB\s-1NUMERICSTRING\s0\fR, \fB\s-1NUMERIC\s0\fR" 4
.IX Item "UNIVERSALSTRING, UNIV, IA5, IA5STRING, UTF8, UTF8String, BMP, BMPSTRING, VISIBLESTRING, VISIBLE, PRINTABLESTRING, PRINTABLE, T61, T61STRING, TELETEXSTRING, GeneralString, NUMERICSTRING, NUMERIC"
These encode the corresponding string types. \fBvalue\fR represents the
contents of this structure. The format can be \fB\s-1ASCII\s0\fR or \fB\s-1UTF8\s0\fR.
.IP "\fB\s-1SEQUENCE\s0\fR, \fB\s-1SEQ\s0\fR, \fB\s-1SET\s0\fR" 2
.IP "\fB\s-1SEQUENCE\s0\fR, \fB\s-1SEQ\s0\fR, \fB\s-1SET\s0\fR" 4
.IX Item "SEQUENCE, SEQ, SET"
Formats the result as an \s-1ASN1\s0 \fB\s-1SEQUENCE\s0\fR or \fB\s-1SET\s0\fR type. \fBvalue\fR
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 \fBvalue\fR is absent then an empty \s-1SEQUENCE\s0
will be encoded.
.SS "\s-1MODIFIERS\s0"
.IX Subsection "MODIFIERS"
.SS "Modifiers"
.IX Subsection "Modifiers"
Modifiers affect the following structure, they can be used to
add \s-1EXPLICIT\s0 or \s-1IMPLICIT\s0 tagging, add wrappers or to change
the string format of the final type and value. The supported
formats are documented below.
.IP "\fB\s-1EXPLICIT\s0\fR, \fB\s-1EXP\s0\fR" 2
.IP "\fB\s-1EXPLICIT\s0\fR, \fB\s-1EXP\s0\fR" 4
.IX Item "EXPLICIT, 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
@ -241,16 +241,16 @@ decimal value.
By following the number with \fBU\fR, \fBA\fR, \fBP\fR or \fBC\fR \s-1UNIVERSAL,
APPLICATION, PRIVATE\s0 or \s-1CONTEXT SPECIFIC\s0 tagging can be used,
the default is \s-1CONTEXT SPECIFIC.\s0
.IP "\fB\s-1IMPLICIT\s0\fR, \fB\s-1IMP\s0\fR" 2
.IP "\fB\s-1IMPLICIT\s0\fR, \fB\s-1IMP\s0\fR" 4
.IX Item "IMPLICIT, IMP"
This is the same as \fB\s-1EXPLICIT\s0\fR except \s-1IMPLICIT\s0 tagging is used
instead.
.IP "\fB\s-1OCTWRAP\s0\fR, \fB\s-1SEQWRAP\s0\fR, \fB\s-1SETWRAP\s0\fR, \fB\s-1BITWRAP\s0\fR" 2
.IP "\fB\s-1OCTWRAP\s0\fR, \fB\s-1SEQWRAP\s0\fR, \fB\s-1SETWRAP\s0\fR, \fB\s-1BITWRAP\s0\fR" 4
.IX Item "OCTWRAP, SEQWRAP, SETWRAP, BITWRAP"
The following structure is surrounded by an \s-1OCTET STRING,\s0 a \s-1SEQUENCE,\s0
a \s-1SET\s0 or a \s-1BIT STRING\s0 respectively. For a \s-1BIT STRING\s0 the number of unused
bits is set to zero.
.IP "\fB\s-1FORMAT\s0\fR" 2
.IP "\fB\s-1FORMAT\s0\fR" 4
.IX Item "FORMAT"
This specifies the format of the ultimate value. It should be followed
by a colon and one of the strings \fB\s-1ASCII\s0\fR, \fB\s-1UTF8\s0\fR, \fB\s-1HEX\s0\fR or \fB\s-1BITLIST\s0\fR.
@ -287,7 +287,7 @@ A \s-1BITSTRING\s0 with bits 1 and 5 set and all others zero:
.Ve
.PP
A more complex example using a config file to produce a
\&\s-1SEQUENCE\s0 consiting of a \s-1BOOL\s0 an \s-1OID\s0 and a UTF8String:
\&\s-1SEQUENCE\s0 consisting of a \s-1BOOL\s0 an \s-1OID\s0 and a UTF8String:
.PP
.Vb 1
\& asn1 = SEQUENCE:seq_section
@ -367,6 +367,11 @@ The error codes that can be obtained by \fIERR_get_error\fR\|(3).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIERR_get_error\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fIASN1_generate_nconf()\fR and \fIASN1_generate_v3()\fR were added to OpenSSL 0.9.8
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2002\-2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

266
secure/lib/libcrypto/man/ASYNC_WAIT_CTX_new.3 Normal file
View file

@ -0,0 +1,266 @@
.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "ASYNC_WAIT_CTX_NEW 3"
.TH ASYNC_WAIT_CTX_NEW 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "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
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
For an overview of how asynchronous operations are implemented in OpenSSL see
\&\fIASYNC_start_job\fR\|(3). An \s-1ASYNC_WAIT_CTX\s0 object represents an asynchronous
\&\*(L"session\*(R", i.e. a related set of crypto operations. For example in \s-1SSL\s0 terms
this would have a one-to-one correspondence with an \s-1SSL\s0 connection.
.PP
Application code must create an \s-1ASYNC_WAIT_CTX\s0 using the \fIASYNC_WAIT_CTX_new()\fR
function prior to calling \fIASYNC_start_job()\fR (see \fIASYNC_start_job\fR\|(3)). When
the job is started it is associated with the \s-1ASYNC_WAIT_CTX\s0 for the duration of
that job. An \s-1ASYNC_WAIT_CTX\s0 should only be used for one \s-1ASYNC_JOB\s0 at any one
time, but can be reused after an \s-1ASYNC_JOB\s0 has finished for a subsequent
\&\s-1ASYNC_JOB.\s0 When the session is complete (e.g. the \s-1SSL\s0 connection is closed),
application code cleans up with \fIASYNC_WAIT_CTX_free()\fR.
.PP
ASYNC_WAIT_CTXs can have \*(L"wait\*(R" file descriptors associated with them. Calling
\&\fIASYNC_WAIT_CTX_get_all_fds()\fR and passing in a pointer to an \s-1ASYNC_WAIT_CTX\s0 in
the \fBctx\fR parameter will return the wait file descriptors associated with that
job in \fB*fd\fR. The number of file descriptors returned will be stored in
\&\fB*numfds\fR. It is the caller's responsibility to ensure that sufficient memory
has been allocated in \fB*fd\fR to receive all the file descriptors. Calling
\&\fIASYNC_WAIT_CTX_get_all_fds()\fR with a \s-1NULL\s0 \fBfd\fR value will return no file
descriptors but will still populate \fB*numfds\fR. 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.
.PP
The function \fIASYNC_WAIT_CTX_get_changed_fds()\fR can be used to detect if any fds
have changed since the last call time \fIASYNC_start_job()\fR returned an \s-1ASYNC_PAUSE\s0
result (or since the \s-1ASYNC_WAIT_CTX\s0 was created if no \s-1ASYNC_PAUSE\s0 result has
been received). The \fBnumaddfds\fR and \fBnumdelfds\fR parameters will be populated
with the number of fds added or deleted respectively. \fB*addfd\fR and \fB*delfd\fR
will be populated with the list of added and deleted fds respectively. Similarly
to \fIASYNC_WAIT_CTX_get_all_fds()\fR either of these can be \s-1NULL,\s0 but if they are not
\&\s-1NULL\s0 then the caller is responsible for ensuring sufficient memory is allocated.
.PP
Implementors of async aware code (e.g. engines) are encouraged to return a
stable fd for the lifetime of the \s-1ASYNC_WAIT_CTX\s0 in order to reduce the \*(L"churn\*(R"
of regularly changing fds \- although no guarantees of this are provided to
applications.
.PP
Applications can wait for the file descriptor to be ready for \*(L"read\*(R" using a
system function call such as select or poll (being ready for \*(L"read\*(R" indicates
that the job should be resumed). If no file descriptor is made available then an
application will have to periodically \*(L"poll\*(R" the job by attempting to restart it
to see if it is ready to continue.
.PP
Async aware code (e.g. engines) can get the current \s-1ASYNC_WAIT_CTX\s0 from the job
via \fIASYNC_get_wait_ctx\fR\|(3) and provide a file descriptor to use for waiting
on by calling \fIASYNC_WAIT_CTX_set_wait_fd()\fR. Typically this would be done by an
engine immediately prior to calling \fIASYNC_pause_job()\fR and not by end user code.
An existing association with a file descriptor can be obtained using
\&\fIASYNC_WAIT_CTX_get_fd()\fR and cleared using \fIASYNC_WAIT_CTX_clear_fd()\fR. Both of
these functions requires a \fBkey\fR value which is unique to the async aware
code. This could be any unique value but a good candidate might be the
\&\fB\s-1ENGINE\s0 *\fR for the engine. The \fBcustom_data\fR parameter can be any value, and
will be returned in a subsequent call to \fIASYNC_WAIT_CTX_get_fd()\fR. The
\&\fIASYNC_WAIT_CTX_set_wait_fd()\fR function also expects a pointer to a \*(L"cleanup\*(R"
routine. This can be \s-1NULL\s0 but if provided will automatically get called when
the \s-1ASYNC_WAIT_CTX\s0 is freed, and gives the engine the opportunity to close the
fd or any other resources. Note: The \*(L"cleanup\*(R" routine does not get called if
the fd is cleared directly via a call to \fIASYNC_WAIT_CTX_clear_fd()\fR.
.PP
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 \fIASYNC_WAIT_CTX_set_wait_fd()\fR followed by
\&\fIASYNC_pause_job()\fR 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 \*(L"select\*(R" 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
\&\*(L"readable\*(R". Once resumed the engine should clear the wake signal on the wait
file descriptor.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fIASYNC_WAIT_CTX_new()\fR returns a pointer to the newly allocated \s-1ASYNC_WAIT_CTX\s0 or
\&\s-1NULL\s0 on error.
.PP
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.
.SH "NOTES"
.IX Header "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.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIcrypto\fR\|(7), \fIASYNC_start_job\fR\|(3)
.SH "HISTORY"
.IX Header "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.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

449
secure/lib/libcrypto/man/ASYNC_start_job.3 Normal file
View file

@ -0,0 +1,449 @@
.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "ASYNC_START_JOB 3"
.TH ASYNC_START_JOB 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "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
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
OpenSSL implements asynchronous capabilities through an \s-1ASYNC_JOB.\s0 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.
.PP
The creation of an \s-1ASYNC_JOB\s0 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 \fIASYNC_init_thread()\fR 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 \fIOPENSSL_init_crypto\fR\|(3)) but may be explicitly
initiated by using \fIASYNC_cleanup_thread()\fR. No asynchronous jobs must be
outstanding for the thread when \fIASYNC_cleanup_thread()\fR is called. Failing to
ensure this will result in memory leaks.
.PP
The \fBmax_size\fR argument limits the number of ASYNC_JOBs that will be held in
the pool. If \fBmax_size\fR is set to 0 then no upper limit is set. When an
\&\s-1ASYNC_JOB\s0 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 \fBmax_size\fR. When the pool is first initialised
\&\fBinit_size\fR ASYNC_JOBs will be created immediately. If \fIASYNC_init_thread()\fR is
not called before the pool is first used then it will be called automatically
with a \fBmax_size\fR of 0 (no upper limit) and an \fBinit_size\fR of 0 (no ASYNC_JOBs
created up front).
.PP
An asynchronous job is started by calling the \fIASYNC_start_job()\fR function.
Initially \fB*job\fR should be \s-1NULL.\s0 \fBctx\fR should point to an \s-1ASYNC_WAIT_CTX\s0
object created through the \fIASYNC_WAIT_CTX_new\fR\|(3) function. \fBret\fR should
point to a location where the return value of the asynchronous function should
be stored on completion of the job. \fBfunc\fR represents the function that should
be started asynchronously. The data pointed to by \fBargs\fR and of size \fBsize\fR
will be copied and then passed as an argument to \fBfunc\fR when the job starts.
ASYNC_start_job will return one of the following values:
.IP "\fB\s-1ASYNC_ERR\s0\fR" 4
.IX Item "ASYNC_ERR"
An error occurred trying to start the job. Check the OpenSSL error queue (e.g.
see \fIERR_print_errors\fR\|(3)) for more details.
.IP "\fB\s-1ASYNC_NO_JOBS\s0\fR" 4
.IX Item "ASYNC_NO_JOBS"
There are no jobs currently available in the pool. This call can be retried
again at a later time.
.IP "\fB\s-1ASYNC_PAUSE\s0\fR" 4
.IX Item "ASYNC_PAUSE"
The job was successfully started but was \*(L"paused\*(R" before it completed (see
\&\fIASYNC_pause_job()\fR below). A handle to the job is placed in \fB*job\fR. Other work
can be performed (if desired) and the job restarted at a later time. To restart
a job call \fIASYNC_start_job()\fR again passing the job handle in \fB*job\fR. The
\&\fBfunc\fR, \fBargs\fR and \fBsize\fR parameters will be ignored when restarting a job.
When restarting a job \fIASYNC_start_job()\fR \fBmust\fR be called from the same thread
that the job was originally started from.
.IP "\fB\s-1ASYNC_FINISH\s0\fR" 4
.IX Item "ASYNC_FINISH"
The job completed. \fB*job\fR will be \s-1NULL\s0 and the return value from \fBfunc\fR will
be placed in \fB*ret\fR.
.PP
At any one time there can be a maximum of one job actively running per thread
(you can have many that are paused). \fIASYNC_get_current_job()\fR can be used to get
a pointer to the currently executing \s-1ASYNC_JOB.\s0 If no job is currently executing
then this will return \s-1NULL.\s0
.PP
If executing within the context of a job (i.e. having been called directly or
indirectly by the function \*(L"func\*(R" passed as an argument to \fIASYNC_start_job()\fR)
then \fIASYNC_pause_job()\fR will immediately return control to the calling
application with \s-1ASYNC_PAUSE\s0 returned from the \fIASYNC_start_job()\fR call. A
subsequent call to ASYNC_start_job passing in the relevant \s-1ASYNC_JOB\s0 in the
\&\fB*job\fR parameter will resume execution from the \fIASYNC_pause_job()\fR call. If
\&\fIASYNC_pause_job()\fR is called whilst not within the context of a job then no
action is taken and \fIASYNC_pause_job()\fR returns immediately.
.PP
\&\fIASYNC_get_wait_ctx()\fR can be used to get a pointer to the \s-1ASYNC_WAIT_CTX\s0
for the \fBjob\fR. ASYNC_WAIT_CTXs can have a \*(L"wait\*(R" file descriptor associated
with them. Applications can wait for the file descriptor to be ready for \*(L"read\*(R"
using a system function call such as select or poll (being ready for \*(L"read\*(R"
indicates that the job should be resumed). If no file descriptor is made
available then an application will have to periodically \*(L"poll\*(R" the job by
attempting to restart it to see if it is ready to continue.
.PP
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 \fIASYNC_WAIT_CTX_set_wait_fd\fR\|(3) followed by
\&\fIASYNC_pause_job()\fR 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 \*(L"select\*(R" 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
\&\*(L"readable\*(R". Once resumed the engine should clear the wake signal on the wait
file descriptor.
.PP
The \fIASYNC_block_pause()\fR function will prevent the currently active job from
pausing. The block will remain in place until a subsequent call to
\&\fIASYNC_unblock_pause()\fR. These functions can be nested, e.g. if you call
\&\fIASYNC_block_pause()\fR twice then you must call \fIASYNC_unblock_pause()\fR 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 \s-1ASYNC_JOB\s0 an
application acquires a lock. It then calls some cryptographic function which
invokes \fIASYNC_pause_job()\fR. This returns control back to the code that created
the \s-1ASYNC_JOB.\s0 If that code then attempts to acquire the same lock before
resuming the original job then a deadlock can occur. By calling
\&\fIASYNC_block_pause()\fR immediately after acquiring the lock and
\&\fIASYNC_unblock_pause()\fR immediately before releasing it then this situation cannot
occur.
.PP
Some platforms cannot support async operations. The \fIASYNC_is_capable()\fR function
can be used to detect whether the current platform is async capable or not.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
ASYNC_init_thread returns 1 on success or 0 otherwise.
.PP
ASYNC_start_job returns one of \s-1ASYNC_ERR, ASYNC_NO_JOBS, ASYNC_PAUSE\s0 or
\&\s-1ASYNC_FINISH\s0 as described above.
.PP
ASYNC_pause_job returns 0 if an error occurred or 1 on success. If called when
not within the context of an \s-1ASYNC_JOB\s0 then this is counted as success so 1 is
returned.
.PP
ASYNC_get_current_job returns a pointer to the currently executing \s-1ASYNC_JOB\s0 or
\&\s-1NULL\s0 if not within the context of a job.
.PP
\&\fIASYNC_get_wait_ctx()\fR returns a pointer to the \s-1ASYNC_WAIT_CTX\s0 for the job.
.PP
\&\fIASYNC_is_capable()\fR returns 1 if the current platform is async capable or 0
otherwise.
.SH "NOTES"
.IX Header "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.
.SH "EXAMPLE"
.IX Header "EXAMPLE"
The following example demonstrates how to use most of the core async APIs:
.PP
.Vb 7
\& #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 = \*(AqX\*(Aq;
\&
\& currjob = ASYNC_get_current_job();
\& if (currjob != NULL) {
\& printf("Executing within a job\en");
\& } else {
\& printf("Not executing within a job \- should not happen\en");
\& return 0;
\& }
\&
\& msg = (unsigned char *)arg;
\& printf("Passed in message is: %s\en", msg);
\&
\& if (pipe(pipefds) != 0) {
\& printf("Failed to create pipe\en");
\& return 0;
\& }
\& wptr = OPENSSL_malloc(sizeof(OSSL_ASYNC_FD));
\& if (wptr == NULL) {
\& printf("Failed to malloc\en");
\& 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\en");
\&
\& 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...\en");
\&
\& ctx = ASYNC_WAIT_CTX_new();
\& if (ctx == NULL) {
\& printf("Failed to create ASYNC_WAIT_CTX\en");
\& abort();
\& }
\&
\& for (;;) {
\& switch (ASYNC_start_job(&job, ctx, &ret, jobfunc, msg, sizeof(msg))) {
\& case ASYNC_ERR:
\& case ASYNC_NO_JOBS:
\& printf("An error occurred\en");
\& goto end;
\& case ASYNC_PAUSE:
\& printf("Job was paused\en");
\& break;
\& case ASYNC_FINISH:
\& printf("Job finished with return value %d\en", ret);
\& goto end;
\& }
\&
\& /* Wait for the job to be woken */
\& printf("Waiting for the job to be woken up\en");
\&
\& if (!ASYNC_WAIT_CTX_get_all_fds(ctx, NULL, &numfds)
\& || numfds > 1) {
\& printf("Unexpected number of fds\en");
\& 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\en");
\&
\& return 0;
\& }
.Ve
.PP
The expected output from executing the above example program is:
.PP
.Vb 8
\& 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
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIcrypto\fR\|(7), \fIERR_print_errors\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
ASYNC_init_thread, ASYNC_cleanup_thread,
ASYNC_start_job, ASYNC_pause_job, ASYNC_get_current_job, \fIASYNC_get_wait_ctx()\fR,
\&\fIASYNC_block_pause()\fR, \fIASYNC_unblock_pause()\fR and \fIASYNC_is_capable()\fR were first
added to OpenSSL 1.1.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2015\-2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

41
secure/lib/libcrypto/man/blowfish.3 → secure/lib/libcrypto/man/BF_encrypt.3
View file

@ -128,15 +128,14 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "blowfish 3"
.TH blowfish 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "BF_ENCRYPT 3"
.TH BF_ENCRYPT 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
blowfish, BF_set_key, BF_encrypt, BF_decrypt, BF_ecb_encrypt, BF_cbc_encrypt,
BF_cfb64_encrypt, BF_ofb64_encrypt, BF_options \- Blowfish encryption
BF_set_key, BF_encrypt, BF_decrypt, BF_ecb_encrypt, BF_cbc_encrypt, BF_cfb64_encrypt, BF_ofb64_encrypt, BF_options \- Blowfish encryption
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
@ -145,18 +144,20 @@ BF_cfb64_encrypt, BF_ofb64_encrypt, BF_options \- Blowfish encryption
\& 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);
\& BF_KEY *key, int enc);
\& void BF_cbc_encrypt(const unsigned char *in, unsigned char *out,
\& long length, BF_KEY *schedule, unsigned char *ivec, int enc);
\& long length, BF_KEY *schedule,
\& unsigned char *ivec, int enc);
\& void BF_cfb64_encrypt(const unsigned char *in, unsigned char *out,
\& long length, BF_KEY *schedule, unsigned char *ivec, int *num,
\& int enc);
\& long length, BF_KEY *schedule,
\& unsigned char *ivec, int *num, int enc);
\& void BF_ofb64_encrypt(const unsigned char *in, unsigned char *out,
\& long length, BF_KEY *schedule, unsigned char *ivec, int *num);
\& long length, BF_KEY *schedule,
\& unsigned char *ivec, int *num);
\& const char *BF_options(void);
\&
\& void BF_encrypt(BF_LONG *data,const BF_KEY *key);
\& void BF_decrypt(BF_LONG *data,const BF_KEY *key);
\& void BF_encrypt(BF_LONG *data, const BF_KEY *key);
\& void BF_decrypt(BF_LONG *data, const BF_KEY *key);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
@ -185,7 +186,7 @@ everything after the first 64 bits is ignored.
.PP
The mode functions \fIBF_cbc_encrypt()\fR, \fIBF_cfb64_encrypt()\fR and \fIBF_ofb64_encrypt()\fR
all operate on variable length data. They all take an initialization vector
\&\fBivec\fR which needs to be passed along into the next call of the same function
\&\fBivec\fR which needs to be passed along into the next call of the same function
for the same message. \fBivec\fR 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 \s-1SSH,\s0 where
@ -228,11 +229,17 @@ None of the functions presented here return any value.
.SH "NOTE"
.IX Header "NOTE"
Applications should use the higher level functions
\&\fIEVP_EncryptInit\fR\|(3) etc. instead of calling the
blowfish functions directly.
\&\fIEVP_EncryptInit\fR\|(3) etc. instead of calling these
functions directly.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIEVP_EncryptInit\fR\|(3),
\&\fIdes_modes\fR\|(7)
.SH "HISTORY"
.IX Header "HISTORY"
The Blowfish functions are available in all versions of SSLeay and OpenSSL.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

249
secure/lib/libcrypto/man/BIO_ADDR.3 Normal file
View file

@ -0,0 +1,249 @@
.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BIO_ADDR 3"
.TH BIO_ADDR 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "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
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& #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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \fB\s-1BIO_ADDR\s0\fR type is a wrapper around all types of socket
addresses that OpenSSL deals with, currently transparently
supporting \s-1AF_INET, AF_INET6\s0 and \s-1AF_UNIX\s0 according to what's
available on the platform at hand.
.PP
\&\fIBIO_ADDR_new()\fR creates a new unfilled \fB\s-1BIO_ADDR\s0\fR, to be used
with routines that will fill it with information, such as
\&\fIBIO_accept_ex()\fR.
.PP
\&\fIBIO_ADDR_free()\fR frees a \fB\s-1BIO_ADDR\s0\fR created with \fIBIO_ADDR_new()\fR.
.PP
\&\fIBIO_ADDR_clear()\fR clears any data held within the provided \fB\s-1BIO_ADDR\s0\fR and sets
it back to an uninitialised state.
.PP
\&\fIBIO_ADDR_rawmake()\fR takes a protocol \fBfamily\fR, an byte array of
size \fBwherelen\fR with an address in network byte order pointed at
by \fBwhere\fR and a port number in network byte order in \fBport\fR (except
for the \fB\s-1AF_UNIX\s0\fR protocol family, where \fBport\fR is meaningless and
therefore ignored) and populates the given \fB\s-1BIO_ADDR\s0\fR with them.
In case this creates a \fB\s-1AF_UNIX\s0\fR \fB\s-1BIO_ADDR\s0\fR, \fBwherelen\fR is expected
to be the length of the path string (not including the terminating
\&\s-1NUL,\s0 such as the result of a call to \fIstrlen()\fR).
\&\fIRead on about the addresses in \*(L"\s-1RAW ADDRESSES\*(R"\s0 below\fR.
.PP
\&\fIBIO_ADDR_family()\fR returns the protocol family of the given
\&\fB\s-1BIO_ADDR\s0\fR. The possible non-error results are one of the
constants \s-1AF_INET, AF_INET6\s0 and \s-1AF_UNIX.\s0 It will also return \s-1AF_UNSPEC\s0 if the
\&\s-1BIO_ADDR\s0 has not been initialised.
.PP
\&\fIBIO_ADDR_rawaddress()\fR will write the raw address of the given
\&\fB\s-1BIO_ADDR\s0\fR in the area pointed at by \fBp\fR if \fBp\fR is non-NULL,
and will set \fB*l\fR to be the amount of bytes the raw address
takes up if \fBl\fR is non-NULL.
A technique to only find out the size of the address is a call
with \fBp\fR set to \fB\s-1NULL\s0\fR. The raw address will be in network byte
order, most significant byte first.
In case this is a \fB\s-1AF_UNIX\s0\fR \fB\s-1BIO_ADDR\s0\fR, \fBl\fR gets the length of the
path string (not including the terminating \s-1NUL,\s0 such as the result of
a call to \fIstrlen()\fR).
\&\fIRead on about the addresses in \*(L"\s-1RAW ADDRESSES\*(R"\s0 below\fR.
.PP
\&\fIBIO_ADDR_rawport()\fR returns the raw port of the given \fB\s-1BIO_ADDR\s0\fR.
The raw port will be in network byte order.
.PP
\&\fIBIO_ADDR_hostname_string()\fR returns a character string with the
hostname of the given \fB\s-1BIO_ADDR\s0\fR. If \fBnumeric\fR is 1, the string
will contain the numerical form of the address. This only works for
\&\fB\s-1BIO_ADDR\s0\fR of the protocol families \s-1AF_INET\s0 and \s-1AF_INET6.\s0 The
returned string has been allocated on the heap and must be freed
with \fIOPENSSL_free()\fR.
.PP
\&\fIBIO_ADDR_service_string()\fR returns a character string with the
service name of the port of the given \fB\s-1BIO_ADDR\s0\fR. If \fBnumeric\fR
is 1, the string will contain the port number. This only works
for \fB\s-1BIO_ADDR\s0\fR of the protocol families \s-1AF_INET\s0 and \s-1AF_INET6.\s0 The
returned string has been allocated on the heap and must be freed
with \fIOPENSSL_free()\fR.
.PP
\&\fIBIO_ADDR_path_string()\fR returns a character string with the path
of the given \fB\s-1BIO_ADDR\s0\fR. This only works for \fB\s-1BIO_ADDR\s0\fR of the
protocol family \s-1AF_UNIX.\s0 The returned string has been allocated
on the heap and must be freed with \fIOPENSSL_free()\fR.
.SH "RAW ADDRESSES"
.IX Header "RAW ADDRESSES"
Both \fIBIO_ADDR_rawmake()\fR and \fIBIO_ADDR_rawaddress()\fR take a pointer to a
network byte order address of a specific site. Internally, those are
treated as a pointer to \fBstruct in_addr\fR (for \fB\s-1AF_INET\s0\fR), \fBstruct
in6_addr\fR (for \fB\s-1AF_INET6\s0\fR) or \fBchar *\fR (for \fB\s-1AF_UNIX\s0\fR), all
depending on the protocol family the address is for.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
The string producing functions \fIBIO_ADDR_hostname_string()\fR,
\&\fIBIO_ADDR_service_string()\fR and \fIBIO_ADDR_path_string()\fR will
return \fB\s-1NULL\s0\fR on error and leave an error indication on the
OpenSSL error stack.
.PP
All other functions described here return 0 or \fB\s-1NULL\s0\fR when the
information they should return isn't available.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIBIO_connect\fR\|(3), \fIBIO_s_connect\fR\|(3)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

235
secure/lib/libcrypto/man/BIO_ADDRINFO.3 Normal file
View file

@ -0,0 +1,235 @@
.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BIO_ADDRINFO 3"
.TH BIO_ADDRINFO 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "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
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& #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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \fB\s-1BIO_ADDRINFO\s0\fR type is a wrapper for address information
types provided on your platform.
.PP
\&\fB\s-1BIO_ADDRINFO\s0\fR normally forms a chain of several that can be
picked at one by one.
.PP
\&\fIBIO_lookup_ex()\fR looks up a specified \fBhost\fR and \fBservice\fR, and
uses \fBlookup_type\fR to determine what the default address should
be if \fBhost\fR is \fB\s-1NULL\s0\fR. \fBfamily\fR, \fBsocktype\fR and \fBprotocol\fR are used to
determine what protocol family, socket type and protocol should be used for
the lookup. \fBfamily\fR can be any of \s-1AF_INET, AF_INET6, AF_UNIX\s0 and
\&\s-1AF_UNSPEC.\s0 \fBsocktype\fR can be \s-1SOCK_STREAM, SOCK_DGRAM\s0 or 0. Specifying 0
indicates that any type can be used. \fBprotocol\fR specifies a protocol such as
\&\s-1IPPROTO_TCP, IPPROTO_UDP\s0 or \s-1IPPORTO_SCTP.\s0 If set to 0 than any protocol can be
used. \fBres\fR points at a pointer to hold the start of a \fB\s-1BIO_ADDRINFO\s0\fR
chain.
.PP
For the family \fB\s-1AF_UNIX\s0\fR, \fIBIO_lookup_ex()\fR will ignore the \fBservice\fR
parameter and expects the \fBnode\fR parameter to hold the path to the
socket file.
.PP
\&\fIBIO_lookup()\fR does the same as \fIBIO_lookup_ex()\fR but does not provide the ability
to select based on the protocol (any protocol may be returned).
.PP
\&\fIBIO_ADDRINFO_family()\fR returns the family of the given
\&\fB\s-1BIO_ADDRINFO\s0\fR. The result will be one of the constants
\&\s-1AF_INET, AF_INET6\s0 and \s-1AF_UNIX.\s0
.PP
\&\fIBIO_ADDRINFO_socktype()\fR returns the socket type of the given
\&\fB\s-1BIO_ADDRINFO\s0\fR. The result will be one of the constants
\&\s-1SOCK_STREAM\s0 and \s-1SOCK_DGRAM.\s0
.PP
\&\fIBIO_ADDRINFO_protocol()\fR returns the protocol id of the given
\&\fB\s-1BIO_ADDRINFO\s0\fR. The result will be one of the constants
\&\s-1IPPROTO_TCP\s0 and \s-1IPPROTO_UDP.\s0
.PP
\&\fIBIO_ADDRINFO_address()\fR returns the underlying \fB\s-1BIO_ADDR\s0\fR
of the given \fB\s-1BIO_ADDRINFO\s0\fR.
.PP
\&\fIBIO_ADDRINFO_next()\fR returns the next \fB\s-1BIO_ADDRINFO\s0\fR in the chain
from the given one.
.PP
\&\fIBIO_ADDRINFO_free()\fR frees the chain of \fB\s-1BIO_ADDRINFO\s0\fR starting
with the given one.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fIBIO_lookup_ex()\fR and \fIBIO_lookup()\fR return 1 on success and 0 when an error
occurred, and will leave an error indication on the OpenSSL error stack in that
case.
.PP
All other functions described here return 0 or \fB\s-1NULL\s0\fR when the
information they should return isn't available.
.SH "NOTES"
.IX Header "NOTES"
The \fIBIO_lookup_ex()\fR implementation uses the platform provided \fIgetaddrinfo()\fR
function. On Linux it is known that specifying 0 for the protocol will not
return any \s-1SCTP\s0 based addresses when calling \fIgetaddrinfo()\fR. Therefore if an \s-1SCTP\s0
address is required then the \fBprotocol\fR parameter to \fIBIO_lookup_ex()\fR should be
explicitly set to \s-1IPPROTO_SCTP.\s0 The same may be true on other platforms.
.SH "HISTORY"
.IX Header "HISTORY"
The \fIBIO_lookup_ex()\fR function was added in OpenSSL 1.1.1.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2016\-2017 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

236
secure/lib/libcrypto/man/BIO_connect.3 Normal file
View file

@ -0,0 +1,236 @@
.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BIO_CONNECT 3"
.TH BIO_CONNECT 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
BIO_socket, BIO_bind, BIO_connect, BIO_listen, BIO_accept_ex, BIO_closesocket \- BIO socket communication setup routines
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fIBIO_socket()\fR creates a socket in the domain \fBdomain\fR, of type
\&\fBsocktype\fR and \fBprotocol\fR. Socket \fBoptions\fR are currently unused,
but is present for future use.
.PP
\&\fIBIO_bind()\fR binds the source address and service to a socket and
may be useful before calling \fIBIO_connect()\fR. The options may include
\&\fB\s-1BIO_SOCK_REUSADDR\s0\fR, which is described in \*(L"\s-1FLAGS\*(R"\s0 below.
.PP
\&\fIBIO_connect()\fR connects \fBsock\fR to the address and service given by
\&\fBaddr\fR. Connection \fBoptions\fR may be zero or any combination of
\&\fB\s-1BIO_SOCK_KEEPALIVE\s0\fR, \fB\s-1BIO_SOCK_NONBLOCK\s0\fR and \fB\s-1BIO_SOCK_NODELAY\s0\fR.
The flags are described in \*(L"\s-1FLAGS\*(R"\s0 below.
.PP
\&\fIBIO_listen()\fR has \fBsock\fR start listening on the address and service
given by \fBaddr\fR. Connection \fBoptions\fR may be zero or any
combination of \fB\s-1BIO_SOCK_KEEPALIVE\s0\fR, \fB\s-1BIO_SOCK_NONBLOCK\s0\fR,
\&\fB\s-1BIO_SOCK_NODELAY\s0\fR, \fB\s-1BIO_SOCK_REUSEADDR\s0\fR and \fB\s-1BIO_SOCK_V6_ONLY\s0\fR.
The flags are described in \*(L"\s-1FLAGS\*(R"\s0 below.
.PP
\&\fIBIO_accept_ex()\fR waits for an incoming connections on the given
socket \fBaccept_sock\fR. When it gets a connection, the address and
port of the peer gets stored in \fBpeer\fR if that one is non-NULL.
Accept \fBoptions\fR may be zero or \fB\s-1BIO_SOCK_NONBLOCK\s0\fR, and is applied
on the accepted socket. The flags are described in \*(L"\s-1FLAGS\*(R"\s0 below.
.PP
\&\fIBIO_closesocket()\fR closes \fBsock\fR.
.SH "FLAGS"
.IX Header "FLAGS"
.IP "\s-1BIO_SOCK_KEEPALIVE\s0" 4
.IX Item "BIO_SOCK_KEEPALIVE"
Enables regular sending of keep-alive messages.
.IP "\s-1BIO_SOCK_NONBLOCK\s0" 4
.IX Item "BIO_SOCK_NONBLOCK"
Sets the socket to non-blocking mode.
.IP "\s-1BIO_SOCK_NODELAY\s0" 4
.IX Item "BIO_SOCK_NODELAY"
Corresponds to \fB\s-1TCP_NODELAY\s0\fR, 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.
.IP "\s-1BIO_SOCK_REUSEADDR\s0" 4
.IX Item "BIO_SOCK_REUSEADDR"
Try to reuse the address and port combination for a recently closed
port.
.IP "\s-1BIO_SOCK_V6_ONLY\s0" 4
.IX Item "BIO_SOCK_V6_ONLY"
When creating an IPv6 socket, make it only listen for IPv6 addresses
and not IPv4 addresses mapped to IPv6.
.PP
These flags are bit flags, so they are to be combined with the
\&\f(CW\*(C`|\*(C'\fR operator, for example:
.PP
.Vb 1
\& BIO_connect(sock, addr, BIO_SOCK_KEEPALIVE | BIO_SOCK_NONBLOCK);
.Ve
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fIBIO_socket()\fR returns the socket number on success or \fB\s-1INVALID_SOCKET\s0\fR
(\-1) on error. When an error has occurred, the OpenSSL error stack
will hold the error data and errno has the system error.
.PP
\&\fIBIO_bind()\fR, \fIBIO_connect()\fR and \fIBIO_listen()\fR 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.
.PP
\&\fIBIO_accept_ex()\fR returns the accepted socket on success or
\&\fB\s-1INVALID_SOCKET\s0\fR (\-1) on error. When an error has occurred, the
OpenSSL error stack will hold the error data and errno has the system
error.
.SH "HISTORY"
.IX Header "HISTORY"
\&\fIBIO_gethostname()\fR, \fIBIO_get_port()\fR, \fIBIO_get_host_ip()\fR,
\&\fIBIO_get_accept_socket()\fR and \fIBIO_accept()\fR were deprecated in
OpenSSL 1.1.0. Use the functions described above instead.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1\fIBIO_ADDR\s0\fR\|(3)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2016\-2018 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

40
secure/lib/libcrypto/man/BIO_ctrl.3
View file

@ -128,43 +128,40 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BIO_ctrl 3"
.TH BIO_ctrl 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "BIO_CTRL 3"
.TH BIO_CTRL 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
BIO_ctrl, BIO_callback_ctrl, BIO_ptr_ctrl, BIO_int_ctrl, BIO_reset,
BIO_seek, BIO_tell, BIO_flush, BIO_eof, BIO_set_close, BIO_get_close,
BIO_pending, BIO_wpending, BIO_ctrl_pending, BIO_ctrl_wpending,
BIO_get_info_callback, BIO_set_info_callback \- BIO control operations
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
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bio.h>
\&
\& long BIO_ctrl(BIO *bp,int cmd,long larg,void *parg);
\& long BIO_callback_ctrl(BIO *b, int cmd, void (*fp)(struct bio_st *, int, const char *, int, long, long));
\& char * BIO_ptr_ctrl(BIO *bp,int cmd,long larg);
\& long BIO_int_ctrl(BIO *bp,int cmd,long larg,int iarg);
\& typedef 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_set_close(BIO *b, long flag);
\& int BIO_get_close(BIO *b);
\& int BIO_pending(BIO *b);
\& int BIO_wpending(BIO *b);
\& size_t BIO_ctrl_pending(BIO *b);
\& size_t BIO_ctrl_wpending(BIO *b);
\&
\& int BIO_get_info_callback(BIO *b,bio_info_cb **cbp);
\& int BIO_set_info_callback(BIO *b,bio_info_cb *cb);
\&
\& typedef void bio_info_cb(BIO *b, int oper, const char *ptr, int arg1, long arg2, long arg3);
\& int BIO_get_info_callback(BIO *b, BIO_info_cb **cbp);
\& int BIO_set_info_callback(BIO *b, BIO_info_cb *cb);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
@ -225,7 +222,7 @@ return the amount of pending data.
.SH "NOTES"
.IX Header "NOTES"
\&\fIBIO_flush()\fR, because it can write data may return 0 or \-1 indicating
that the call should be retried later in a similar manner to \fIBIO_write()\fR.
that the call should be retried later in a similar manner to \fIBIO_write_ex()\fR.
The \fIBIO_should_retry()\fR call should be used and appropriate action taken
is the call fails.
.PP
@ -252,6 +249,11 @@ 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 \s-1EOF\s0 has not been reached and in
the case of \fIBIO_seek()\fR on a file \s-1BIO\s0 for a successful operation.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1TBA\s0
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

21
secure/lib/libcrypto/man/BIO_f_base64.3
View file

@ -128,8 +128,8 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BIO_f_base64 3"
.TH BIO_f_base64 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "BIO_F_BASE64 3"
.TH BIO_F_BASE64 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
@ -142,7 +142,7 @@ BIO_f_base64 \- base64 BIO filter
\& #include <openssl/bio.h>
\& #include <openssl/evp.h>
\&
\& BIO_METHOD * BIO_f_base64(void);
\& const BIO_METHOD *BIO_f_base64(void);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
@ -196,8 +196,8 @@ data to standard output:
\& bio = BIO_new_fp(stdin, BIO_NOCLOSE);
\& bio_out = BIO_new_fp(stdout, BIO_NOCLOSE);
\& BIO_push(b64, bio);
\& while((inlen = BIO_read(b64, inbuf, 512)) > 0)
\& BIO_write(bio_out, inbuf, inlen);
\& while ((inlen = BIO_read(b64, inbuf, 512)) > 0)
\& BIO_write(bio_out, inbuf, inlen);
\&
\& BIO_flush(bio_out);
\& BIO_free_all(b64);
@ -209,6 +209,11 @@ data following the base64 encoded block to be misinterpreted.
.PP
There should be some way of specifying a test that the \s-1BIO\s0 can perform
to reliably determine \s-1EOF\s0 (for example a \s-1MIME\s0 boundary).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1TBA\s0
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

35
secure/lib/libcrypto/man/BIO_f_buffer.3
View file

@ -128,26 +128,26 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BIO_f_buffer 3"
.TH BIO_f_buffer 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "BIO_F_BUFFER 3"
.TH BIO_F_BUFFER 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
BIO_f_buffer \- buffering BIO
BIO_get_buffer_num_lines, BIO_set_read_buffer_size, BIO_set_write_buffer_size, BIO_set_buffer_size, BIO_set_buffer_read_data, BIO_f_buffer \&\- buffering BIO
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bio.h>
\&
\& BIO_METHOD * BIO_f_buffer(void);
\& const BIO_METHOD *BIO_f_buffer(void);
\&
\& #define BIO_get_buffer_num_lines(b) BIO_ctrl(b,BIO_C_GET_BUFF_NUM_LINES,0,NULL)
\& #define BIO_set_read_buffer_size(b,size) BIO_int_ctrl(b,BIO_C_SET_BUFF_SIZE,size,0)
\& #define BIO_set_write_buffer_size(b,size) BIO_int_ctrl(b,BIO_C_SET_BUFF_SIZE,size,1)
\& #define BIO_set_buffer_size(b,size) BIO_ctrl(b,BIO_C_SET_BUFF_SIZE,size,NULL)
\& #define BIO_set_buffer_read_data(b,buf,num) BIO_ctrl(b,BIO_C_SET_BUFF_READ_DATA,num,buf)
\& long BIO_get_buffer_num_lines(BIO *b);
\& long BIO_set_read_buffer_size(BIO *b, long size);
\& long BIO_set_write_buffer_size(BIO *b, long size);
\& long BIO_set_buffer_size(BIO *b, long size);
\& long BIO_set_buffer_read_data(BIO *b, void *buf, long num);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
@ -173,7 +173,9 @@ bytes of \fBbuf\fR. If \fBnum\fR is larger than the current buffer size the buff
is expanded.
.SH "NOTES"
.IX Header "NOTES"
Buffering BIOs implement \fIBIO_gets()\fR by using \fIBIO_read()\fR operations on the
These functions, other than \fIBIO_f_buffer()\fR, are implemented as macros.
.PP
Buffering BIOs implement \fIBIO_gets()\fR by using \fIBIO_read_ex()\fR operations on the
next \s-1BIO\s0 in the chain. By prepending a buffering \s-1BIO\s0 to a chain it is therefore
possible to provide \fIBIO_gets()\fR functionality if the following BIOs do not
support it (for example \s-1SSL\s0 BIOs).
@ -196,9 +198,16 @@ return 1 if the buffer was successfully resized or 0 for failure.
there was an error.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1\fIBIO\s0\fR\|(3),
\&\fIbio\fR\|(7),
\&\fIBIO_reset\fR\|(3),
\&\fIBIO_flush\fR\|(3),
\&\fIBIO_pop\fR\|(3),
\&\fIBIO_ctrl\fR\|(3),
\&\fIBIO_int_ctrl\fR\|(3)
\&\fIBIO_ctrl\fR\|(3).
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

26
secure/lib/libcrypto/man/BIO_f_cipher.3
View file

@ -128,8 +128,8 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BIO_f_cipher 3"
.TH BIO_f_cipher 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "BIO_F_CIPHER 3"
.TH BIO_F_CIPHER 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
@ -142,9 +142,9 @@ BIO_f_cipher, BIO_set_cipher, BIO_get_cipher_status, BIO_get_cipher_ctx \- ciphe
\& #include <openssl/bio.h>
\& #include <openssl/evp.h>
\&
\& BIO_METHOD * BIO_f_cipher(void);
\& void BIO_set_cipher(BIO *b,const EVP_CIPHER *cipher,
\& unsigned char *key, unsigned char *iv, int enc);
\& const BIO_METHOD *BIO_f_cipher(void);
\& void BIO_set_cipher(BIO *b, const EVP_CIPHER *cipher,
\& unsigned char *key, unsigned char *iv, int enc);
\& int BIO_get_cipher_status(BIO *b)
\& int BIO_get_cipher_ctx(BIO *b, EVP_CIPHER_CTX **pctx)
.Ve
@ -180,7 +180,7 @@ When encrypting \fIBIO_flush()\fR \fBmust\fR be called to flush the final block
through the \s-1BIO.\s0 If it is not then the final block will fail a subsequent
decrypt.
.PP
When decrypting an error on the final block is signalled by a zero
When decrypting an error on the final block is signaled by a zero
return value from the read operation. A successful decrypt followed
by \s-1EOF\s0 will also return zero for the final read. \fIBIO_get_cipher_status()\fR
should be called to determine if the decrypt was successful.
@ -197,9 +197,11 @@ be achieved by preceding the cipher \s-1BIO\s0 with a buffering \s-1BIO.\s0
for failure.
.PP
\&\fIBIO_get_cipher_ctx()\fR currently always returns 1.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
\&\s-1TBA\s0
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1TBA\s0
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

77
secure/lib/libcrypto/man/BIO_f_md.3
View file

@ -128,8 +128,8 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BIO_f_md 3"
.TH BIO_f_md 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "BIO_F_MD 3"
.TH BIO_F_MD 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
@ -142,10 +142,10 @@ BIO_f_md, BIO_set_md, BIO_get_md, BIO_get_md_ctx \- message digest BIO filter
\& #include <openssl/bio.h>
\& #include <openssl/evp.h>
\&
\& BIO_METHOD * BIO_f_md(void);
\& int BIO_set_md(BIO *b,EVP_MD *md);
\& int BIO_get_md(BIO *b,EVP_MD **mdp);
\& int BIO_get_md_ctx(BIO *b,EVP_MD_CTX **mdcp);
\& const BIO_METHOD *BIO_f_md(void);
\& int BIO_set_md(BIO *b, EVP_MD *md);
\& int BIO_get_md(BIO *b, EVP_MD **mdp);
\& int BIO_get_md_ctx(BIO *b, EVP_MD_CTX **mdcp);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
@ -154,8 +154,8 @@ BIO_f_md, BIO_set_md, BIO_get_md, BIO_get_md_ctx \- message digest BIO filter
for the digest routines \fIEVP_DigestInit()\fR, \fIEVP_DigestUpdate()\fR
and \fIEVP_DigestFinal()\fR.
.PP
Any data written or read through a digest \s-1BIO\s0 using \fIBIO_read()\fR and
\&\fIBIO_write()\fR is digested.
Any data written or read through a digest \s-1BIO\s0 using \fIBIO_read_ex()\fR and
\&\fIBIO_write_ex()\fR is digested.
.PP
\&\fIBIO_gets()\fR, if its \fBsize\fR parameter is large enough finishes the
digest calculation and returns the digest value. \fIBIO_puts()\fR is
@ -190,10 +190,8 @@ If an application needs to call \fIBIO_gets()\fR or \fIBIO_puts()\fR through
a chain containing digest BIOs then this can be done by prepending
a buffering \s-1BIO.\s0
.PP
Before OpenSSL 1.0.0 the call to \fIBIO_get_md_ctx()\fR would only work if the \s-1BIO\s0
had been initialized for example by calling \fIBIO_set_md()\fR ). In OpenSSL
1.0.0 and later the context is always returned and the \s-1BIO\s0 is state is set
to initialized. This allows applications to initialize the context externally
Calling \fIBIO_get_md_ctx()\fR will return the context and initialize the \s-1BIO\s0
state. This allows applications to initialize the context externally
if the standard calls such as \fIBIO_set_md()\fR are not sufficiently flexible.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
@ -207,13 +205,15 @@ The following example creates a \s-1BIO\s0 chain containing an \s-1SHA1\s0 and \
digest \s-1BIO\s0 and passes the string \*(L"Hello World\*(R" through it. Error
checking has been omitted for clarity.
.PP
.Vb 10
.Vb 2
\& 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
\& /*
\& * 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);
@ -226,10 +226,11 @@ checking has been omitted for clarity.
.PP
The next example digests data by reading through a chain instead:
.PP
.Vb 10
.Vb 3
\& 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());
@ -238,31 +239,34 @@ The next example digests data by reading through a chain instead:
\& BIO_set_md(mdtmp, EVP_md5());
\& bio = BIO_push(mdtmp, bio);
\& do {
\& rdlen = BIO_read(bio, buf, sizeof(buf));
\& /* Might want to do something with the data here */
\& } while(rdlen > 0);
\& rdlen = BIO_read(bio, buf, sizeof(buf));
\& /* Might want to do something with the data here */
\& } while (rdlen > 0);
.Ve
.PP
This next example retrieves the message digests from a \s-1BIO\s0 chain and
outputs them. This could be used with the examples above.
.PP
.Vb 10
.Vb 4
\& 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("\en");
\& mdtmp = BIO_next(mdtmp);
\& } while(mdtmp);
\& 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("\en");
\& mdtmp = BIO_next(mdtmp);
\& } while (mdtmp);
\&
\& BIO_free_all(bio);
.Ve
@ -273,6 +277,15 @@ The lack of support for \fIBIO_puts()\fR and the non standard behaviour of
and \fIBIO_puts()\fR should be passed to the next \s-1BIO\s0 in the chain and digest
the data passed through and that digests should be retrieved using a
separate \fIBIO_ctrl()\fR call.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1TBA\s0
.SH "HISTORY"
.IX Header "HISTORY"
Before OpenSSL 1.0.0., the call to \fIBIO_get_md_ctx()\fR would only work if the
\&\s-1BIO\s0 was initialized first.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

17
secure/lib/libcrypto/man/BIO_f_null.3
View file

@ -128,8 +128,8 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BIO_f_null 3"
.TH BIO_f_null 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "BIO_F_NULL 3"
.TH BIO_F_NULL 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
@ -141,7 +141,7 @@ BIO_f_null \- null filter
.Vb 1
\& #include <openssl/bio.h>
\&
\& BIO_METHOD * BIO_f_null(void);
\& const BIO_METHOD *BIO_f_null(void);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
@ -157,6 +157,11 @@ As may be apparent a null filter \s-1BIO\s0 is not particularly useful.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fIBIO_f_null()\fR returns the null filter \s-1BIO\s0 method.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1TBA\s0
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

241
secure/lib/libcrypto/man/BIO_f_ssl.3
View file

@ -128,42 +128,36 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BIO_f_ssl 3"
.TH BIO_f_ssl 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "BIO_F_SSL 3"
.TH BIO_F_SSL 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
BIO_f_ssl, BIO_set_ssl, BIO_get_ssl, BIO_set_ssl_mode, BIO_set_ssl_renegotiate_bytes,
BIO_get_num_renegotiates, BIO_set_ssl_renegotiate_timeout, BIO_new_ssl,
BIO_new_ssl_connect, BIO_new_buffer_ssl_connect, BIO_ssl_copy_session_id,
BIO_ssl_shutdown \- SSL BIO
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
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& #include <openssl/bio.h>
\& #include <openssl/ssl.h>
\&
\& BIO_METHOD *BIO_f_ssl(void);
\& const BIO_METHOD *BIO_f_ssl(void);
\&
\& #define BIO_set_ssl(b,ssl,c) BIO_ctrl(b,BIO_C_SET_SSL,c,(char *)ssl)
\& #define BIO_get_ssl(b,sslp) BIO_ctrl(b,BIO_C_GET_SSL,0,(char *)sslp)
\& #define BIO_set_ssl_mode(b,client) BIO_ctrl(b,BIO_C_SSL_MODE,client,NULL)
\& #define BIO_set_ssl_renegotiate_bytes(b,num) \e
\& BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_BYTES,num,NULL);
\& #define BIO_set_ssl_renegotiate_timeout(b,seconds) \e
\& BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_TIMEOUT,seconds,NULL);
\& #define BIO_get_num_renegotiates(b) \e
\& BIO_ctrl(b,BIO_C_SET_SSL_NUM_RENEGOTIATES,0,NULL);
\& long BIO_set_ssl(BIO *b, SSL *ssl, long c);
\& long BIO_get_ssl(BIO *b, SSL **sslp);
\& long BIO_set_ssl_mode(BIO *b, long client);
\& long BIO_set_ssl_renegotiate_bytes(BIO *b, long num);
\& long BIO_set_ssl_renegotiate_timeout(BIO *b, long seconds);
\& long BIO_get_num_renegotiates(BIO *b);
\&
\& BIO *BIO_new_ssl(SSL_CTX *ctx,int client);
\& BIO *BIO_new_ssl(SSL_CTX *ctx, int client);
\& BIO *BIO_new_ssl_connect(SSL_CTX *ctx);
\& BIO *BIO_new_buffer_ssl_connect(SSL_CTX *ctx);
\& int BIO_ssl_copy_session_id(BIO *to,BIO *from);
\& int BIO_ssl_copy_session_id(BIO *to, BIO *from);
\& void BIO_ssl_shutdown(BIO *bio);
\&
\& #define BIO_do_handshake(b) BIO_ctrl(b,BIO_C_DO_STATE_MACHINE,0,NULL)
\& long BIO_do_handshake(BIO *b);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
@ -196,7 +190,7 @@ manipulated using the standard \s-1SSL\s0 library functions.
is 1 client mode is set. If \fBclient\fR is 0 server mode is set.
.PP
\&\fIBIO_set_ssl_renegotiate_bytes()\fR sets the renegotiate byte count
to \fBnum\fR. When set after every \fBnum\fR bytes of I/O (read and write)
to \fBnum\fR. When set after every \fBnum\fR bytes of I/O (read and write)
the \s-1SSL\s0 session is automatically renegotiated. \fBnum\fR must be at
least 512 bytes.
.PP
@ -217,7 +211,7 @@ client mode if \fBclient\fR is non zero.
of a buffering \s-1BIO,\s0 an \s-1SSL BIO\s0 (using \fBctx\fR) and a connect
\&\s-1BIO.\s0
.PP
\&\fIBIO_ssl_copy_session_id()\fR copies an \s-1SSL\s0 session id between
\&\fIBIO_ssl_copy_session_id()\fR copies an \s-1SSL\s0 session id between
\&\s-1BIO\s0 chains \fBfrom\fR and \fBto\fR. It does this by locating the
\&\s-1SSL\s0 BIOs in each chain and calling \fISSL_copy_session_id()\fR on
the internal \s-1SSL\s0 pointer.
@ -239,10 +233,10 @@ already been established this call has no effect.
\&\s-1SSL\s0 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 \fIBIO_read()\fR operation, one
renegotiation takes place during a \fIBIO_read_ex()\fR operation, one
case where this happens is when step up occurs.
.PP
In OpenSSL 0.9.6 and later the \s-1SSL\s0 flag \s-1SSL_AUTO_RETRY\s0 can be
The \s-1SSL\s0 flag \s-1SSL_AUTO_RETRY\s0 can be
set to disable this behaviour. That is when this flag is set
an \s-1SSL BIO\s0 using a blocking transport will never request a
retry.
@ -255,9 +249,10 @@ to locate the connect \s-1BIO\s0 first.
Applications do not have to call \fIBIO_do_handshake()\fR but may wish
to do so to separate the handshake process from other I/O
processing.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\s-1TBA\s0
.PP
\&\fIBIO_set_ssl()\fR, \fIBIO_get_ssl()\fR, \fIBIO_set_ssl_mode()\fR,
\&\fIBIO_set_ssl_renegotiate_bytes()\fR, \fIBIO_set_ssl_renegotiate_timeout()\fR,
\&\fIBIO_get_num_renegotiates()\fR, and \fIBIO_do_handshake()\fR are implemented as macros.
.SH "EXAMPLE"
.IX Header "EXAMPLE"
This \s-1SSL/TLS\s0 client example, attempts to retrieve a page from an
@ -271,57 +266,48 @@ unencrypted example in \fIBIO_s_connect\fR\|(3).
\& SSL_CTX *ctx;
\& SSL *ssl;
\&
\& ERR_load_crypto_strings();
\& ERR_load_SSL_strings();
\& OpenSSL_add_all_algorithms();
\& /* XXX Seed the PRNG if needed. */
\&
\& /* We would seed the PRNG here if the platform didn\*(Aqt
\& * do it automatically
\& */
\& ctx = SSL_CTX_new(TLS_client_method());
\&
\& ctx = SSL_CTX_new(SSLv23_client_method());
\&
\& /* We\*(Aqd normally set some stuff like the verify paths and
\& * mode here because as things stand this will connect to
\& * any server whose certificate is signed by any CA.
\& */
\& /* XXX Set verify paths and mode here. */
\&
\& sbio = BIO_new_ssl_connect(ctx);
\&
\& BIO_get_ssl(sbio, &ssl);
\&
\& if(!ssl) {
\& fprintf(stderr, "Can\*(Aqt locate SSL pointer\en");
\& /* whatever ... */
\& if (ssl == NULL) {
\& fprintf(stderr, "Can\*(Aqt locate SSL pointer\en");
\& ERR_print_errors_fp(stderr);
\& exit(1);
\& }
\&
\& /* Don\*(Aqt want any retries */
\& SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY);
\&
\& /* We might want to do other things with ssl here */
\& /* XXX We might want to do other things with ssl here */
\&
\& BIO_set_conn_hostname(sbio, "localhost:https");
\& /* An empty host part means the loopback address */
\& BIO_set_conn_hostname(sbio, ":https");
\&
\& out = BIO_new_fp(stdout, BIO_NOCLOSE);
\& if(BIO_do_connect(sbio) <= 0) {
\& fprintf(stderr, "Error connecting to server\en");
\& ERR_print_errors_fp(stderr);
\& /* whatever ... */
\& if (BIO_do_connect(sbio) <= 0) {
\& fprintf(stderr, "Error connecting to server\en");
\& ERR_print_errors_fp(stderr);
\& exit(1);
\& }
\& if (BIO_do_handshake(sbio) <= 0) {
\& fprintf(stderr, "Error establishing SSL connection\en");
\& ERR_print_errors_fp(stderr);
\& exit(1);
\& }
\&
\& if(BIO_do_handshake(sbio) <= 0) {
\& fprintf(stderr, "Error establishing SSL connection\en");
\& ERR_print_errors_fp(stderr);
\& /* whatever ... */
\& }
\&
\& /* Could examine ssl here to get connection info */
\& /* XXX Could examine ssl here to get connection info */
\&
\& BIO_puts(sbio, "GET / HTTP/1.0\en\en");
\& for(;;) {
\& len = BIO_read(sbio, tmpbuf, 1024);
\& if(len <= 0) break;
\& BIO_write(out, tmpbuf, len);
\& for (;;) {
\& len = BIO_read(sbio, tmpbuf, 1024);
\& if (len <= 0)
\& break;
\& BIO_write(out, tmpbuf, len);
\& }
\& BIO_free_all(sbio);
\& BIO_free(out);
@ -339,116 +325,107 @@ a client and also echoes the request to standard output.
\& SSL_CTX *ctx;
\& SSL *ssl;
\&
\& ERR_load_crypto_strings();
\& ERR_load_SSL_strings();
\& OpenSSL_add_all_algorithms();
\& /* XXX Seed the PRNG if needed. */
\&
\& /* Might seed PRNG here */
\&
\& ctx = SSL_CTX_new(SSLv23_server_method());
\&
\& if (!SSL_CTX_use_certificate_file(ctx,"server.pem",SSL_FILETYPE_PEM)
\& || !SSL_CTX_use_PrivateKey_file(ctx,"server.pem",SSL_FILETYPE_PEM)
\& || !SSL_CTX_check_private_key(ctx)) {
\&
\& fprintf(stderr, "Error setting up SSL_CTX\en");
\& ERR_print_errors_fp(stderr);
\& return 0;
\& ctx = SSL_CTX_new(TLS_server_method());
\& if (!SSL_CTX_use_certificate_file(ctx, "server.pem", SSL_FILETYPE_PEM)
\& || !SSL_CTX_use_PrivateKey_file(ctx, "server.pem", SSL_FILETYPE_PEM)
\& || !SSL_CTX_check_private_key(ctx)) {
\& fprintf(stderr, "Error setting up SSL_CTX\en");
\& ERR_print_errors_fp(stderr);
\& exit(1);
\& }
\&
\& /* Might do other things here like setting verify locations and
\& * DH and/or RSA temporary key callbacks
\& */
\& /* XXX Other things like set verify locations, EDH temp callbacks. */
\&
\& /* New SSL BIO setup as server */
\& sbio=BIO_new_ssl(ctx,0);
\&
\& sbio = BIO_new_ssl(ctx, 0);
\& BIO_get_ssl(sbio, &ssl);
\&
\& if(!ssl) {
\& fprintf(stderr, "Can\*(Aqt locate SSL pointer\en");
\& /* whatever ... */
\& if (ssl == NULL) {
\& fprintf(stderr, "Can\*(Aqt locate SSL pointer\en");
\& ERR_print_errors_fp(stderr);
\& exit(1);
\& }
\&
\& /* Don\*(Aqt want any retries */
\& SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY);
\&
\& /* Create the buffering BIO */
\&
\& bbio = BIO_new(BIO_f_buffer());
\&
\& /* Add to chain */
\& sbio = BIO_push(bbio, sbio);
\& acpt = BIO_new_accept("4433");
\&
\& acpt=BIO_new_accept("4433");
\&
\& /* By doing this when a new connection is established
\& /*
\& * By doing this when a new connection is established
\& * we automatically have sbio inserted into it. The
\& * BIO chain is now \*(Aqswallowed\*(Aq by the accept BIO and
\& * will be freed when the accept BIO is freed.
\& * will be freed when the accept BIO is freed.
\& */
\&
\& BIO_set_accept_bios(acpt,sbio);
\&
\& BIO_set_accept_bios(acpt, sbio);
\& out = BIO_new_fp(stdout, BIO_NOCLOSE);
\&
\& /* Setup accept BIO */
\& if(BIO_do_accept(acpt) <= 0) {
\& fprintf(stderr, "Error setting up accept BIO\en");
\& ERR_print_errors_fp(stderr);
\& return 0;
\& if (BIO_do_accept(acpt) <= 0) {
\& fprintf(stderr, "Error setting up accept BIO\en");
\& ERR_print_errors_fp(stderr);
\& exit(1);
\& }
\&
\& /* Now wait for incoming connection */
\& if(BIO_do_accept(acpt) <= 0) {
\& fprintf(stderr, "Error in connection\en");
\& ERR_print_errors_fp(stderr);
\& return 0;
\& }
\&
\& /* We only want one connection so remove and free
\& * accept BIO
\& */
\&
\& /* We only want one connection so remove and free accept BIO */
\& sbio = BIO_pop(acpt);
\&
\& BIO_free_all(acpt);
\&
\& if(BIO_do_handshake(sbio) <= 0) {
\& fprintf(stderr, "Error in SSL handshake\en");
\& ERR_print_errors_fp(stderr);
\& return 0;
\& if (BIO_do_handshake(sbio) <= 0) {
\& fprintf(stderr, "Error in SSL handshake\en");
\& ERR_print_errors_fp(stderr);
\& exit(1);
\& }
\&
\& BIO_puts(sbio, "HTTP/1.0 200 OK\er\enContent\-type: text/plain\er\en\er\en");
\& BIO_puts(sbio, "\er\enConnection Established\er\enRequest headers:\er\en");
\& BIO_puts(sbio, "\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\er\en");
\&
\& 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] == \*(Aq\er\*(Aq) || (tmpbuf[0] == \*(Aq\en\*(Aq)) break;
\& for (;;) {
\& len = BIO_gets(sbio, tmpbuf, 1024);
\& if (len <= 0)
\& break;
\& BIO_write(sbio, tmpbuf, len);
\& BIO_write(out, tmpbuf, len);
\& /* Look for blank line signifying end of headers*/
\& if (tmpbuf[0] == \*(Aq\er\*(Aq || tmpbuf[0] == \*(Aq\en\*(Aq)
\& break;
\& }
\&
\& BIO_puts(sbio, "\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\er\en");
\& BIO_puts(sbio, "\er\en");
\&
\& /* Since there is a buffering BIO present we had better flush it */
\& BIO_flush(sbio);
\&
\& BIO_free_all(sbio);
.Ve
.SH "BUGS"
.IX Header "BUGS"
In OpenSSL versions before 1.0.0 the \fIBIO_pop()\fR call was handled incorrectly,
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fIBIO_f_ssl()\fR returns the \s-1SSL\s0 \fB\s-1BIO_METHOD\s0\fR structure.
.PP
\&\fIBIO_set_ssl()\fR, \fIBIO_get_ssl()\fR, \fIBIO_set_ssl_mode()\fR, \fIBIO_set_ssl_renegotiate_bytes()\fR,
\&\fIBIO_set_ssl_renegotiate_timeout()\fR and \fIBIO_get_num_renegotiates()\fR return 1 on
success or a value which is less than or equal to 0 if an error occurred.
.PP
\&\fIBIO_new_ssl()\fR, \fIBIO_new_ssl_connect()\fR and \fIBIO_new_buffer_ssl_connect()\fR return
a valid \fB\s-1BIO\s0\fR structure on success or \fB\s-1NULL\s0\fR if an error occurred.
.PP
\&\fIBIO_ssl_copy_session_id()\fR returns 1 on success or 0 on error.
.PP
\&\fIBIO_do_handshake()\fR returns 1 if the connection was established successfully.
A zero or negative value is returned if the connection could not be established.
.SH "HISTORY"
.IX Header "HISTORY"
In OpenSSL before 1.0.0 the \fIBIO_pop()\fR call was handled incorrectly,
the I/O \s-1BIO\s0 reference count was incorrectly incremented (instead of
decremented) and dissociated with the \s-1SSL BIO\s0 even if the \s-1SSL BIO\s0 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 \s-1BIO.\s0
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1TBA\s0
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

84
secure/lib/libcrypto/man/BIO_find_type.3
View file

@ -128,8 +128,8 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BIO_find_type 3"
.TH BIO_find_type 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "BIO_FIND_TYPE 3"
.TH BIO_FIND_TYPE 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
@ -141,46 +141,23 @@ BIO_find_type, BIO_next, BIO_method_type \- BIO chain traversal
.Vb 1
\& #include <openssl/bio.h>
\&
\& BIO * BIO_find_type(BIO *b,int bio_type);
\& BIO * BIO_next(BIO *b);
\&
\& #define BIO_method_type(b) ((b)\->method\->type)
\&
\& #define BIO_TYPE_NONE 0
\& #define BIO_TYPE_MEM (1|0x0400)
\& #define BIO_TYPE_FILE (2|0x0400)
\&
\& #define BIO_TYPE_FD (4|0x0400|0x0100)
\& #define BIO_TYPE_SOCKET (5|0x0400|0x0100)
\& #define BIO_TYPE_NULL (6|0x0400)
\& #define BIO_TYPE_SSL (7|0x0200)
\& #define BIO_TYPE_MD (8|0x0200)
\& #define BIO_TYPE_BUFFER (9|0x0200)
\& #define BIO_TYPE_CIPHER (10|0x0200)
\& #define BIO_TYPE_BASE64 (11|0x0200)
\& #define BIO_TYPE_CONNECT (12|0x0400|0x0100)
\& #define BIO_TYPE_ACCEPT (13|0x0400|0x0100)
\& #define BIO_TYPE_PROXY_CLIENT (14|0x0200)
\& #define BIO_TYPE_PROXY_SERVER (15|0x0200)
\& #define BIO_TYPE_NBIO_TEST (16|0x0200)
\& #define BIO_TYPE_NULL_FILTER (17|0x0200)
\& #define BIO_TYPE_BER (18|0x0200)
\& #define BIO_TYPE_BIO (19|0x0400)
\&
\& #define BIO_TYPE_DESCRIPTOR 0x0100
\& #define BIO_TYPE_FILTER 0x0200
\& #define BIO_TYPE_SOURCE_SINK 0x0400
\& BIO *BIO_find_type(BIO *b, int bio_type);
\& BIO *BIO_next(BIO *b);
\& int BIO_method_type(const BIO *b);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \fIBIO_find_type()\fR searches for a \s-1BIO\s0 of a given type in a chain, starting
at \s-1BIO\s0 \fBb\fR. If \fBtype\fR is a specific type (such as \s-1BIO_TYPE_MEM\s0) then a search
at \s-1BIO\s0 \fBb\fR. If \fBtype\fR is a specific type (such as \fB\s-1BIO_TYPE_MEM\s0\fR) then a search
is made for a \s-1BIO\s0 of that type. If \fBtype\fR is a general type (such as
\&\fB\s-1BIO_TYPE_SOURCE_SINK\s0\fR) then the next matching \s-1BIO\s0 of the given general type is
searched for. \fIBIO_find_type()\fR returns the next matching \s-1BIO\s0 or \s-1NULL\s0 if none is
found.
.PP
Note: not all the \fBBIO_TYPE_*\fR types above have corresponding \s-1BIO\s0 implementations.
The following general types are defined:
\&\fB\s-1BIO_TYPE_DESCRIPTOR\s0\fR, \fB\s-1BIO_TYPE_FILTER\s0\fR, and \fB\s-1BIO_TYPE_SOURCE_SINK\s0\fR.
.PP
For a list of the specific types, see the \fBopenssl/bio.h\fR header file.
.PP
\&\fIBIO_next()\fR returns the next \s-1BIO\s0 in a chain. It can be used to traverse all BIOs
in a chain or used in conjunction with \fIBIO_find_type()\fR to find all BIOs of a
@ -194,36 +171,29 @@ certain type.
\&\fIBIO_next()\fR returns the next \s-1BIO\s0 in a chain.
.PP
\&\fIBIO_method_type()\fR returns the type of the \s-1BIO\s0 \fBb\fR.
.SH "NOTES"
.IX Header "NOTES"
\&\fIBIO_next()\fR was added to OpenSSL 0.9.6 to provide a 'clean' way to traverse a \s-1BIO\s0
chain or find multiple matches using \fIBIO_find_type()\fR. Previous versions had to
use:
.PP
.Vb 1
\& next = bio\->next_bio;
.Ve
.SH "BUGS"
.IX Header "BUGS"
\&\fIBIO_find_type()\fR in OpenSSL 0.9.5a and earlier could not be safely passed a
\&\s-1NULL\s0 pointer for the \fBb\fR argument.
.SH "EXAMPLE"
.IX Header "EXAMPLE"
Traverse a chain looking for digest BIOs:
.PP
.Vb 2
.Vb 1
\& 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_find_type(btmp, BIO_TYPE_MD);
\& if (btmp == NULL)
\& break; /* Not found */
\& /* btmp is a digest BIO, do something with it ...*/
\& ...
\&
\& btmp = BIO_next(btmp);
\& } while(btmp);
\& btmp = BIO_next(btmp);
\& } while (btmp);
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1TBA\s0
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

191
secure/lib/libcrypto/man/BIO_get_data.3 Normal file
View file

@ -0,0 +1,191 @@
.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BIO_GET_DATA 3"
.TH BIO_GET_DATA 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "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
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
These functions are mainly useful when implementing a custom \s-1BIO.\s0
.PP
The \fIBIO_set_data()\fR function associates the custom data pointed to by \fBptr\fR with
the \s-1BIO.\s0 This data can subsequently be retrieved via a call to \fIBIO_get_data()\fR.
This can be used by custom BIOs for storing implementation specific information.
.PP
The \fIBIO_set_init()\fR function sets the value of the \s-1BIO\s0's \*(L"init\*(R" flag to indicate
whether initialisation has been completed for this \s-1BIO\s0 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 \s-1BIO.\s0 For
some BIOs however, initialisation may not complete until after additional steps
have occurred (for example through calling custom ctrls). The \fIBIO_get_init()\fR
function returns the value of the \*(L"init\*(R" flag.
.PP
The \fIBIO_set_shutdown()\fR and \fIBIO_get_shutdown()\fR functions set and get the state of
this \s-1BIO\s0's shutdown (i.e. \s-1BIO_CLOSE\s0) flag. If set then the underlying resource
is also closed when the \s-1BIO\s0 is freed.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fIBIO_get_data()\fR returns a pointer to the implementation specific custom data
associated with this \s-1BIO,\s0 or \s-1NULL\s0 if none has been set.
.PP
\&\fIBIO_get_init()\fR returns the state of the \s-1BIO\s0's init flag.
.PP
\&\fIBIO_get_shutdown()\fR returns the stat of the \s-1BIO\s0's shutdown (i.e. \s-1BIO_CLOSE\s0) flag.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
bio, BIO_meth_new
.SH "HISTORY"
.IX Header "HISTORY"
The functions described here were added in OpenSSL 1.1.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

187
secure/lib/libcrypto/man/BIO_get_ex_new_index.3 Normal file
View file

@ -0,0 +1,187 @@
.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BIO_GET_EX_NEW_INDEX 3"
.TH BIO_GET_EX_NEW_INDEX 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "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
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
In the description here, \fI\s-1TYPE\s0\fR is used a placeholder
for any of the OpenSSL datatypes listed in
\&\fICRYPTO_get_ex_new_index\fR\|(3).
.PP
These functions handle application-specific data for OpenSSL data
structures.
.PP
\&\fITYPE_get_new_ex_index()\fR is a macro that calls \fICRYPTO_get_ex_new_index()\fR
with the correct \fBindex\fR value.
.PP
\&\fITYPE_set_ex_data()\fR is a function that calls \fICRYPTO_set_ex_data()\fR with
an offset into the opaque exdata part of the \s-1TYPE\s0 object.
.PP
\&\fITYPE_get_ex_data()\fR is a function that calls \fICRYPTO_get_ex_data()\fR with
an offset into the opaque exdata part of the \s-1TYPE\s0 object.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fITYPE_get_new_ex_index()\fR returns a new index on success or \-1 on error.
.PP
\&\fITYPE_set_ex_data()\fR returns 1 on success or 0 on error.
.PP
\&\fITYPE_get_ex_data()\fR returns the application data or \s-1NULL\s0 if an error occurred.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fICRYPTO_get_ex_new_index\fR\|(3).
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2015\-2018 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

284
secure/lib/libcrypto/man/BIO_meth_new.3 Normal file
View file

@ -0,0 +1,284 @@
.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BIO_METH_NEW 3"
.TH BIO_METH_NEW 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "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
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #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 *));
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \fB\s-1BIO_METHOD\s0\fR type is a structure used for the implementation of new \s-1BIO\s0
types. It provides a set of functions used by OpenSSL for the implementation
of the various \s-1BIO\s0 capabilities. See the bio page for more information.
.PP
\&\fIBIO_meth_new()\fR creates a new \fB\s-1BIO_METHOD\s0\fR structure. It should be given a
unique integer \fBtype\fR and a string that represents its \fBname\fR.
Use \fIBIO_get_new_index()\fR to get the value for \fBtype\fR.
.PP
The set of
standard OpenSSL provided \s-1BIO\s0 types is provided in \fBbio.h\fR. Some examples
include \fB\s-1BIO_TYPE_BUFFER\s0\fR and \fB\s-1BIO_TYPE_CIPHER\s0\fR. Filter BIOs should have a
type which have the \*(L"filter\*(R" bit set (\fB\s-1BIO_TYPE_FILTER\s0\fR). Source/sink BIOs
should have the \*(L"source/sink\*(R" bit set (\fB\s-1BIO_TYPE_SOURCE_SINK\s0\fR). File descriptor
based BIOs (e.g. socket, fd, connect, accept etc) should additionally have the
\&\*(L"descriptor\*(R" bit set (\fB\s-1BIO_TYPE_DESCRIPTOR\s0\fR). See the BIO_find_type page for
more information.
.PP
\&\fIBIO_meth_free()\fR destroys a \fB\s-1BIO_METHOD\s0\fR structure and frees up any memory
associated with it.
.PP
\&\fIBIO_meth_get_write_ex()\fR and \fIBIO_meth_set_write_ex()\fR get and set the function
used for writing arbitrary length data to the \s-1BIO\s0 respectively. This function
will be called in response to the application calling \fIBIO_write_ex()\fR or
\&\fIBIO_write()\fR. The parameters for the function have the same meaning as for
\&\fIBIO_write_ex()\fR. Older code may call \fIBIO_meth_get_write()\fR and
\&\fIBIO_meth_set_write()\fR instead. Applications should not call both
\&\fIBIO_meth_set_write_ex()\fR and \fIBIO_meth_set_write()\fR or call \fIBIO_meth_get_write()\fR
when the function was set with \fIBIO_meth_set_write_ex()\fR.
.PP
\&\fIBIO_meth_get_read_ex()\fR and \fIBIO_meth_set_read_ex()\fR get and set the function used
for reading arbitrary length data from the \s-1BIO\s0 respectively. This function will
be called in response to the application calling \fIBIO_read_ex()\fR or \fIBIO_read()\fR.
The parameters for the function have the same meaning as for \fIBIO_read_ex()\fR.
Older code may call \fIBIO_meth_get_read()\fR and \fIBIO_meth_set_read()\fR instead.
Applications should not call both \fIBIO_meth_set_read_ex()\fR and \fIBIO_meth_set_read()\fR
or call \fIBIO_meth_get_read()\fR when the function was set with
\&\fIBIO_meth_set_read_ex()\fR.
.PP
\&\fIBIO_meth_get_puts()\fR and \fIBIO_meth_set_puts()\fR get and set the function used for
writing a \s-1NULL\s0 terminated string to the \s-1BIO\s0 respectively. This function will be
called in response to the application calling \fIBIO_puts()\fR. The parameters for
the function have the same meaning as for \fIBIO_puts()\fR.
.PP
\&\fIBIO_meth_get_gets()\fR and \fIBIO_meth_set_gets()\fR get and set the function typically
used for reading a line of data from the \s-1BIO\s0 respectively (see the \fIBIO_gets\fR\|(3)
page for more information). This function will be called in response to the
application calling \fIBIO_gets()\fR. The parameters for the function have the same
meaning as for \fIBIO_gets()\fR.
.PP
\&\fIBIO_meth_get_ctrl()\fR and \fIBIO_meth_set_ctrl()\fR get and set the function used for
processing ctrl messages in the \s-1BIO\s0 respectively. See the BIO_ctrl page for
more information. This function will be called in response to the application
calling \fIBIO_ctrl()\fR. The parameters for the function have the same meaning as for
\&\fIBIO_ctrl()\fR.
.PP
\&\fIBIO_meth_get_create()\fR and \fIBIO_meth_set_create()\fR get and set the function used
for creating a new instance of the \s-1BIO\s0 respectively. This function will be
called in response to the application calling \fIBIO_new()\fR and passing
in a pointer to the current \s-1BIO_METHOD.\s0 The \fIBIO_new()\fR function will allocate the
memory for the new \s-1BIO,\s0 and a pointer to this newly allocated structure will
be passed as a parameter to the function.
.PP
\&\fIBIO_meth_get_destroy()\fR and \fIBIO_meth_set_destroy()\fR get and set the function used
for destroying an instance of a \s-1BIO\s0 respectively. This function will be
called in response to the application calling \fIBIO_free()\fR. A pointer to the \s-1BIO\s0
to be destroyed is passed as a parameter. The destroy function should be used
for \s-1BIO\s0 specific clean up. The memory for the \s-1BIO\s0 itself should not be freed by
this function.
.PP
\&\fIBIO_meth_get_callback_ctrl()\fR and \fIBIO_meth_set_callback_ctrl()\fR get and set the
function used for processing callback ctrl messages in the \s-1BIO\s0 respectively. See
the \fIBIO_callback_ctrl\fR\|(3) page for more information. This function will be called
in response to the application calling \fIBIO_callback_ctrl()\fR. The parameters for
the function have the same meaning as for \fIBIO_callback_ctrl()\fR.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fIBIO_get_new_index()\fR returns the new \s-1BIO\s0 type value or \-1 if an error occurred.
.PP
BIO_meth_new(int type, const char *name) returns a valid \fB\s-1BIO_METHOD\s0\fR or \s-1NULL\s0
if an error occurred.
.PP
The \fBBIO_meth_set\fR functions return 1 on success or 0 on error.
.PP
The \fBBIO_meth_get\fR functions return the corresponding function pointers.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
bio, BIO_find_type, BIO_ctrl, BIO_read_ex, BIO_new
.SH "HISTORY"
.IX Header "HISTORY"
The functions described here were added in OpenSSL 1.1.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2016\-2018 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

44
secure/lib/libcrypto/man/BIO_new.3
View file

@ -128,21 +128,21 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BIO_new 3"
.TH BIO_new 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "BIO_NEW 3"
.TH BIO_NEW 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
BIO_new, BIO_set, BIO_free, BIO_vfree, BIO_free_all \- BIO allocation and freeing functions
BIO_new, BIO_up_ref, BIO_free, BIO_vfree, BIO_free_all \&\- BIO allocation and freeing functions
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bio.h>
\&
\& BIO * BIO_new(BIO_METHOD *type);
\& int BIO_set(BIO *a,BIO_METHOD *type);
\& 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);
@ -151,39 +151,36 @@ BIO_new, BIO_set, BIO_free, BIO_vfree, BIO_free_all \- BIO allocation and freein
.IX Header "DESCRIPTION"
The \fIBIO_new()\fR function returns a new \s-1BIO\s0 using method \fBtype\fR.
.PP
\&\fIBIO_set()\fR sets the method of an already existing \s-1BIO.\s0
\&\fIBIO_up_ref()\fR increments the reference count associated with the \s-1BIO\s0 object.
.PP
\&\fIBIO_free()\fR frees up a single \s-1BIO,\s0 \fIBIO_vfree()\fR also frees up a single \s-1BIO\s0
but it does not return a value. Calling \fIBIO_free()\fR may also have some effect
but it does not return a value.
If \fBa\fR is \s-1NULL\s0 nothing is done.
Calling \fIBIO_free()\fR 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
\&\s-1BIO_METHOD\s0 descriptions.
.PP
\&\fIBIO_free_all()\fR frees up an entire \s-1BIO\s0 chain, it does not halt if an error
occurs freeing up an individual \s-1BIO\s0 in the chain.
If \fBa\fR is \s-1NULL\s0 nothing is done.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fIBIO_new()\fR returns a newly created \s-1BIO\s0 or \s-1NULL\s0 if the call fails.
.PP
\&\fIBIO_set()\fR, \fIBIO_free()\fR return 1 for success and 0 for failure.
\&\fIBIO_up_ref()\fR and \fIBIO_free()\fR return 1 for success and 0 for failure.
.PP
\&\fIBIO_free_all()\fR and \fIBIO_vfree()\fR do not return values.
.SH "NOTES"
.IX Header "NOTES"
Some BIOs (such as memory BIOs) can be used immediately after calling
\&\fIBIO_new()\fR. Others (such as file BIOs) need some additional initialization,
and frequently a utility function exists to create and initialize such BIOs.
.PP
If \fIBIO_free()\fR is called on a \s-1BIO\s0 chain it will only free one \s-1BIO\s0 resulting
in a memory leak.
.PP
Calling \fIBIO_free_all()\fR a single \s-1BIO\s0 has the same effect as calling \fIBIO_free()\fR
Calling \fIBIO_free_all()\fR on a single \s-1BIO\s0 has the same effect as calling \fIBIO_free()\fR
on it other than the discarded return value.
.PP
Normally the \fBtype\fR argument is supplied by a function which returns a
pointer to a \s-1BIO_METHOD.\s0 There is a naming convention for such functions:
a source/sink \s-1BIO\s0 is normally called BIO_s_*() and a filter \s-1BIO\s0
BIO_f_*();
.SH "HISTORY"
.IX Header "HISTORY"
\&\fIBIO_set()\fR was removed in OpenSSL 1.1.0 as \s-1BIO\s0 type is now opaque.
.SH "EXAMPLE"
.IX Header "EXAMPLE"
Create a memory \s-1BIO:\s0
@ -191,6 +188,11 @@ Create a memory \s-1BIO:\s0
.Vb 1
\& BIO *mem = BIO_new(BIO_s_mem());
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1TBA\s0
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

16
secure/lib/libcrypto/man/BIO_new_CMS.3
View file

@ -128,16 +128,14 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BIO_new_CMS 3"
.TH BIO_new_CMS 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "BIO_NEW_CMS 3"
.TH BIO_NEW_CMS 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
.Vb 1
\& BIO_new_CMS \- CMS streaming filter BIO
.Ve
BIO_new_CMS \- CMS streaming filter BIO
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
@ -192,3 +190,11 @@ occurred. The error can be obtained from \fIERR_get_error\fR\|(3).
.SH "HISTORY"
.IX Header "HISTORY"
\&\fIBIO_new_CMS()\fR was added to OpenSSL 1.0.0
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2008\-2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

208
secure/lib/libcrypto/man/BIO_parse_hostserv.3 Normal file
View file

@ -0,0 +1,208 @@
.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BIO_PARSE_HOSTSERV 3"
.TH BIO_PARSE_HOSTSERV 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
BIO_hostserv_priorities, BIO_parse_hostserv \&\- utility routines to parse a standard host and service string
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fIBIO_parse_hostserv()\fR will parse the information given in \fBhostserv\fR,
create strings with the host name and service name and give those
back via \fBhost\fR and \fBservice\fR. Those will need to be freed after
they are used. \fBhostserv_prio\fR helps determine if \fBhostserv\fR shall
be interpreted primarily as a host name or a service name in ambiguous
cases.
.PP
The syntax the \fIBIO_parse_hostserv()\fR recognises is:
.PP
.Vb 7
\& host + \*(Aq:\*(Aq + service
\& host + \*(Aq:\*(Aq + \*(Aq*\*(Aq
\& host + \*(Aq:\*(Aq
\& \*(Aq:\*(Aq + service
\& \*(Aq*\*(Aq + \*(Aq:\*(Aq + service
\& host
\& service
.Ve
.PP
The host part can be a name or an \s-1IP\s0 address. If it's a IPv6
address, it \s-1MUST\s0 be enclosed in brackets, such as '[::1]'.
.PP
The service part can be a service name or its port number.
.PP
The returned values will depend on the given \fBhostserv\fR string
and \fBhostserv_prio\fR, as follows:
.PP
.Vb 5
\& host + \*(Aq:\*(Aq + service => *host = "host", *service = "service"
\& host + \*(Aq:\*(Aq + \*(Aq*\*(Aq => *host = "host", *service = NULL
\& host + \*(Aq:\*(Aq => *host = "host", *service = NULL
\& \*(Aq:\*(Aq + service => *host = NULL, *service = "service"
\& \*(Aq*\*(Aq + \*(Aq:\*(Aq + service => *host = NULL, *service = "service"
\&
\& in case no \*(Aq:\*(Aq 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"
.Ve
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fIBIO_parse_hostserv()\fR returns 1 on success or 0 on error.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1\fIBIO_ADDRINFO\s0\fR\|(3)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2016\-2018 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

178
secure/lib/libcrypto/man/BIO_printf.3 Normal file
View file

@ -0,0 +1,178 @@
.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BIO_PRINTF 3"
.TH BIO_PRINTF 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
BIO_printf, BIO_vprintf, BIO_snprintf, BIO_vsnprintf \&\- formatted output to a BIO
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #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)
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fIBIO_printf()\fR is similar to the standard C \fIprintf()\fR function, except that
the output is sent to the specified \s-1BIO,\s0 \fBbio\fR, rather than standard
output. All common format specifiers are supported.
.PP
\&\fIBIO_vprintf()\fR is similar to the \fIvprintf()\fR function found on many platforms,
the output is sent to the specified \s-1BIO,\s0 \fBbio\fR, rather than standard
output. All common format specifiers are supported. The argument
list \fBargs\fR is a stdarg argument list.
.PP
\&\fIBIO_snprintf()\fR is for platforms that do not have the common \fIsnprintf()\fR
function. It is like \fIsprintf()\fR except that the size parameter, \fBn\fR,
specifies the size of the output buffer.
.PP
\&\fIBIO_vsnprintf()\fR is to \fIBIO_snprintf()\fR as \fIBIO_vprintf()\fR is to \fIBIO_printf()\fR.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
All functions return the number of bytes written, or \-1 on error.
For \fIBIO_snprintf()\fR and \fIBIO_vsnprintf()\fR this includes when the output
buffer is too small.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

28
secure/lib/libcrypto/man/BIO_push.3
View file

@ -128,21 +128,22 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BIO_push 3"
.TH BIO_push 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "BIO_PUSH 3"
.TH BIO_PUSH 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
BIO_push, BIO_pop \- add and remove BIOs from a chain.
BIO_push, BIO_pop, BIO_set_next \- add and remove BIOs from a chain
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bio.h>
\&
\& BIO * BIO_push(BIO *b,BIO *append);
\& BIO * BIO_pop(BIO *b);
\& BIO *BIO_push(BIO *b, BIO *append);
\& BIO *BIO_pop(BIO *b);
\& void BIO_set_next(BIO *b, BIO *next);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
@ -153,6 +154,10 @@ The \fIBIO_push()\fR function appends the \s-1BIO\s0 \fBappend\fR to \fBb\fR, it
in the chain, or \s-1NULL\s0 if there is no next \s-1BIO.\s0 The removed \s-1BIO\s0 then
becomes a single \s-1BIO\s0 with no association with the original chain,
it can thus be freed or attached to a different chain.
.PP
\&\fIBIO_set_next()\fR replaces the existing next \s-1BIO\s0 in a chain with the \s-1BIO\s0 pointed to
by \fBnext\fR. The new chain may include some of the same BIOs from the old chain
or it may be completely different.
.SH "NOTES"
.IX Header "NOTES"
The names of these functions are perhaps a little misleading. \fIBIO_push()\fR
@ -201,4 +206,15 @@ be written to \fBmd1\fR as before.
\&\s-1BIO.\s0
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1TBA\s0
bio
.SH "HISTORY"
.IX Header "HISTORY"
The \fIBIO_set_next()\fR function was added in OpenSSL 1.1.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

52
secure/lib/libcrypto/man/BIO_read.3
View file

@ -128,44 +128,60 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BIO_read 3"
.TH BIO_read 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "BIO_READ 3"
.TH BIO_READ 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
BIO_read, BIO_write, BIO_gets, BIO_puts \- BIO I/O functions
BIO_read_ex, BIO_write_ex, BIO_read, BIO_write, BIO_gets, BIO_puts \&\- BIO I/O functions
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bio.h>
\&
\& int BIO_read(BIO *b, void *buf, int len);
\& int BIO_gets(BIO *b, char *buf, int size);
\& int BIO_write(BIO *b, const void *buf, int len);
\& int BIO_puts(BIO *b, const char *buf);
\& int BIO_read_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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fIBIO_read_ex()\fR attempts to read \fBdlen\fR bytes from \s-1BIO\s0 \fBb\fR and places the data
in \fBdata\fR. If any bytes were successfully read then the number of bytes read is
stored in \fB*readbytes\fR.
.PP
\&\fIBIO_write_ex()\fR attempts to write \fBdlen\fR bytes from \fBdata\fR to \s-1BIO\s0 \fBb\fR. If
successful then the number of bytes written is stored in \fB*written\fR.
.PP
\&\fIBIO_read()\fR attempts to read \fBlen\fR bytes from \s-1BIO\s0 \fBb\fR and places
the data in \fBbuf\fR.
.PP
\&\fIBIO_gets()\fR performs the BIOs \*(L"gets\*(R" operation and places the data
in \fBbuf\fR. Usually this operation will attempt to read a line of data
from the \s-1BIO\s0 of maximum length \fBlen\fR. There are exceptions to this
however, for example \fIBIO_gets()\fR on a digest \s-1BIO\s0 will calculate and
from the \s-1BIO\s0 of maximum length \fBsize\-1\fR. There are exceptions to this,
however; for example, \fIBIO_gets()\fR on a digest \s-1BIO\s0 will calculate and
return the digest and other BIOs may not support \fIBIO_gets()\fR at all.
The returned string is always NUL-terminated and the '\en' is preserved
if present in the input data.
.PP
\&\fIBIO_write()\fR attempts to write \fBlen\fR bytes from \fBbuf\fR to \s-1BIO\s0 \fBb\fR.
.PP
\&\fIBIO_puts()\fR attempts to write a null terminated string \fBbuf\fR to \s-1BIO\s0 \fBb\fR.
\&\fIBIO_puts()\fR attempts to write a NUL-terminated string \fBbuf\fR to \s-1BIO\s0 \fBb\fR.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
All these functions return either the amount of data successfully read or
\&\fIBIO_read_ex()\fR and \fIBIO_write_ex()\fR return 1 if data was successfully read or
written, and 0 otherwise.
.PP
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 \s-1BIO\s0 type.
the operation is not implemented in the specific \s-1BIO\s0 type. The trailing
\&\s-1NUL\s0 is not included in the length returned by \fIBIO_gets()\fR.
.SH "NOTES"
.IX Header "NOTES"
A 0 or \-1 return is not necessarily an indication of an error. In
@ -192,5 +208,15 @@ to the chain.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIBIO_should_retry\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fIBIO_gets()\fR on 1.1.0 and older when called on \fIBIO_fd()\fR based \s-1BIO\s0 does not
keep the '\en' at the end of the line in the buffer.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
\&\s-1TBA\s0
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

129
secure/lib/libcrypto/man/BIO_s_accept.3
View file

@ -128,24 +128,25 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BIO_s_accept 3"
.TH BIO_s_accept 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "BIO_S_ACCEPT 3"
.TH BIO_S_ACCEPT 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
BIO_s_accept, BIO_set_accept_port, BIO_get_accept_port, BIO_new_accept,
BIO_set_nbio_accept, BIO_set_accept_bios, BIO_set_bind_mode,
BIO_get_bind_mode, BIO_do_accept \- accept BIO
BIO_s_accept, BIO_set_accept_name, BIO_set_accept_port, BIO_get_accept_name, BIO_get_accept_port, BIO_new_accept, BIO_set_nbio_accept, BIO_set_accept_bios, BIO_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
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bio.h>
\&
\& BIO_METHOD *BIO_s_accept(void);
\& const BIO_METHOD *BIO_s_accept(void);
\&
\& long BIO_set_accept_port(BIO *b, char *name);
\& long BIO_set_accept_name(BIO *b, char *name);
\& char *BIO_get_accept_name(BIO *b);
\&
\& long BIO_set_accept_port(BIO *b, char *port);
\& char *BIO_get_accept_port(BIO *b);
\&
\& BIO *BIO_new_accept(char *host_port);
@ -153,12 +154,13 @@ BIO_get_bind_mode, BIO_do_accept \- accept BIO
\& long BIO_set_nbio_accept(BIO *b, int n);
\& long BIO_set_accept_bios(BIO *b, char *bio);
\&
\& long BIO_set_bind_mode(BIO *b, long mode);
\& long BIO_get_bind_mode(BIO *b, long dummy);
\& 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);
\&
\& #define BIO_BIND_NORMAL 0
\& #define BIO_BIND_REUSEADDR_IF_UNUSED 1
\& #define BIO_BIND_REUSEADDR 2
\& long BIO_set_bind_mode(BIO *b, long mode);
\& long BIO_get_bind_mode(BIO *b);
\&
\& int BIO_do_accept(BIO *b);
.Ve
@ -182,23 +184,30 @@ If the close flag is set on an accept \s-1BIO\s0 then any active
connection on that chain is shutdown and the socket closed when
the \s-1BIO\s0 is freed.
.PP
Calling \fIBIO_reset()\fR on a accept \s-1BIO\s0 will close any active
Calling \fIBIO_reset()\fR on an accept \s-1BIO\s0 will close any active
connection and reset the \s-1BIO\s0 into a state where it awaits another
incoming connection.
.PP
\&\fIBIO_get_fd()\fR and \fIBIO_set_fd()\fR can be called to retrieve or set
the accept socket. See \fIBIO_s_fd\fR\|(3)
.PP
\&\fIBIO_set_accept_port()\fR uses the string \fBname\fR to set the accept
port. The port is represented as a string of the form \*(L"host:port\*(R",
\&\fIBIO_set_accept_name()\fR uses the string \fBname\fR to set the accept
name. The name is represented as a string of the form \*(L"host:port\*(R",
where \*(L"host\*(R" is the interface to use and \*(L"port\*(R" is the port.
The host can be can be \*(L"*\*(R" which is interpreted as meaning
any interface; \*(L"port\*(R" has the same syntax
as the port specified in \fIBIO_set_conn_port()\fR for connect BIOs,
that is it can be a numerical port string or a string to lookup
using \fIgetservbyname()\fR and a string table.
The host can be \*(L"*\*(R" 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 \*(L"[::1]:https\*(R". \*(L"port\*(R" has the
same syntax as the port specified in \fIBIO_set_conn_port()\fR for
connect BIOs, that is it can be a numerical port string or a
string to lookup using \fIgetservbyname()\fR and a string table.
.PP
\&\fIBIO_new_accept()\fR combines \fIBIO_new()\fR and \fIBIO_set_accept_port()\fR into
\&\fIBIO_set_accept_port()\fR uses the string \fBport\fR to set the accept
port. \*(L"port\*(R" has the same syntax as the port specified in
\&\fIBIO_set_conn_port()\fR for connect BIOs, that is it can be a numerical
port string or a string to lookup using \fIgetservbyname()\fR and a string
table.
.PP
\&\fIBIO_new_accept()\fR combines \fIBIO_new()\fR and \fIBIO_set_accept_name()\fR into
a single call: that is it creates a new accept \s-1BIO\s0 with port
\&\fBhost_port\fR.
.PP
@ -207,19 +216,19 @@ a single call: that is it creates a new accept \s-1BIO\s0 with port
.PP
\&\fIBIO_set_accept_bios()\fR can be used to set a chain of BIOs which
will be duplicated and prepended to the chain when an incoming
connection is received. This is useful if, for example, a
connection is received. This is useful if, for example, a
buffering or \s-1SSL BIO\s0 is required for each connection. The
chain of BIOs must not be freed after this call, they will
be automatically freed when the accept \s-1BIO\s0 is freed.
.PP
\&\fIBIO_set_bind_mode()\fR and \fIBIO_get_bind_mode()\fR set and retrieve
the current bind mode. If \s-1BIO_BIND_NORMAL\s0 (the default) is set
the current bind mode. If \fB\s-1BIO_BIND_NORMAL\s0\fR (the default) is set
then another socket cannot be bound to the same port. If
\&\s-1BIO_BIND_REUSEADDR\s0 is set then other sockets can bind to the
same port. If \s-1BIO_BIND_REUSEADDR_IF_UNUSED\s0 is set then and
\&\fB\s-1BIO_BIND_REUSEADDR\s0\fR is set then other sockets can bind to the
same port. If \fB\s-1BIO_BIND_REUSEADDR_IF_UNUSED\s0\fR is set then and
attempt is first made to use \s-1BIO_BIN_NORMAL,\s0 if this fails
and the port is not in use then a second attempt is made
using \s-1BIO_BIND_REUSEADDR.\s0
using \fB\s-1BIO_BIND_REUSEADDR\s0\fR.
.PP
\&\fIBIO_do_accept()\fR serves two functions. When it is first
called, after the accept \s-1BIO\s0 has been setup, it will attempt
@ -271,47 +280,65 @@ 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.
.PP
\&\fIBIO_set_accept_port()\fR, \fIBIO_get_accept_port()\fR, \fIBIO_set_nbio_accept()\fR,
\&\fIBIO_set_accept_bios()\fR, \fIBIO_set_bind_mode()\fR, \fIBIO_get_bind_mode()\fR and
\&\fIBIO_do_accept()\fR are macros.
\&\fIBIO_set_accept_name()\fR, \fIBIO_get_accept_name()\fR, \fIBIO_set_accept_port()\fR,
\&\fIBIO_get_accept_port()\fR, \fIBIO_set_nbio_accept()\fR, \fIBIO_set_accept_bios()\fR,
\&\fIBIO_get_peer_name()\fR, \fIBIO_get_peer_port()\fR,
\&\fIBIO_get_accept_ip_family()\fR, \fIBIO_set_accept_ip_family()\fR,
\&\fIBIO_set_bind_mode()\fR, \fIBIO_get_bind_mode()\fR and \fIBIO_do_accept()\fR are macros.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\s-1TBA\s0
\&\fIBIO_do_accept()\fR,
\&\fIBIO_set_accept_name()\fR, \fIBIO_set_accept_port()\fR, \fIBIO_set_nbio_accept()\fR,
\&\fIBIO_set_accept_bios()\fR, \fIBIO_set_accept_ip_family()\fR, and \fIBIO_set_bind_mode()\fR
return 1 for success and 0 or \-1 for failure.
.PP
\&\fIBIO_get_accept_name()\fR returns the accept name or \s-1NULL\s0 on error.
\&\fIBIO_get_peer_name()\fR returns the peer name or \s-1NULL\s0 on error.
.PP
\&\fIBIO_get_accept_port()\fR returns the accept port as a string or \s-1NULL\s0 on error.
\&\fIBIO_get_peer_port()\fR returns the peer port as a string or \s-1NULL\s0 on error.
\&\fIBIO_get_accept_ip_family()\fR returns the \s-1IP\s0 family or \-1 on error.
.PP
\&\fIBIO_get_bind_mode()\fR returns the set of \fB\s-1BIO_BIND\s0\fR flags, or \-1 on failure.
.PP
\&\fIBIO_new_accept()\fR returns a \s-1BIO\s0 or \s-1NULL\s0 on error.
.SH "EXAMPLE"
.IX Header "EXAMPLE"
This example accepts two connections on port 4444, sends messages
down each and finally closes both down.
.PP
.Vb 3
.Vb 1
\& BIO *abio, *cbio, *cbio2;
\& ERR_load_crypto_strings();
\& abio = BIO_new_accept("4444");
\&
\& /* First call to BIO_accept() sets up accept BIO */
\& if(BIO_do_accept(abio) <= 0) {
\& fprintf(stderr, "Error setting up accept\en");
\& ERR_print_errors_fp(stderr);
\& exit(0);
\& abio = BIO_new_accept("4444");
\& if (BIO_do_accept(abio) <= 0) {
\& fprintf(stderr, "Error setting up accept\en");
\& ERR_print_errors_fp(stderr);
\& exit(1);
\& }
\&
\& /* Wait for incoming connection */
\& if(BIO_do_accept(abio) <= 0) {
\& fprintf(stderr, "Error accepting connection\en");
\& ERR_print_errors_fp(stderr);
\& exit(0);
\& if (BIO_do_accept(abio) <= 0) {
\& fprintf(stderr, "Error accepting connection\en");
\& ERR_print_errors_fp(stderr);
\& exit(1);
\& }
\& fprintf(stderr, "Connection 1 established\en");
\&
\& /* Retrieve BIO for connection */
\& cbio = BIO_pop(abio);
\& BIO_puts(cbio, "Connection 1: Sending out Data on initial connection\en");
\& fprintf(stderr, "Sent out data on connection 1\en");
\&
\& /* Wait for another connection */
\& if(BIO_do_accept(abio) <= 0) {
\& fprintf(stderr, "Error accepting connection\en");
\& ERR_print_errors_fp(stderr);
\& exit(0);
\& if (BIO_do_accept(abio) <= 0) {
\& fprintf(stderr, "Error accepting connection\en");
\& ERR_print_errors_fp(stderr);
\& exit(1);
\& }
\& fprintf(stderr, "Connection 2 established\en");
\&
\& /* Close accept BIO to refuse further connections */
\& cbio2 = BIO_pop(abio);
\& BIO_free(abio);
@ -319,10 +346,16 @@ down each and finally closes both down.
\& fprintf(stderr, "Sent out data on connection 2\en");
\&
\& BIO_puts(cbio, "Connection 1: Second connection established\en");
\&
\& /* Close the two established connections */
\& BIO_free(cbio);
\& BIO_free(cbio2);
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1TBA\s0
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

86
secure/lib/libcrypto/man/BIO_s_bio.3
View file

@ -128,40 +128,34 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BIO_s_bio 3"
.TH BIO_s_bio 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "BIO_S_BIO 3"
.TH BIO_S_BIO 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "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
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
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bio.h>
\&
\& BIO_METHOD *BIO_s_bio(void);
\& const BIO_METHOD *BIO_s_bio(void);
\&
\& #define BIO_make_bio_pair(b1,b2) (int)BIO_ctrl(b1,BIO_C_MAKE_BIO_PAIR,0,b2)
\& #define BIO_destroy_bio_pair(b) (int)BIO_ctrl(b,BIO_C_DESTROY_BIO_PAIR,0,NULL)
\& int BIO_make_bio_pair(BIO *b1, BIO *b2);
\& int BIO_destroy_bio_pair(BIO *b);
\& int BIO_shutdown_wr(BIO *b);
\&
\& #define BIO_shutdown_wr(b) (int)BIO_ctrl(b, BIO_C_SHUTDOWN_WR, 0, NULL)
\&
\& #define BIO_set_write_buf_size(b,size) (int)BIO_ctrl(b,BIO_C_SET_WRITE_BUF_SIZE,size,NULL)
\& #define BIO_get_write_buf_size(b,size) (size_t)BIO_ctrl(b,BIO_C_GET_WRITE_BUF_SIZE,size,NULL)
\& int BIO_set_write_buf_size(BIO *b, long size);
\& size_t BIO_get_write_buf_size(BIO *b, long size);
\&
\& int BIO_new_bio_pair(BIO **bio1, size_t writebuf1, BIO **bio2, size_t writebuf2);
\&
\& #define BIO_get_write_guarantee(b) (int)BIO_ctrl(b,BIO_C_GET_WRITE_GUARANTEE,0,NULL)
\& int BIO_get_write_guarantee(BIO *b);
\& size_t BIO_ctrl_get_write_guarantee(BIO *b);
\&
\& #define BIO_get_read_request(b) (int)BIO_ctrl(b,BIO_C_GET_READ_REQUEST,0,NULL)
\& int BIO_get_read_request(BIO *b);
\& size_t BIO_ctrl_get_read_request(BIO *b);
\&
\& int BIO_ctrl_reset_read_request(BIO *b);
.Ve
.SH "DESCRIPTION"
@ -179,10 +173,10 @@ One typical use of \s-1BIO\s0 pairs is to place \s-1TLS/SSL I/O\s0 under applica
can be used when the application wishes to use a non standard transport for
\&\s-1TLS/SSL\s0 or the normal socket routines are inappropriate.
.PP
Calls to \fIBIO_read()\fR will read data from the buffer or request a retry if no
Calls to \fIBIO_read_ex()\fR will read data from the buffer or request a retry if no
data is available.
.PP
Calls to \fIBIO_write()\fR will place data in the buffer or request a retry if the
Calls to \fIBIO_write_ex()\fR will place data in the buffer or request a retry if the
buffer is full.
.PP
The standard calls \fIBIO_ctrl_pending()\fR and \fIBIO_ctrl_wpending()\fR can be used to
@ -215,9 +209,9 @@ zero then the default size is used. \fIBIO_new_bio_pair()\fR does not check whe
.PP
\&\fIBIO_get_write_guarantee()\fR and \fIBIO_ctrl_get_write_guarantee()\fR return the maximum
length of data that can be currently written to the \s-1BIO.\s0 Writes larger than this
value will return a value from \fIBIO_write()\fR less than the amount requested or if the
buffer is full request a retry. \fIBIO_ctrl_get_write_guarantee()\fR is a function
whereas \fIBIO_get_write_guarantee()\fR is a macro.
value will return a value from \fIBIO_write_ex()\fR less than the amount requested or
if the buffer is full request a retry. \fIBIO_ctrl_get_write_guarantee()\fR is a
function whereas \fIBIO_get_write_guarantee()\fR is a macro.
.PP
\&\fIBIO_get_read_request()\fR and \fIBIO_ctrl_get_read_request()\fR return the
amount of data requested, or the buffer size if it is less, if the
@ -245,15 +239,20 @@ it to the underlying transport. This must be done before any normal processing
(such as calling \fIselect()\fR ) due to a request and \fIBIO_should_read()\fR being true.
.PP
To see why this is important consider a case where a request is sent using
\&\fIBIO_write()\fR and a response read with \fIBIO_read()\fR, this can occur during an
\&\s-1TLS/SSL\s0 handshake for example. \fIBIO_write()\fR will succeed and place data in the write
buffer. \fIBIO_read()\fR will initially fail and \fIBIO_should_read()\fR 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!
\&\fIBIO_write_ex()\fR and a response read with \fIBIO_read_ex()\fR, this can occur during an
\&\s-1TLS/SSL\s0 handshake for example. \fIBIO_write_ex()\fR will succeed and place data in the
write buffer. \fIBIO_read_ex()\fR will initially fail and \fIBIO_should_read()\fR 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!
.PP
\&\fIBIO_eof()\fR is true if no data is in the peer \s-1BIO\s0 and the peer \s-1BIO\s0 has been
shutdown.
.PP
\&\fIBIO_make_bio_pair()\fR, \fIBIO_destroy_bio_pair()\fR, \fIBIO_shutdown_wr()\fR,
\&\fIBIO_set_write_buf_size()\fR, \fIBIO_get_write_buf_size()\fR,
\&\fIBIO_get_write_guarantee()\fR, and \fIBIO_get_read_request()\fR are implemented
as macros.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fIBIO_new_bio_pair()\fR returns 1 on success, with the new BIOs available in
@ -267,12 +266,13 @@ The \s-1BIO\s0 pair can be used to have full control over the network access of
application. The application can call \fIselect()\fR on the socket as required
without having to go through the SSL-interface.
.PP
.Vb 6
.Vb 1
\& BIO *internal_bio, *network_bio;
\&
\& ...
\& BIO_new_bio_pair(internal_bio, 0, network_bio, 0);
\& BIO_new_bio_pair(&internal_bio, 0, &network_bio, 0);
\& SSL_set_bio(ssl, internal_bio, internal_bio);
\& SSL_operations();
\& SSL_operations(); /* e.g SSL_read and SSL_write */
\& ...
\&
\& application | TLS\-engine
@ -281,9 +281,13 @@ without having to go through the SSL-interface.
\& | /\e ||
\& | || \e/
\& | BIO\-pair (internal_bio)
\& +\-\-\-\-\-\-\-\-\-\-< BIO\-pair (network_bio)
\& | BIO\-pair (network_bio)
\& | || /\e
\& | \e/ ||
\& +\-\-\-\-\-\-\-\-\-\-\-< BIO_operations()
\& | |
\& socket |
\& | |
\& socket
\&
\& ...
\& SSL_free(ssl); /* implicitly frees internal_bio */
@ -297,17 +301,25 @@ buffer is full or the read buffer is drained. Then the application has to
flush the write buffer and/or fill the read buffer.
.PP
Use the \fIBIO_ctrl_pending()\fR, to find out whether data is buffered in the \s-1BIO\s0
and must be transfered to the network. Use \fIBIO_ctrl_get_read_request()\fR to
and must be transferred to the network. Use \fIBIO_ctrl_get_read_request()\fR to
find out, how many bytes must be written into the buffer before the
\&\fISSL_operation()\fR can successfully be continued.
.SH "WARNING"
.IX Header "WARNING"
As the data is buffered, \fISSL_operation()\fR may return with a \s-1ERROR_SSL_WANT_READ\s0
As the data is buffered, \fISSL_operation()\fR may return with an \s-1ERROR_SSL_WANT_READ\s0
condition, but there is still data in the write buffer. An application must
not rely on the error value of \fISSL_operation()\fR 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.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fISSL_set_bio\fR\|(3), \fIssl\fR\|(3), \fIbio\fR\|(3),
\&\fIBIO_should_retry\fR\|(3), \fIBIO_read\fR\|(3)
\&\fISSL_set_bio\fR\|(3), \fIssl\fR\|(7), \fIbio\fR\|(7),
\&\fIBIO_should_retry\fR\|(3), \fIBIO_read_ex\fR\|(3)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

121
secure/lib/libcrypto/man/BIO_s_connect.3
View file

@ -128,34 +128,31 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BIO_s_connect 3"
.TH BIO_s_connect 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "BIO_S_CONNECT 3"
.TH BIO_S_CONNECT 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
BIO_s_connect, BIO_new_connect, BIO_set_conn_hostname, BIO_set_conn_port,
BIO_set_conn_ip, BIO_set_conn_int_port, BIO_get_conn_hostname,
BIO_get_conn_port, BIO_get_conn_ip, BIO_get_conn_int_port,
BIO_set_nbio, BIO_do_connect \- connect BIO
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
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bio.h>
\&
\& BIO_METHOD * BIO_s_connect(void);
\& const BIO_METHOD * BIO_s_connect(void);
\&
\& BIO *BIO_new_connect(char *name);
\&
\& long BIO_set_conn_hostname(BIO *b, char *name);
\& long BIO_set_conn_port(BIO *b, char *port);
\& long BIO_set_conn_ip(BIO *b, char *ip);
\& long BIO_set_conn_int_port(BIO *b, char *port);
\& char *BIO_get_conn_hostname(BIO *b);
\& char *BIO_get_conn_port(BIO *b);
\& char *BIO_get_conn_ip(BIO *b);
\& long BIO_get_conn_int_port(BIO *b);
\& long BIO_set_conn_address(BIO *b, BIO_ADDR *addr);
\& 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);
\&
@ -190,36 +187,37 @@ it also returns the socket . If \fBc\fR is not \s-1NULL\s0 it should be of
type (int *).
.PP
\&\fIBIO_set_conn_hostname()\fR uses the string \fBname\fR to set the hostname.
The hostname can be an \s-1IP\s0 address. The hostname can also include the
port in the form hostname:port . It is also acceptable to use the
form \*(L"hostname/any/other/path\*(R" or \*(L"hostname:port/any/other/path\*(R".
The hostname can be an \s-1IP\s0 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.
.PP
\&\fIBIO_set_conn_port()\fR sets the port to \fBport\fR. \fBport\fR can be the
numerical form or a string such as \*(L"http\*(R". A string will be looked
up first using \fIgetservbyname()\fR on the host platform but if that
fails a standard table of port names will be used. Currently the
list is http, telnet, socks, https, ssl, ftp, gopher and wais.
fails a standard table of port names will be used. This internal
list is http, telnet, socks, https, ssl, ftp, and gopher.
.PP
\&\fIBIO_set_conn_ip()\fR sets the \s-1IP\s0 address to \fBip\fR using binary form,
that is four bytes specifying the \s-1IP\s0 address in big-endian form.
\&\fIBIO_set_conn_address()\fR sets the address and port information using
a \s-1\fIBIO_ADDR\s0\fR\|(3ssl).
.PP
\&\fIBIO_set_conn_int_port()\fR sets the port using \fBport\fR. \fBport\fR should
be of type (int *).
\&\fIBIO_set_conn_ip_family()\fR sets the \s-1IP\s0 family.
.PP
\&\fIBIO_get_conn_hostname()\fR returns the hostname of the connect \s-1BIO\s0 or
\&\s-1NULL\s0 if the \s-1BIO\s0 is initialized but no hostname is set.
This return value is an internal pointer which should not be modified.
.PP
\&\fIBIO_get_conn_port()\fR returns the port as a string.
This return value is an internal pointer which should not be modified.
.PP
\&\fIBIO_get_conn_ip()\fR returns the \s-1IP\s0 address in binary form.
\&\fIBIO_get_conn_address()\fR returns the address information as a \s-1BIO_ADDR.\s0
This return value is an internal pointer which should not be modified.
.PP
\&\fIBIO_get_conn_int_port()\fR returns the port as an int.
\&\fIBIO_get_conn_ip_family()\fR returns the \s-1IP\s0 family of the connect \s-1BIO.\s0
.PP
\&\fIBIO_set_nbio()\fR sets the non blocking I/O flag to \fBn\fR. If \fBn\fR is
zero then blocking I/O is set. If \fBn\fR is 1 then non blocking I/O
is set. Blocking I/O is the default. The call to \fIBIO_set_nbio()\fR
should be made before the connection is established because
should be made before the connection is established because
non blocking I/O is set during the connect process.
.PP
\&\fIBIO_new_connect()\fR combines \fIBIO_new()\fR and \fIBIO_set_conn_hostname()\fR into
@ -243,10 +241,10 @@ 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.
.PP
The values returned by \fIBIO_get_conn_hostname()\fR, \fIBIO_get_conn_port()\fR,
\&\fIBIO_get_conn_ip()\fR and \fIBIO_get_conn_int_port()\fR are updated when a
connection attempt is made. Before any connection attempt the values
returned are those set by the application itself.
The values returned by \fIBIO_get_conn_hostname()\fR, \fIBIO_get_conn_address()\fR,
and \fIBIO_get_conn_port()\fR are updated when a connection attempt is made.
Before any connection attempt the values returned are those set by the
application itself.
.PP
Applications do not have to call \fIBIO_do_connect()\fR but may wish to do
so to separate the connection process from other I/O processing.
@ -260,10 +258,10 @@ 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.
.PP
\&\fIBIO_set_conn_hostname()\fR, \fIBIO_set_conn_port()\fR, \fIBIO_set_conn_ip()\fR,
\&\fIBIO_set_conn_int_port()\fR, \fIBIO_get_conn_hostname()\fR, \fIBIO_get_conn_port()\fR,
\&\fIBIO_get_conn_ip()\fR, \fIBIO_get_conn_int_port()\fR, \fIBIO_set_nbio()\fR and
\&\fIBIO_do_connect()\fR are macros.
\&\fIBIO_set_conn_hostname()\fR, \fIBIO_set_conn_port()\fR, \fIBIO_get_conn_hostname()\fR,
\&\fIBIO_set_conn_address()\fR, \fIBIO_get_conn_port()\fR, \fIBIO_get_conn_address()\fR,
\&\fIBIO_set_conn_ip_family()\fR, \fIBIO_get_conn_ip_family()\fR,
\&\fIBIO_set_nbio()\fR, and \fIBIO_do_connect()\fR are macros.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fIBIO_s_connect()\fR returns the connect \s-1BIO\s0 method.
@ -271,21 +269,22 @@ the underlying socket has connected and retry the call.
\&\fIBIO_get_fd()\fR returns the socket or \-1 if the \s-1BIO\s0 has not
been initialized.
.PP
\&\fIBIO_set_conn_hostname()\fR, \fIBIO_set_conn_port()\fR, \fIBIO_set_conn_ip()\fR and
\&\fIBIO_set_conn_int_port()\fR always return 1.
\&\fIBIO_set_conn_address()\fR, \fIBIO_set_conn_port()\fR, and \fIBIO_set_conn_ip_family()\fR
always return 1.
.PP
\&\fIBIO_get_conn_hostname()\fR returns the connected hostname or \s-1NULL\s0 is
\&\fIBIO_set_conn_hostname()\fR returns 1 on success and 0 on failure.
.PP
\&\fIBIO_get_conn_address()\fR returns the address information or \s-1NULL\s0 if none
was set.
.PP
\&\fIBIO_get_conn_hostname()\fR returns the connected hostname or \s-1NULL\s0 if
none was set.
.PP
\&\fIBIO_get_conn_ip_family()\fR returns the address family or \-1 if none was set.
.PP
\&\fIBIO_get_conn_port()\fR returns a string representing the connected
port or \s-1NULL\s0 if not set.
.PP
\&\fIBIO_get_conn_ip()\fR returns a pointer to the connected \s-1IP\s0 address in
binary form or all zeros if not set.
.PP
\&\fIBIO_get_conn_int_port()\fR returns the connected port or 0 if none was
set.
.PP
\&\fIBIO_set_nbio()\fR always returns 1.
.PP
\&\fIBIO_do_connect()\fR returns 1 if the connection was successfully
@ -295,27 +294,41 @@ established and 0 or \-1 if the connection failed.
This is example connects to a webserver on the local host and attempts
to retrieve a page and copy the result to standard output.
.PP
.Vb 10
.Vb 3
\& BIO *cbio, *out;
\& int len;
\& char tmpbuf[1024];
\& ERR_load_crypto_strings();
\&
\& cbio = BIO_new_connect("localhost:http");
\& out = BIO_new_fp(stdout, BIO_NOCLOSE);
\& if(BIO_do_connect(cbio) <= 0) {
\& fprintf(stderr, "Error connecting to server\en");
\& ERR_print_errors_fp(stderr);
\& /* whatever ... */
\& }
\& if (BIO_do_connect(cbio) <= 0) {
\& fprintf(stderr, "Error connecting to server\en");
\& ERR_print_errors_fp(stderr);
\& exit(1);
\& }
\& BIO_puts(cbio, "GET / HTTP/1.0\en\en");
\& for(;;) {
\& len = BIO_read(cbio, tmpbuf, 1024);
\& if(len <= 0) break;
\& BIO_write(out, tmpbuf, len);
\& for (;;) {
\& len = BIO_read(cbio, tmpbuf, 1024);
\& if (len <= 0)
\& break;
\& BIO_write(out, tmpbuf, len);
\& }
\& BIO_free(cbio);
\& BIO_free(out);
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1TBA\s0
\&\s-1\fIBIO_ADDR\s0\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fIBIO_set_conn_int_port()\fR, \fIBIO_get_conn_int_port()\fR, \fIBIO_set_conn_ip()\fR, and \fIBIO_get_conn_ip()\fR
were removed in OpenSSL 1.1.0.
Use \fIBIO_set_conn_address()\fR and \fIBIO_get_conn_address()\fR instead.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

52
secure/lib/libcrypto/man/BIO_s_fd.3
View file

@ -128,8 +128,8 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BIO_s_fd 3"
.TH BIO_s_fd 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "BIO_S_FD 3"
.TH BIO_S_FD 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
@ -141,10 +141,10 @@ BIO_s_fd, BIO_set_fd, BIO_get_fd, BIO_new_fd \- file descriptor BIO
.Vb 1
\& #include <openssl/bio.h>
\&
\& BIO_METHOD * BIO_s_fd(void);
\& const BIO_METHOD *BIO_s_fd(void);
\&
\& #define BIO_set_fd(b,fd,c) BIO_int_ctrl(b,BIO_C_SET_FD,c,fd)
\& #define BIO_get_fd(b,c) BIO_ctrl(b,BIO_C_GET_FD,0,(char *)c)
\& int BIO_set_fd(BIO *b, int fd, int c);
\& int BIO_get_fd(BIO *b, int *c);
\&
\& BIO *BIO_new_fd(int fd, int close_flag);
.Ve
@ -153,47 +153,44 @@ BIO_s_fd, BIO_set_fd, BIO_get_fd, BIO_new_fd \- file descriptor BIO
\&\fIBIO_s_fd()\fR returns the file descriptor \s-1BIO\s0 method. This is a wrapper
round the platforms file descriptor routines such as \fIread()\fR and \fIwrite()\fR.
.PP
\&\fIBIO_read()\fR and \fIBIO_write()\fR read or write the underlying descriptor.
\&\fIBIO_read_ex()\fR and \fIBIO_write_ex()\fR read or write the underlying descriptor.
\&\fIBIO_puts()\fR is supported but \fIBIO_gets()\fR is not.
.PP
If the close flag is set then then \fIclose()\fR is called on the underlying
If the close flag is set then \fIclose()\fR is called on the underlying
file descriptor when the \s-1BIO\s0 is freed.
.PP
\&\fIBIO_reset()\fR attempts to change the file pointer to the start of file
using lseek(fd, 0, 0).
such as by using \fBlseek(fd, 0, 0)\fR.
.PP
\&\fIBIO_seek()\fR sets the file pointer to position \fBofs\fR from start of file
using lseek(fd, ofs, 0).
such as by using \fBlseek(fd, ofs, 0)\fR.
.PP
\&\fIBIO_tell()\fR returns the current file position by calling lseek(fd, 0, 1).
\&\fIBIO_tell()\fR returns the current file position such as by calling
\&\fBlseek(fd, 0, 1)\fR.
.PP
\&\fIBIO_set_fd()\fR sets the file descriptor of \s-1BIO\s0 \fBb\fR to \fBfd\fR and the close
flag to \fBc\fR.
.PP
\&\fIBIO_get_fd()\fR places the file descriptor in \fBc\fR if it is not \s-1NULL,\s0 it also
returns the file descriptor. If \fBc\fR is not \s-1NULL\s0 it should be of type
(int *).
returns the file descriptor.
.PP
\&\fIBIO_new_fd()\fR returns a file descriptor \s-1BIO\s0 using \fBfd\fR and \fBclose_flag\fR.
.SH "NOTES"
.IX Header "NOTES"
The behaviour of \fIBIO_read()\fR and \fIBIO_write()\fR depends on the behavior of the
platforms \fIread()\fR and \fIwrite()\fR calls on the descriptor. If the underlying
The behaviour of \fIBIO_read_ex()\fR and \fIBIO_write_ex()\fR depends on the behavior of the
platforms \fIread()\fR and \fIwrite()\fR calls on the descriptor. If the underlying
file descriptor is in a non blocking mode then the \s-1BIO\s0 will behave in the
manner described in the \fIBIO_read\fR\|(3) and \fIBIO_should_retry\fR\|(3)
manner described in the \fIBIO_read_ex\fR\|(3) and \fIBIO_should_retry\fR\|(3)
manual pages.
.PP
File descriptor BIOs should not be used for socket I/O. Use socket BIOs
instead.
.PP
\&\fIBIO_set_fd()\fR and \fIBIO_get_fd()\fR are implemented as macros.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fIBIO_s_fd()\fR returns the file descriptor \s-1BIO\s0 method.
.PP
\&\fIBIO_reset()\fR returns zero for success and \-1 if an error occurred.
\&\fIBIO_seek()\fR and \fIBIO_tell()\fR return the current file position or \-1
if an error occurred. These values reflect the underlying \fIlseek()\fR
behaviour.
.PP
\&\fIBIO_set_fd()\fR always returns 1.
.PP
\&\fIBIO_get_fd()\fR returns the file descriptor or \-1 if the \s-1BIO\s0 has not
@ -205,8 +202,9 @@ occurred.
.IX Header "EXAMPLE"
This is a file descriptor \s-1BIO\s0 version of \*(L"Hello World\*(R":
.PP
.Vb 4
.Vb 1
\& BIO *out;
\&
\& out = BIO_new_fd(fileno(stdout), BIO_NOCLOSE);
\& BIO_printf(out, "Hello World\en");
\& BIO_free(out);
@ -214,7 +212,15 @@ This is a file descriptor \s-1BIO\s0 version of \*(L"Hello World\*(R":
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIBIO_seek\fR\|(3), \fIBIO_tell\fR\|(3),
\&\fIBIO_reset\fR\|(3), \fIBIO_read\fR\|(3),
\&\fIBIO_write\fR\|(3), \fIBIO_puts\fR\|(3),
\&\fIBIO_reset\fR\|(3), \fIBIO_read_ex\fR\|(3),
\&\fIBIO_write_ex\fR\|(3), \fIBIO_puts\fR\|(3),
\&\fIBIO_gets\fR\|(3), \fIBIO_printf\fR\|(3),
\&\fIBIO_set_close\fR\|(3), \fIBIO_get_close\fR\|(3)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

59
secure/lib/libcrypto/man/BIO_s_file.3
View file

@ -128,27 +128,25 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BIO_s_file 3"
.TH BIO_s_file 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "BIO_S_FILE 3"
.TH BIO_S_FILE 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "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
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
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bio.h>
\&
\& BIO_METHOD * BIO_s_file(void);
\& const BIO_METHOD *BIO_s_file(void);
\& BIO *BIO_new_file(const char *filename, const char *mode);
\& BIO *BIO_new_fp(FILE *stream, int flags);
\&
\& BIO_set_fp(BIO *b,FILE *fp, int flags);
\& BIO_get_fp(BIO *b,FILE **fpp);
\& BIO_set_fp(BIO *b, FILE *fp, int flags);
\& BIO_get_fp(BIO *b, FILE **fpp);
\&
\& int BIO_read_filename(BIO *b, char *name)
\& int BIO_write_filename(BIO *b, char *name)
@ -161,7 +159,7 @@ BIO_rw_filename \- FILE bio
is a wrapper round the stdio \s-1FILE\s0 structure and it is a
source/sink \s-1BIO.\s0
.PP
Calls to \fIBIO_read()\fR and \fIBIO_write()\fR read and write data to the
Calls to \fIBIO_read_ex()\fR and \fIBIO_write_ex()\fR read and write data to the
underlying stream. \fIBIO_gets()\fR and \fIBIO_puts()\fR are supported on file BIOs.
.PP
\&\fIBIO_flush()\fR on a file \s-1BIO\s0 calls the \fIfflush()\fR function on the wrapped
@ -187,7 +185,7 @@ flag is set on the returned \s-1BIO.\s0
stream to text mode, default is binary: this only has any effect under
Win32).
.PP
\&\fIBIO_set_fp()\fR set the fp of a file \s-1BIO\s0 to \fBfp\fR. \fBflags\fR has the same
\&\fIBIO_set_fp()\fR sets the fp of a file \s-1BIO\s0 to \fBfp\fR. \fBflags\fR has the same
meaning as in \fIBIO_new_fp()\fR, it is a macro.
.PP
\&\fIBIO_get_fp()\fR retrieves the fp of a file \s-1BIO,\s0 it is a macro.
@ -215,39 +213,48 @@ lingual environment, encode file names in \s-1UTF\-8.\s0
.IX Header "EXAMPLES"
File \s-1BIO\s0 \*(L"hello world\*(R":
.PP
.Vb 3
.Vb 1
\& BIO *bio_out;
\&
\& bio_out = BIO_new_fp(stdout, BIO_NOCLOSE);
\& BIO_printf(bio_out, "Hello World\en");
.Ve
.PP
Alternative technique:
.PP
.Vb 5
.Vb 1
\& BIO *bio_out;
\&
\& bio_out = BIO_new(BIO_s_file());
\& if(bio_out == NULL) /* Error ... */
\& if(!BIO_set_fp(bio_out, stdout, BIO_NOCLOSE)) /* Error ... */
\& if (bio_out == NULL)
\& /* Error */
\& if (!BIO_set_fp(bio_out, stdout, BIO_NOCLOSE))
\& /* Error */
\& BIO_printf(bio_out, "Hello World\en");
.Ve
.PP
Write to a file:
.PP
.Vb 5
.Vb 1
\& BIO *out;
\&
\& out = BIO_new_file("filename.txt", "w");
\& if(!out) /* Error occurred */
\& if (!out)
\& /* Error */
\& BIO_printf(out, "Hello World\en");
\& BIO_free(out);
.Ve
.PP
Alternative technique:
.PP
.Vb 6
.Vb 1
\& BIO *out;
\&
\& out = BIO_new(BIO_s_file());
\& if(out == NULL) /* Error ... */
\& if(!BIO_write_filename(out, "filename.txt")) /* Error ... */
\& if (out == NULL)
\& /* Error */
\& if (!BIO_write_filename(out, "filename.txt"))
\& /* Error */
\& BIO_printf(out, "Hello World\en");
\& BIO_free(out);
.Ve
@ -266,7 +273,7 @@ occurred.
.PP
\&\fIBIO_tell()\fR returns the current file position.
.PP
\&\fIBIO_read_filename()\fR, \fIBIO_write_filename()\fR, \fIBIO_append_filename()\fR and
\&\fIBIO_read_filename()\fR, \fIBIO_write_filename()\fR, \fIBIO_append_filename()\fR and
\&\fIBIO_rw_filename()\fR return 1 for success or 0 for failure.
.SH "BUGS"
.IX Header "BUGS"
@ -278,7 +285,15 @@ occurred this differs from other types of \s-1BIO\s0 which will typically return
.IX Header "SEE ALSO"
\&\fIBIO_seek\fR\|(3), \fIBIO_tell\fR\|(3),
\&\fIBIO_reset\fR\|(3), \fIBIO_flush\fR\|(3),
\&\fIBIO_read\fR\|(3),
\&\fIBIO_write\fR\|(3), \fIBIO_puts\fR\|(3),
\&\fIBIO_read_ex\fR\|(3),
\&\fIBIO_write_ex\fR\|(3), \fIBIO_puts\fR\|(3),
\&\fIBIO_gets\fR\|(3), \fIBIO_printf\fR\|(3),
\&\fIBIO_set_close\fR\|(3), \fIBIO_get_close\fR\|(3)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

67
secure/lib/libcrypto/man/BIO_s_mem.3
View file

@ -128,37 +128,40 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BIO_s_mem 3"
.TH BIO_s_mem 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "BIO_S_MEM 3"
.TH BIO_S_MEM 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
BIO_s_mem, BIO_set_mem_eof_return, BIO_get_mem_data, BIO_set_mem_buf,
BIO_get_mem_ptr, BIO_new_mem_buf \- memory BIO
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
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bio.h>
\&
\& BIO_METHOD * BIO_s_mem(void);
\& const BIO_METHOD *BIO_s_mem(void);
\& const BIO_METHOD *BIO_s_secmem(void);
\&
\& BIO_set_mem_eof_return(BIO *b,int v)
\& BIO_set_mem_eof_return(BIO *b, int v)
\& long BIO_get_mem_data(BIO *b, char **pp)
\& BIO_set_mem_buf(BIO *b,BUF_MEM *bm,int c)
\& BIO_get_mem_ptr(BIO *b,BUF_MEM **pp)
\& BIO_set_mem_buf(BIO *b, BUF_MEM *bm, int c)
\& BIO_get_mem_ptr(BIO *b, BUF_MEM **pp)
\&
\& BIO *BIO_new_mem_buf(const void *buf, int len);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fIBIO_s_mem()\fR return the memory \s-1BIO\s0 method function.
\&\fIBIO_s_mem()\fR returns the memory \s-1BIO\s0 method function.
.PP
A memory \s-1BIO\s0 is a source/sink \s-1BIO\s0 which uses memory for its I/O. Data
written to a memory \s-1BIO\s0 is stored in a \s-1BUF_MEM\s0 structure which is extended
as appropriate to accommodate the stored data.
.PP
\&\fIBIO_s_secmem()\fR is like \fIBIO_s_mem()\fR except that the secure heap is used
for buffer storage.
.PP
Any data written to a memory \s-1BIO\s0 can be recalled by reading from it.
Unless the memory \s-1BIO\s0 is read only any data read from it is deleted from
the \s-1BIO.\s0
@ -168,9 +171,10 @@ Memory BIOs support \fIBIO_gets()\fR and \fIBIO_puts()\fR.
If the \s-1BIO_CLOSE\s0 flag is set when a memory \s-1BIO\s0 is freed then the underlying
\&\s-1BUF_MEM\s0 structure is also freed.
.PP
Calling \fIBIO_reset()\fR on a read write memory \s-1BIO\s0 clears any data in it. On a
read only \s-1BIO\s0 it restores the \s-1BIO\s0 to its original state and the read only
data can be read again.
Calling \fIBIO_reset()\fR on a read write memory \s-1BIO\s0 clears any data in it if the
flag \s-1BIO_FLAGS_NONCLEAR_RST\s0 is not set. On a read only \s-1BIO\s0 or if the flag
\&\s-1BIO_FLAGS_NONCLEAR_RST\s0 is set it restores the \s-1BIO\s0 to its original state and
the data can be read again.
.PP
\&\fIBIO_eof()\fR is true if no data is in the \s-1BIO.\s0
.PP
@ -210,40 +214,51 @@ an internal copy operation, if a \s-1BIO\s0 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 \s-1BIO\s0 avoids this problem. If the \s-1BIO\s0 must be read write then adding
a buffering \s-1BIO\s0 to the chain will speed up the process.
.PP
Calling \fIBIO_set_mem_buf()\fR on a \s-1BIO\s0 created with \fIBIO_new_secmem()\fR will
give undefined results, including perhaps a program crash.
.SH "BUGS"
.IX Header "BUGS"
There should be an option to set the maximum size of a memory \s-1BIO.\s0
.PP
There should be a way to \*(L"rewind\*(R" a read write \s-1BIO\s0 without destroying
its contents.
.PP
The copying operation should not occur after every small read of a large \s-1BIO\s0
to improve efficiency.
.SH "EXAMPLE"
.IX Header "EXAMPLE"
Create a memory \s-1BIO\s0 and write some data to it:
.PP
.Vb 2
.Vb 1
\& BIO *mem = BIO_new(BIO_s_mem());
\&
\& BIO_puts(mem, "Hello World\en");
.Ve
.PP
Create a read only memory \s-1BIO:\s0
.PP
.Vb 3
.Vb 2
\& char data[] = "Hello World";
\& BIO *mem;
\& mem = BIO_new_mem_buf(data, \-1);
\& BIO *mem = BIO_new_mem_buf(data, \-1);
.Ve
.PP
Extract the \s-1BUF_MEM\s0 structure from a memory \s-1BIO\s0 and then free up the \s-1BIO:\s0
.PP
.Vb 4
.Vb 1
\& 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);
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1TBA\s0
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fIBIO_s_mem()\fR and \fIBIO_s_secmem()\fR return a valid memory \fB\s-1BIO_METHOD\s0\fR structure.
.PP
\&\fIBIO_set_mem_eof_return()\fR, \fIBIO_get_mem_data()\fR, \fIBIO_set_mem_buf()\fR and \fIBIO_get_mem_ptr()\fR
return 1 on success or a value which is less than or equal to 0 if an error occurred.
.PP
\&\fIBIO_new_mem_buf()\fR returns a valid \fB\s-1BIO\s0\fR structure on success or \s-1NULL\s0 on error.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

17
secure/lib/libcrypto/man/BIO_s_null.3
View file

@ -128,8 +128,8 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BIO_s_null 3"
.TH BIO_s_null 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "BIO_S_NULL 3"
.TH BIO_S_NULL 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
@ -141,7 +141,7 @@ BIO_s_null \- null data sink
.Vb 1
\& #include <openssl/bio.h>
\&
\& BIO_METHOD * BIO_s_null(void);
\& const BIO_METHOD *BIO_s_null(void);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
@ -162,6 +162,11 @@ by adding a null sink \s-1BIO\s0 to the end of the chain
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fIBIO_s_null()\fR returns the null sink \s-1BIO\s0 method.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1TBA\s0
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

35
secure/lib/libcrypto/man/BIO_s_socket.3
View file

@ -128,8 +128,8 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BIO_s_socket 3"
.TH BIO_s_socket 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "BIO_S_SOCKET 3"
.TH BIO_S_SOCKET 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
@ -141,10 +141,7 @@ BIO_s_socket, BIO_new_socket \- socket BIO
.Vb 1
\& #include <openssl/bio.h>
\&
\& BIO_METHOD *BIO_s_socket(void);
\&
\& long BIO_set_fd(BIO *b, int fd, long close_flag);
\& long BIO_get_fd(BIO *b, int *c);
\& const BIO_METHOD *BIO_s_socket(void);
\&
\& BIO *BIO_new_socket(int sock, int close_flag);
.Ve
@ -153,18 +150,12 @@ BIO_s_socket, BIO_new_socket \- socket BIO
\&\fIBIO_s_socket()\fR returns the socket \s-1BIO\s0 method. This is a wrapper
round the platform's socket routines.
.PP
\&\fIBIO_read()\fR and \fIBIO_write()\fR read or write the underlying socket.
\&\fIBIO_read_ex()\fR and \fIBIO_write_ex()\fR read or write the underlying socket.
\&\fIBIO_puts()\fR is supported but \fIBIO_gets()\fR is not.
.PP
If the close flag is set then the socket is shut down and closed
when the \s-1BIO\s0 is freed.
.PP
\&\fIBIO_set_fd()\fR sets the socket of \s-1BIO\s0 \fBb\fR to \fBfd\fR and the close
flag to \fBclose_flag\fR.
.PP
\&\fIBIO_get_fd()\fR places the socket in \fBc\fR if it is not \s-1NULL,\s0 it also
returns the socket. If \fBc\fR is not \s-1NULL\s0 it should be of type (int *).
.PP
\&\fIBIO_new_socket()\fR returns a socket \s-1BIO\s0 using \fBsock\fR and \fBclose_flag\fR.
.SH "NOTES"
.IX Header "NOTES"
@ -175,19 +166,17 @@ 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.
.PP
\&\fIBIO_set_fd()\fR and \fIBIO_get_fd()\fR are macros.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fIBIO_s_socket()\fR returns the socket \s-1BIO\s0 method.
.PP
\&\fIBIO_set_fd()\fR always returns 1.
.PP
\&\fIBIO_get_fd()\fR returns the socket or \-1 if the \s-1BIO\s0 has not been
initialized.
.PP
\&\fIBIO_new_socket()\fR returns the newly allocated \s-1BIO\s0 or \s-1NULL\s0 is an error
occurred.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1TBA\s0
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

259
secure/lib/libcrypto/man/BIO_set_callback.3
View file

@ -128,102 +128,261 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BIO_set_callback 3"
.TH BIO_set_callback 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "BIO_SET_CALLBACK 3"
.TH BIO_SET_CALLBACK 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
BIO_set_callback, BIO_get_callback, BIO_set_callback_arg, BIO_get_callback_arg,
BIO_debug_callback \- BIO callback functions
BIO_set_callback_ex, BIO_get_callback_ex, BIO_set_callback, BIO_get_callback, BIO_set_callback_arg, BIO_get_callback_arg, BIO_debug_callback, BIO_callback_fn_ex, BIO_callback_fn \&\- BIO callback functions
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bio.h>
\&
\& #define BIO_set_callback(b,cb) ((b)\->callback=(cb))
\& #define BIO_get_callback(b) ((b)\->callback)
\& #define BIO_set_callback_arg(b,arg) ((b)\->cb_arg=(char *)(arg))
\& #define BIO_get_callback_arg(b) ((b)\->cb_arg)
\& typedef long (*BIO_callback_fn_ex)(BIO *b, int oper, const char *argp,
\& size_t len, int argi,
\& long argl, int ret, size_t *processed);
\& typedef long (*BIO_callback_fn)(BIO *b, int oper, const char *argp, int argi,
\& long argl, long ret);
\&
\& long BIO_debug_callback(BIO *bio,int cmd,const char *argp,int argi,
\& long argl,long ret);
\& void BIO_set_callback_ex(BIO *b, BIO_callback_fn_ex callback);
\& BIO_callback_fn_ex BIO_get_callback_ex(const BIO *b);
\&
\& typedef long (*callback)(BIO *b, int oper, const char *argp,
\& int argi, long argl, long retvalue);
\& void BIO_set_callback(BIO *b, BIO_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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fIBIO_set_callback()\fR and \fIBIO_get_callback()\fR set and retrieve the \s-1BIO\s0 callback,
they are both macros. The callback is called during most high level \s-1BIO\s0
operations. It can be used for debugging purposes to trace operations on
a \s-1BIO\s0 or to modify its operation.
\&\fIBIO_set_callback_ex()\fR and \fIBIO_get_callback_ex()\fR set and retrieve the \s-1BIO\s0
callback. The callback is called during most high level \s-1BIO\s0 operations. It can
be used for debugging purposes to trace operations on a \s-1BIO\s0 or to modify its
operation.
.PP
\&\fIBIO_set_callback()\fR and \fIBIO_get_callback()\fR set and retrieve the old format \s-1BIO\s0
callback. New code should not use these functions, but they are retained for
backwards compatibility. Any callback set via \fIBIO_set_callback_ex()\fR will get
called in preference to any set by \fIBIO_set_callback()\fR.
.PP
\&\fIBIO_set_callback_arg()\fR and \fIBIO_get_callback_arg()\fR are macros which can be
used to set and retrieve an argument for use in the callback.
.PP
\&\fIBIO_debug_callback()\fR is a standard debugging callback which prints
out information relating to each \s-1BIO\s0 operation. If the callback
argument is set if is interpreted as a \s-1BIO\s0 to send the information
argument is set it is interpreted as a \s-1BIO\s0 to send the information
to, otherwise stderr is used.
.PP
\&\fIcallback()\fR is the callback function itself. The meaning of each
argument is described below.
.PP
\&\fIBIO_callback_fn_ex()\fR is the type of the callback function and \fIBIO_callback_fn()\fR
is the type of the old format callback function. The meaning of each argument
is described below:
.IP "\fBb\fR" 4
.IX Item "b"
The \s-1BIO\s0 the callback is attached to is passed in \fBb\fR.
.PP
.IP "\fBoper\fR" 4
.IX Item "oper"
\&\fBoper\fR 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 \fBoper\fR or'ed with \s-1BIO_CB_RETURN.\s0
.PP
.IP "\fBlen\fR" 4
.IX Item "len"
The length of the data requested to be read or written. This is only useful if
\&\fBoper\fR is \s-1BIO_CB_READ, BIO_CB_WRITE\s0 or \s-1BIO_CB_GETS.\s0
.IP "\fBargp\fR \fBargi\fR \fBargl\fR" 4
.IX Item "argp argi argl"
The meaning of the arguments \fBargp\fR, \fBargi\fR and \fBargl\fR depends on
the value of \fBoper\fR, that is the operation being performed.
.PP
\&\fBretvalue\fR is the return value that would be returned to the
.IP "\fBprocessed\fR" 4
.IX Item "processed"
\&\fBprocessed\fR is a pointer to a location which will be updated with the amount of
data that was actually read or written. Only used for \s-1BIO_CB_READ, BIO_CB_WRITE,
BIO_CB_GETS\s0 and \s-1BIO_CB_PUTS.\s0
.IP "\fBret\fR" 4
.IX Item "ret"
\&\fBret\fR 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 \s-1BIO\s0 operation 1 is placed in retvalue, if
called before the actual \s-1BIO\s0 operation 1 is placed in \fBret\fR, if
the return value is not positive it will be immediately returned to
the application and the \s-1BIO\s0 operation will not be performed.
.PP
The callback should normally simply return \fBretvalue\fR when it has
finished processing, unless if specifically wishes to modify the
The callback should normally simply return \fBret\fR when it has
finished processing, unless it specifically wishes to modify the
value returned to the application.
.SH "CALLBACK OPERATIONS"
.IX Header "CALLBACK OPERATIONS"
In the notes below, \fBcallback\fR defers to the actual callback
function that is called.
.IP "\fBBIO_free(b)\fR" 4
.IX Item "BIO_free(b)"
callback(b, \s-1BIO_CB_FREE, NULL, 0L, 0L, 1L\s0) is called before the
free operation.
.IP "\fBBIO_read(b, out, outl)\fR" 4
.IX Item "BIO_read(b, out, outl)"
callback(b, \s-1BIO_CB_READ,\s0 out, outl, 0L, 1L) is called before
the read and callback(b, BIO_CB_READ|BIO_CB_RETURN, out, outl, 0L, retvalue)
.Vb 1
\& callback_ex(b, BIO_CB_FREE, NULL, 0, 0, 0L, 1L, NULL)
.Ve
.Sp
or
.Sp
.Vb 1
\& callback(b, BIO_CB_FREE, NULL, 0L, 0L, 1L)
.Ve
.Sp
is called before the free operation.
.IP "\fBBIO_read_ex(b, data, dlen, readbytes)\fR" 4
.IX Item "BIO_read_ex(b, data, dlen, readbytes)"
.Vb 1
\& callback_ex(b, BIO_CB_READ, data, dlen, 0, 0L, 1L, NULL)
.Ve
.Sp
or
.Sp
.Vb 1
\& callback(b, BIO_CB_READ, data, dlen, 0L, 1L)
.Ve
.Sp
is called before the read and
.Sp
.Vb 2
\& callback_ex(b, BIO_CB_READ | BIO_CB_RETURN, data, dlen, 0, 0L, retvalue,
\& &readbytes)
.Ve
.Sp
or
.Sp
.Vb 1
\& callback(b, BIO_CB_READ|BIO_CB_RETURN, data, dlen, 0L, retvalue)
.Ve
.Sp
after.
.IP "\fBBIO_write(b, in, inl)\fR" 4
.IX Item "BIO_write(b, in, inl)"
callback(b, \s-1BIO_CB_WRITE,\s0 in, inl, 0L, 1L) is called before
the write and callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, inl, 0L, retvalue)
.IP "\fBBIO_write(b, data, dlen, written)\fR" 4
.IX Item "BIO_write(b, data, dlen, written)"
.Vb 1
\& callback_ex(b, BIO_CB_WRITE, data, dlen, 0, 0L, 1L, NULL)
.Ve
.Sp
or
.Sp
.Vb 1
\& callback(b, BIO_CB_WRITE, datat, dlen, 0L, 1L)
.Ve
.Sp
is called before the write and
.Sp
.Vb 2
\& callback_ex(b, BIO_CB_WRITE | BIO_CB_RETURN, data, dlen, 0, 0L, retvalue,
\& &written)
.Ve
.Sp
or
.Sp
.Vb 1
\& callback(b, BIO_CB_WRITE|BIO_CB_RETURN, data, dlen, 0L, retvalue)
.Ve
.Sp
after.
.IP "\fBBIO_gets(b, out, outl)\fR" 4
.IX Item "BIO_gets(b, out, outl)"
callback(b, \s-1BIO_CB_GETS,\s0 out, outl, 0L, 1L) is called before
the operation and callback(b, BIO_CB_GETS|BIO_CB_RETURN, out, outl, 0L, retvalue)
.IP "\fBBIO_gets(b, buf, size)\fR" 4
.IX Item "BIO_gets(b, buf, size)"
.Vb 1
\& callback_ex(b, BIO_CB_GETS, buf, size, 0, 0L, 1, NULL, NULL)
.Ve
.Sp
or
.Sp
.Vb 1
\& callback(b, BIO_CB_GETS, buf, size, 0L, 1L)
.Ve
.Sp
is called before the operation and
.Sp
.Vb 2
\& callback_ex(b, BIO_CB_GETS | BIO_CB_RETURN, buf, size, 0, 0L, retvalue,
\& &readbytes)
.Ve
.Sp
or
.Sp
.Vb 1
\& callback(b, BIO_CB_GETS|BIO_CB_RETURN, buf, size, 0L, retvalue)
.Ve
.Sp
after.
.IP "\fBBIO_puts(b, in)\fR" 4
.IX Item "BIO_puts(b, in)"
callback(b, \s-1BIO_CB_WRITE,\s0 in, 0, 0L, 1L) is called before
the operation and callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, 0, 0L, retvalue)
.IP "\fBBIO_puts(b, buf)\fR" 4
.IX Item "BIO_puts(b, buf)"
.Vb 1
\& callback_ex(b, BIO_CB_PUTS, buf, 0, 0, 0L, 1L, NULL);
.Ve
.Sp
or
.Sp
.Vb 1
\& callback(b, BIO_CB_PUTS, buf, 0, 0L, 1L)
.Ve
.Sp
is called before the operation and
.Sp
.Vb 1
\& callback_ex(b, BIO_CB_PUTS | BIO_CB_RETURN, buf, 0, 0, 0L, retvalue, &written)
.Ve
.Sp
or
.Sp
.Vb 1
\& callback(b, BIO_CB_PUTS|BIO_CB_RETURN, buf, 0, 0L, retvalue)
.Ve
.Sp
after.
.IP "\fBBIO_ctrl(\s-1BIO\s0 *b, int cmd, long larg, void *parg)\fR" 4
.IX Item "BIO_ctrl(BIO *b, int cmd, long larg, void *parg)"
callback(b,BIO_CB_CTRL,parg,cmd,larg,1L) is called before the call and
callback(b,BIO_CB_CTRL|BIO_CB_RETURN,parg,cmd, larg,ret) after.
.Vb 1
\& callback_ex(b, BIO_CB_CTRL, parg, 0, cmd, larg, 1L, NULL)
.Ve
.Sp
or
.Sp
.Vb 1
\& callback(b, BIO_CB_CTRL, parg, cmd, larg, 1L)
.Ve
.Sp
is called before the call and
.Sp
.Vb 1
\& callback_ex(b, BIO_CB_CTRL | BIO_CB_RETURN, parg, 0, cmd, larg, ret, NULL)
.Ve
.Sp
or
.Sp
.Vb 1
\& callback(b, BIO_CB_CTRL|BIO_CB_RETURN, parg, cmd, larg, ret)
.Ve
.Sp
after.
.Sp
Note: \fBcmd\fR == \fB\s-1BIO_CTRL_SET_CALLBACK\s0\fR is special, because \fBparg\fR is not the
argument of type \fBBIO_info_cb\fR itself. In this case \fBparg\fR is a pointer to
the actual call parameter, see \fBBIO_callback_ctrl\fR.
.SH "EXAMPLE"
.IX Header "EXAMPLE"
The \fIBIO_debug_callback()\fR function is a good example, its source is
in crypto/bio/bio_cb.c
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1TBA\s0
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fIBIO_get_callback_ex()\fR and \fIBIO_get_callback()\fR return the callback function
previously set by a call to \fIBIO_set_callback_ex()\fR and \fIBIO_set_callback()\fR
respectively.
.PP
\&\fIBIO_get_callback_arg()\fR returns a \fBchar\fR pointer to the value previously set
via a call to \fIBIO_set_callback_arg()\fR.
.PP
\&\fIBIO_debug_callback()\fR returns 1 or \fBret\fR if it's called after specific \s-1BIO\s0
operations.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

77
secure/lib/libcrypto/man/BIO_should_retry.3
View file

@ -128,40 +128,33 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BIO_should_retry 3"
.TH BIO_should_retry 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "BIO_SHOULD_RETRY 3"
.TH BIO_SHOULD_RETRY 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
BIO_should_retry, BIO_should_read, BIO_should_write,
BIO_should_io_special, BIO_retry_type, BIO_should_retry,
BIO_get_retry_BIO, BIO_get_retry_reason \- BIO retry functions
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
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bio.h>
\&
\& #define BIO_should_read(a) ((a)\->flags & BIO_FLAGS_READ)
\& #define BIO_should_write(a) ((a)\->flags & BIO_FLAGS_WRITE)
\& #define BIO_should_io_special(a) ((a)\->flags & BIO_FLAGS_IO_SPECIAL)
\& #define BIO_retry_type(a) ((a)\->flags & BIO_FLAGS_RWS)
\& #define BIO_should_retry(a) ((a)\->flags & BIO_FLAGS_SHOULD_RETRY)
\& int BIO_should_read(BIO *b);
\& int BIO_should_write(BIO *b);
\& int BIO_should_io_special(iBIO *b);
\& int BIO_retry_type(BIO *b);
\& int BIO_should_retry(BIO *b);
\&
\& #define BIO_FLAGS_READ 0x01
\& #define BIO_FLAGS_WRITE 0x02
\& #define BIO_FLAGS_IO_SPECIAL 0x04
\& #define BIO_FLAGS_RWS (BIO_FLAGS_READ|BIO_FLAGS_WRITE|BIO_FLAGS_IO_SPECIAL)
\& #define BIO_FLAGS_SHOULD_RETRY 0x08
\&
\& BIO * BIO_get_retry_BIO(BIO *bio, int *reason);
\& int BIO_get_retry_reason(BIO *bio);
\& BIO *BIO_get_retry_BIO(BIO *bio, int *reason);
\& int BIO_get_retry_reason(BIO *bio);
\& void BIO_set_retry_reason(BIO *bio, int reason);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
These functions determine why a \s-1BIO\s0 is not able to read or write data.
They will typically be called after a failed \fIBIO_read()\fR or \fIBIO_write()\fR
They will typically be called after a failed \fIBIO_read_ex()\fR or \fIBIO_write_ex()\fR
call.
.PP
\&\fIBIO_should_retry()\fR is true if the call that produced this condition
@ -169,11 +162,13 @@ should then be retried at a later time.
.PP
If \fIBIO_should_retry()\fR is false then the cause is an error condition.
.PP
\&\fIBIO_should_read()\fR is true if the cause of the condition is that a \s-1BIO\s0
needs to read data.
\&\fIBIO_should_read()\fR is true if the cause of the condition is that the \s-1BIO\s0
has insufficient data to return. Check for readability and/or retry the
last operation.
.PP
\&\fIBIO_should_write()\fR is true if the cause of the condition is that a \s-1BIO\s0
needs to read data.
\&\fIBIO_should_write()\fR is true if the cause of the condition is that the \s-1BIO\s0
has pending data to write. Check for writability and/or retry the
last operation.
.PP
\&\fIBIO_should_io_special()\fR is true if some \*(L"special\*(R" condition, that is a
reason other than reading or writing is the cause of the condition.
@ -184,18 +179,24 @@ consisting of the values \fB\s-1BIO_FLAGS_READ\s0\fR, \fB\s-1BIO_FLAGS_WRITE\s0\
these.
.PP
\&\fIBIO_get_retry_BIO()\fR determines the precise reason for the special
condition, it returns the \s-1BIO\s0 that caused this condition and if
condition, it returns the \s-1BIO\s0 that caused this condition and if
\&\fBreason\fR is not \s-1NULL\s0 it contains the reason code. The meaning of
the reason code and the action that should be taken depends on
the type of \s-1BIO\s0 that resulted in this condition.
.PP
\&\fIBIO_get_retry_reason()\fR returns the reason for a special condition if
passed the relevant \s-1BIO,\s0 for example as returned by \fIBIO_get_retry_BIO()\fR.
.PP
\&\fIBIO_set_retry_reason()\fR sets the retry reason for a special condition for a given
\&\s-1BIO.\s0 This would usually only be called by \s-1BIO\s0 implementations.
.SH "NOTES"
.IX Header "NOTES"
\&\fIBIO_should_read()\fR, \fIBIO_should_write()\fR, \fIBIO_should_io_special()\fR,
\&\fIBIO_retry_type()\fR, and \fIBIO_should_retry()\fR, are implemented as macros.
.PP
If \fIBIO_should_retry()\fR returns false then the precise \*(L"error condition\*(R"
depends on the \s-1BIO\s0 type that caused it and the return code of the \s-1BIO\s0
operation. For example if a call to \fIBIO_read()\fR on a socket \s-1BIO\s0 returns
operation. For example if a call to \fIBIO_read_ex()\fR on a socket \s-1BIO\s0 returns
0 and \fIBIO_should_retry()\fR is false then the cause will be that the
connection closed. A similar condition on a file \s-1BIO\s0 will mean that it
has reached \s-1EOF.\s0 Some \s-1BIO\s0 types may place additional information on
@ -239,6 +240,30 @@ The OpenSSL \s-1ASN1\s0 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 \s-1ASN1\s0 functions when
the entire structure can be read or written.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fIBIO_should_read()\fR, \fIBIO_should_write()\fR, \fIBIO_should_io_special()\fR, and
\&\fIBIO_should_retry()\fR return either 1 or 0 based on the actual conditions
of the \fB\s-1BIO\s0\fR.
.PP
\&\fIBIO_retry_type()\fR returns a flag combination presenting the cause of a retry
condition or false if there is no retry condition.
.PP
\&\fIBIO_get_retry_BIO()\fR returns a valid \fB\s-1BIO\s0\fR structure.
.PP
\&\fIBIO_get_retry_reason()\fR returns the reason for a special condition.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1TBA\s0
bio
.SH "HISTORY"
.IX Header "HISTORY"
The \fIBIO_get_retry_reason()\fR and \fIBIO_set_retry_reason()\fR functions were added in
OpenSSL 1.1.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

86
secure/lib/libcrypto/man/BN_BLINDING_new.3
View file

@ -128,45 +128,44 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BN_BLINDING_new 3"
.TH BN_BLINDING_new 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "BN_BLINDING_NEW 3"
.TH BN_BLINDING_NEW 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
BN_BLINDING_new, BN_BLINDING_free, BN_BLINDING_update, BN_BLINDING_convert,
BN_BLINDING_invert, BN_BLINDING_convert_ex, BN_BLINDING_invert_ex,
BN_BLINDING_get_thread_id, BN_BLINDING_set_thread_id, BN_BLINDING_thread_id, BN_BLINDING_get_flags,
BN_BLINDING_set_flags, BN_BLINDING_create_param \- blinding related BIGNUM
functions.
BN_BLINDING_new, BN_BLINDING_free, BN_BLINDING_update, BN_BLINDING_convert, BN_BLINDING_invert, BN_BLINDING_convert_ex, BN_BLINDING_invert_ex, BN_BLINDING_is_current_thread, BN_BLINDING_set_current_thread, BN_BLINDING_lock, BN_BLINDING_unlock, BN_BLINDING_get_flags, BN_BLINDING_set_flags, BN_BLINDING_create_param \- blinding related BIGNUM functions
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bn.h>
\&
\& BN_BLINDING *BN_BLINDING_new(const BIGNUM *A, const BIGNUM *Ai,
\& BIGNUM *mod);
\& BIGNUM *mod);
\& void BN_BLINDING_free(BN_BLINDING *b);
\& int BN_BLINDING_update(BN_BLINDING *b,BN_CTX *ctx);
\& int BN_BLINDING_update(BN_BLINDING *b, BN_CTX *ctx);
\& int BN_BLINDING_convert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx);
\& int BN_BLINDING_invert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx);
\& int BN_BLINDING_convert_ex(BIGNUM *n, BIGNUM *r, BN_BLINDING *b,
\& BN_CTX *ctx);
\& BN_CTX *ctx);
\& int BN_BLINDING_invert_ex(BIGNUM *n, const BIGNUM *r, BN_BLINDING *b,
\& BN_CTX *ctx);
\& #ifndef OPENSSL_NO_DEPRECATED
\& unsigned long BN_BLINDING_get_thread_id(const BN_BLINDING *);
\& void BN_BLINDING_set_thread_id(BN_BLINDING *, unsigned long);
\& #endif
\& CRYPTO_THREADID *BN_BLINDING_thread_id(BN_BLINDING *);
\& BN_CTX *ctx);
\& int BN_BLINDING_is_current_thread(BN_BLINDING *b);
\& void BN_BLINDING_set_current_thread(BN_BLINDING *b);
\& int BN_BLINDING_lock(BN_BLINDING *b);
\& int BN_BLINDING_unlock(BN_BLINDING *b);
\& unsigned long BN_BLINDING_get_flags(const BN_BLINDING *);
\& void BN_BLINDING_set_flags(BN_BLINDING *, unsigned long);
\& BN_BLINDING *BN_BLINDING_create_param(BN_BLINDING *b,
\& const BIGNUM *e, BIGNUM *m, BN_CTX *ctx,
\& int (*bn_mod_exp)(BIGNUM *r, const BIGNUM *a, const BIGNUM *p,
\& const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx),
\& BN_MONT_CTX *m_ctx);
\& const BIGNUM *e, BIGNUM *m, BN_CTX *ctx,
\& int (*bn_mod_exp)(BIGNUM *r,
\& const BIGNUM *a,
\& const BIGNUM *p,
\& const BIGNUM *m,
\& BN_CTX *ctx,
\& BN_MONT_CTX *m_ctx),
\& BN_MONT_CTX *m_ctx);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
@ -174,6 +173,7 @@ functions.
the \fBA\fR and \fBAi\fR values into the newly created \fB\s-1BN_BLINDING\s0\fR object.
.PP
\&\fIBN_BLINDING_free()\fR frees the \fB\s-1BN_BLINDING\s0\fR structure.
If \fBb\fR is \s-1NULL,\s0 nothing is done.
.PP
\&\fIBN_BLINDING_update()\fR updates the \fB\s-1BN_BLINDING\s0\fR parameters by squaring
the \fBA\fR and \fBAi\fR or, after specific number of uses and if the
@ -190,11 +190,16 @@ the inverse blinding.
functions for \fIBN_BLINDING_convert_ex()\fR and \fIBN_BLINDING_invert_ex()\fR
with \fBr\fR set to \s-1NULL.\s0
.PP
\&\fIBN_BLINDING_thread_id()\fR provides access to the \fB\s-1CRYPTO_THREADID\s0\fR
object within the \fB\s-1BN_BLINDING\s0\fR structure. This is to help users
provide proper locking if needed for multi-threaded use. The \*(L"thread
id\*(R" object of a newly allocated \fB\s-1BN_BLINDING\s0\fR structure is
initialised to the thread id in which \fIBN_BLINDING_new()\fR was called.
\&\fIBN_BLINDING_is_current_thread()\fR returns whether the \fB\s-1BN_BLINDING\s0\fR
structure is owned by the current thread. This is to help users
provide proper locking if needed for multi-threaded use.
.PP
\&\fIBN_BLINDING_set_current_thread()\fR sets the current thread as the
owner of the \fB\s-1BN_BLINDING\s0\fR structure.
.PP
\&\fIBN_BLINDING_lock()\fR locks the \fB\s-1BN_BLINDING\s0\fR structure.
.PP
\&\fIBN_BLINDING_unlock()\fR unlocks the \fB\s-1BN_BLINDING\s0\fR structure.
.PP
\&\fIBN_BLINDING_get_flags()\fR returns the \s-1BN_BLINDING\s0 flags. Currently
there are two supported flags: \fB\s-1BN_BLINDING_NO_UPDATE\s0\fR and
@ -218,25 +223,28 @@ or \s-1NULL\s0 in case of an error.
\&\fIBN_BLINDING_convert_ex()\fR and \fIBN_BLINDING_invert_ex()\fR return 1 on
success and 0 if an error occurred.
.PP
\&\fIBN_BLINDING_thread_id()\fR returns a pointer to the thread id object
within a \fB\s-1BN_BLINDING\s0\fR object.
\&\fIBN_BLINDING_is_current_thread()\fR returns 1 if the current thread owns
the \fB\s-1BN_BLINDING\s0\fR object, 0 otherwise.
.PP
\&\fIBN_BLINDING_set_current_thread()\fR doesn't return anything.
.PP
\&\fIBN_BLINDING_lock()\fR, \fIBN_BLINDING_unlock()\fR return 1 if the operation
succeeded or 0 on error.
.PP
\&\fIBN_BLINDING_get_flags()\fR returns the currently set \fB\s-1BN_BLINDING\s0\fR flags
(a \fBunsigned long\fR value).
.PP
\&\fIBN_BLINDING_create_param()\fR returns the newly created \fB\s-1BN_BLINDING\s0\fR
\&\fIBN_BLINDING_create_param()\fR returns the newly created \fB\s-1BN_BLINDING\s0\fR
parameters or \s-1NULL\s0 on error.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIbn\fR\|(3)
.SH "HISTORY"
.IX Header "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.
\&\fIBN_BLINDING_thread_id()\fR was first introduced in OpenSSL 1.0.0, and it
deprecates \fIBN_BLINDING_set_thread_id()\fR and \fIBN_BLINDING_get_thread_id()\fR.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2005\-2017 The OpenSSL Project Authors. All Rights Reserved.
.PP
BN_BLINDING_convert_ex, BN_BLINDIND_invert_ex, BN_BLINDING_get_thread_id,
BN_BLINDING_set_thread_id, BN_BLINDING_set_flags, BN_BLINDING_get_flags
and BN_BLINDING_create_param were first introduced in OpenSSL 0.9.8
.SH "AUTHOR"
.IX Header "AUTHOR"
Nils Larsch for the OpenSSL project (http://www.openssl.org).
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

71
secure/lib/libcrypto/man/BN_CTX_new.3
View file

@ -128,14 +128,14 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BN_CTX_new 3"
.TH BN_CTX_new 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "BN_CTX_NEW 3"
.TH BN_CTX_NEW 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
BN_CTX_new, BN_CTX_init, BN_CTX_free \- allocate and free BN_CTX structures
BN_CTX_new, BN_CTX_secure_new, BN_CTX_free \- allocate and free BN_CTX structures
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
@ -143,14 +143,10 @@ BN_CTX_new, BN_CTX_init, BN_CTX_free \- allocate and free BN_CTX structures
\&
\& BN_CTX *BN_CTX_new(void);
\&
\& BN_CTX *BN_CTX_secure_new(void);
\&
\& void BN_CTX_free(BN_CTX *c);
.Ve
.PP
Deprecated:
.PP
.Vb 1
\& void BN_CTX_init(BN_CTX *c);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
A \fB\s-1BN_CTX\s0\fR is a structure that holds \fB\s-1BIGNUM\s0\fR temporary variables used by
@ -158,29 +154,56 @@ library functions. Since dynamic memory allocation to create \fB\s-1BIGNUM\s0\fR
is rather expensive when used in conjunction with repeated subroutine
calls, the \fB\s-1BN_CTX\s0\fR structure is used.
.PP
\&\fIBN_CTX_new()\fR allocates and initializes a \fB\s-1BN_CTX\s0\fR
structure.
\&\fIBN_CTX_new()\fR allocates and initializes a \fB\s-1BN_CTX\s0\fR structure.
\&\fIBN_CTX_secure_new()\fR allocates and initializes a \fB\s-1BN_CTX\s0\fR structure
but uses the secure heap (see \fICRYPTO_secure_malloc\fR\|(3)) to hold the
\&\fB\s-1BIGNUM\s0\fRs.
.PP
\&\fIBN_CTX_free()\fR frees the components of the \fB\s-1BN_CTX\s0\fR, and if it was
created by \fIBN_CTX_new()\fR, also the structure itself.
If \fIBN_CTX_start\fR\|(3) has been used on the \fB\s-1BN_CTX\s0\fR,
\&\fIBN_CTX_end\fR\|(3) must be called before the \fB\s-1BN_CTX\s0\fR
may be freed by \fIBN_CTX_free()\fR.
\&\fIBN_CTX_free()\fR frees the components of the \fB\s-1BN_CTX\s0\fR and the structure itself.
Since \fIBN_CTX_start()\fR is required in order to obtain \fB\s-1BIGNUM\s0\fRs from the
\&\fB\s-1BN_CTX\s0\fR, in most cases \fIBN_CTX_end()\fR must be called before the \fB\s-1BN_CTX\s0\fR may
be freed by \fIBN_CTX_free()\fR. If \fBc\fR is \s-1NULL,\s0 nothing is done.
.PP
\&\fIBN_CTX_init()\fR (deprecated) initializes an existing uninitialized \fB\s-1BN_CTX\s0\fR.
This should not be used for new programs. Use \fIBN_CTX_new()\fR instead.
A given \fB\s-1BN_CTX\s0\fR 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.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fIBN_CTX_new()\fR returns a pointer to the \fB\s-1BN_CTX\s0\fR. If the allocation fails,
it returns \fB\s-1NULL\s0\fR and sets an error code that can be obtained by
\&\fIBN_CTX_new()\fR and \fIBN_CTX_secure_new()\fR return a pointer to the \fB\s-1BN_CTX\s0\fR.
If the allocation fails,
they return \fB\s-1NULL\s0\fR and sets an error code that can be obtained by
\&\fIERR_get_error\fR\|(3).
.PP
\&\fIBN_CTX_init()\fR and \fIBN_CTX_free()\fR have no return values.
\&\fIBN_CTX_free()\fR has no return values.
.SH "REMOVED FUNCTIONALITY"
.IX Header "REMOVED FUNCTIONALITY"
.Vb 1
\& void BN_CTX_init(BN_CTX *c);
.Ve
.PP
\&\fIBN_CTX_init()\fR is no longer available as of OpenSSL 1.1.0. Applications should
replace use of BN_CTX_init with BN_CTX_new instead:
.PP
.Vb 6
\& BN_CTX *ctx;
\& ctx = BN_CTX_new();
\& if (!ctx)
\& /* error */
\& ...
\& BN_CTX_free(ctx);
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIbn\fR\|(3), \fIERR_get_error\fR\|(3), \fIBN_add\fR\|(3),
\&\fIERR_get_error\fR\|(3), \fIBN_add\fR\|(3),
\&\fIBN_CTX_start\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fIBN_CTX_new()\fR and \fIBN_CTX_free()\fR are available in all versions on SSLeay
and OpenSSL. \fIBN_CTX_init()\fR was added in SSLeay 0.9.1b.
\&\fIBN_CTX_init()\fR was removed in OpenSSL 1.1.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2017 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

15
secure/lib/libcrypto/man/BN_CTX_start.3
View file

@ -128,8 +128,8 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BN_CTX_start 3"
.TH BN_CTX_start 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "BN_CTX_START 3"
.TH BN_CTX_START 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
@ -174,6 +174,11 @@ can be obtained by \fIERR_get_error\fR\|(3).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIBN_CTX_new\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fIBN_CTX_start()\fR, \fIBN_CTX_get()\fR and \fIBN_CTX_end()\fR were added in OpenSSL 0.9.5.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

37
secure/lib/libcrypto/man/BN_add.3
View file

@ -128,16 +128,14 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BN_add 3"
.TH BN_add 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "BN_ADD 3"
.TH BN_ADD 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "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
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
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
@ -152,27 +150,27 @@ arithmetic operations on BIGNUMs
\& 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);
\& 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);
\& BN_CTX *ctx);
\&
\& int BN_mod_sub(BIGNUM *r, BIGNUM *a, BIGNUM *b, const BIGNUM *m,
\& BN_CTX *ctx);
\& BN_CTX *ctx);
\&
\& int BN_mod_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b, const BIGNUM *m,
\& BN_CTX *ctx);
\& 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);
\& const BIGNUM *m, BN_CTX *ctx);
\&
\& int BN_gcd(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx);
.Ve
@ -182,6 +180,7 @@ arithmetic operations on BIGNUMs
\&\fIr\fR may be the same \fB\s-1BIGNUM\s0\fR as \fIa\fR or \fIb\fR.
.PP
\&\fIBN_sub()\fR subtracts \fIb\fR from \fIa\fR and places the result in \fIr\fR (\f(CW\*(C`r=a\-b\*(C'\fR).
\&\fIr\fR may be the same \fB\s-1BIGNUM\s0\fR as \fIa\fR or \fIb\fR.
.PP
\&\fIBN_mul()\fR multiplies \fIa\fR and \fIb\fR and places the result in \fIr\fR (\f(CW\*(C`r=a*b\*(C'\fR).
\&\fIr\fR may be the same \fB\s-1BIGNUM\s0\fR as \fIa\fR or \fIb\fR.
@ -244,13 +243,13 @@ value should always be checked (e.g., \f(CW\*(C`if (!BN_add(r,a,b)) goto err;\*(
The error codes can be obtained by \fIERR_get_error\fR\|(3).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIbn\fR\|(3), \fIERR_get_error\fR\|(3), \fIBN_CTX_new\fR\|(3),
\&\fIERR_get_error\fR\|(3), \fIBN_CTX_new\fR\|(3),
\&\fIBN_add_word\fR\|(3), \fIBN_set_bit\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fIBN_add()\fR, \fIBN_sub()\fR, \fIBN_sqr()\fR, \fIBN_div()\fR, \fIBN_mod()\fR, \fIBN_mod_mul()\fR,
\&\fIBN_mod_exp()\fR and \fIBN_gcd()\fR are available in all versions of SSLeay and
OpenSSL. The \fIctx\fR argument to \fIBN_mul()\fR was added in SSLeay
0.9.1b. \fIBN_exp()\fR appeared in SSLeay 0.9.0.
\&\fIBN_nnmod()\fR, \fIBN_mod_add()\fR, \fIBN_mod_sub()\fR, and \fIBN_mod_sqr()\fR were added in
OpenSSL 0.9.7.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

23
secure/lib/libcrypto/man/BN_add_word.3
View file

@ -128,15 +128,14 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BN_add_word 3"
.TH BN_add_word 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "BN_ADD_WORD 3"
.TH BN_ADD_WORD 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
BN_add_word, BN_sub_word, BN_mul_word, BN_div_word, BN_mod_word \- arithmetic
functions on BIGNUMs with integers
BN_add_word, BN_sub_word, BN_mul_word, BN_div_word, BN_mod_word \- arithmetic functions on BIGNUMs with integers
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
@ -178,12 +177,12 @@ on error. The error codes can be obtained by \fIERR_get_error\fR\|(3).
\&\fB(\s-1BN_ULONG\s0)\-1\fR if an error occurred.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIbn\fR\|(3), \fIERR_get_error\fR\|(3), \fIBN_add\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fIBN_add_word()\fR and \fIBN_mod_word()\fR are available in all versions of
SSLeay and OpenSSL. \fIBN_div_word()\fR was added in SSLeay 0.8, and
\&\fIBN_sub_word()\fR and \fIBN_mul_word()\fR in SSLeay 0.9.0.
\&\fIERR_get_error\fR\|(3), \fIBN_add\fR\|(3)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2017 The OpenSSL Project Authors. All Rights Reserved.
.PP
Before 0.9.8a the return value for \fIBN_div_word()\fR and \fIBN_mod_word()\fR
in case of an error was 0.
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

47
secure/lib/libcrypto/man/BN_bn2bin.3
View file

@ -128,23 +128,26 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BN_bn2bin 3"
.TH BN_bn2bin 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "BN_BN2BIN 3"
.TH BN_BN2BIN 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
BN_bn2bin, BN_bin2bn, BN_bn2hex, BN_bn2dec, BN_hex2bn, BN_dec2bn,
BN_print, BN_print_fp, BN_bn2mpi, BN_mpi2bn \- format conversions
BN_bn2binpad, BN_bn2bin, BN_bin2bn, BN_bn2lebinpad, BN_lebin2bn, BN_bn2hex, BN_bn2dec, BN_hex2bn, BN_dec2bn, BN_print, BN_print_fp, BN_bn2mpi, BN_mpi2bn \- format conversions
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #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);
@ -162,20 +165,28 @@ BN_print, BN_print_fp, BN_bn2mpi, BN_mpi2bn \- format conversions
and stores it at \fBto\fR. \fBto\fR must point to BN_num_bytes(\fBa\fR) bytes of
memory.
.PP
\&\fIBN_bn2binpad()\fR also converts the absolute value of \fBa\fR into big-endian form
and stores it at \fBto\fR. \fBtolen\fR indicates the length of the output buffer
\&\fBto\fR. The result is padded with zeroes if necessary. If \fBtolen\fR is less than
BN_num_bytes(\fBa\fR) an error is returned.
.PP
\&\fIBN_bin2bn()\fR converts the positive integer in big-endian form of length
\&\fBlen\fR at \fBs\fR into a \fB\s-1BIGNUM\s0\fR and places it in \fBret\fR. If \fBret\fR is
\&\s-1NULL,\s0 a new \fB\s-1BIGNUM\s0\fR is created.
.PP
\&\fIBN_bn2lebinpad()\fR and \fIBN_lebin2bn()\fR are identical to \fIBN_bn2binpad()\fR and
\&\fIBN_bin2bn()\fR except the buffer is in little-endian format.
.PP
\&\fIBN_bn2hex()\fR and \fIBN_bn2dec()\fR return printable strings containing the
hexadecimal and decimal encoding of \fBa\fR respectively. For negative
numbers, the string is prefaced with a leading '\-'. The string must be
freed later using \fIOPENSSL_free()\fR.
.PP
\&\fIBN_hex2bn()\fR converts the string \fBstr\fR containing a hexadecimal number
to a \fB\s-1BIGNUM\s0\fR and stores it in **\fBa\fR. If *\fBa\fR is \s-1NULL,\s0 a new
\&\fB\s-1BIGNUM\s0\fR is created. If \fBa\fR is \s-1NULL,\s0 it only computes the number's
length in hexadecimal digits. If the string starts with '\-', the
number is negative.
\&\fIBN_hex2bn()\fR takes as many characters as possible from the string \fBstr\fR,
including the leading character '\-' which means negative, to form a valid
hexadecimal number representation and converts them to a \fB\s-1BIGNUM\s0\fR and
stores it in **\fBa\fR. If *\fBa\fR is \s-1NULL,\s0 a new \fB\s-1BIGNUM\s0\fR is created. If
\&\fBa\fR is \s-1NULL,\s0 it only computes the length of valid representation.
A \*(L"negative zero\*(R" is converted to zero.
\&\fIBN_dec2bn()\fR is the same using the decimal system.
.PP
@ -201,6 +212,9 @@ if \fBret\fR is \s-1NULL.\s0
\&\fIBN_bn2bin()\fR returns the length of the big-endian number placed at \fBto\fR.
\&\fIBN_bin2bn()\fR returns the \fB\s-1BIGNUM\s0\fR, \s-1NULL\s0 on error.
.PP
\&\fIBN_bn2binpad()\fR returns the number of bytes written or \-1 if the supplied
buffer is too small.
.PP
\&\fIBN_bn2hex()\fR and \fIBN_bn2dec()\fR return a null-terminated string, or \s-1NULL\s0
on error. \fIBN_hex2bn()\fR and \fIBN_dec2bn()\fR return the number of characters
used in parsing, or 0 on error, in which
@ -214,13 +228,14 @@ returns the \fB\s-1BIGNUM\s0\fR, and \s-1NULL\s0 on error.
The error codes can be obtained by \fIERR_get_error\fR\|(3).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIbn\fR\|(3), \fIERR_get_error\fR\|(3), \fIBN_zero\fR\|(3),
\&\fIERR_get_error\fR\|(3), \fIBN_zero\fR\|(3),
\&\fIASN1_INTEGER_to_BN\fR\|(3),
\&\fIBN_num_bytes\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fIBN_bn2bin()\fR, \fIBN_bin2bn()\fR, \fIBN_print_fp()\fR and \fIBN_print()\fR are available
in all versions of SSLeay and OpenSSL.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved.
.PP
\&\fIBN_bn2hex()\fR, \fIBN_bn2dec()\fR, \fIBN_hex2bn()\fR, \fIBN_dec2bn()\fR, \fIBN_bn2mpi()\fR and
\&\fIBN_mpi2bn()\fR were added in SSLeay 0.9.0.
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

20
secure/lib/libcrypto/man/BN_cmp.3
View file

@ -128,8 +128,8 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BN_cmp 3"
.TH BN_cmp 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "BN_CMP 3"
.TH BN_CMP 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
@ -166,11 +166,11 @@ of \fBa\fR and \fBb\fR.
.PP
\&\fIBN_is_zero()\fR, \fIBN_is_one()\fR \fIBN_is_word()\fR and \fIBN_is_odd()\fR return 1 if
the condition is true, 0 otherwise.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIbn\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fIBN_cmp()\fR, \fIBN_ucmp()\fR, \fIBN_is_zero()\fR, \fIBN_is_one()\fR and \fIBN_is_word()\fR are
available in all versions of SSLeay and OpenSSL.
\&\fIBN_is_odd()\fR was added in SSLeay 0.8.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2017 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

39
secure/lib/libcrypto/man/BN_copy.3
View file

@ -128,14 +128,14 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BN_copy 3"
.TH BN_copy 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "BN_COPY 3"
.TH BN_COPY 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
BN_copy, BN_dup \- copy BIGNUMs
BN_copy, BN_dup, BN_with_flags \- copy BIGNUMs
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
@ -144,11 +144,31 @@ BN_copy, BN_dup \- copy BIGNUMs
\& 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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fIBN_copy()\fR copies \fBfrom\fR to \fBto\fR. \fIBN_dup()\fR creates a new \fB\s-1BIGNUM\s0\fR
containing the value \fBfrom\fR.
.PP
BN_with_flags creates a \fBtemporary\fR shallow copy of \fBb\fR in \fBdest\fR. 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 \fBflags\fR will
be set in \fBdest\fR in addition to any flags already set in \fBb\fR. For example this
might commonly be used to create a temporary copy of a \s-1BIGNUM\s0 with the
\&\fB\s-1BN_FLG_CONSTTIME\s0\fR flag set for constant time operations. The temporary copy in
\&\fBdest\fR will share some internal state with \fBb\fR. For this reason the following
restrictions apply to the use of \fBdest\fR:
.IP "\(bu" 2
\&\fBdest\fR should be a newly allocated \s-1BIGNUM\s0 obtained via a call to \fIBN_new()\fR. It
should not have been used for other purposes or initialised in any way.
.IP "\(bu" 2
\&\fBdest\fR must only be used in \*(L"read-only\*(R" operations, i.e. typically those
functions where the relevant parameter is declared \*(L"const\*(R".
.IP "\(bu" 2
\&\fBdest\fR must be used and freed before any further subsequent use of \fBb\fR
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fIBN_copy()\fR returns \fBto\fR on success, \s-1NULL\s0 on error. \fIBN_dup()\fR returns
@ -156,7 +176,12 @@ the new \fB\s-1BIGNUM\s0\fR, and \s-1NULL\s0 on error. The error codes can be ob
by \fIERR_get_error\fR\|(3).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIbn\fR\|(3), \fIERR_get_error\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fIBN_copy()\fR and \fIBN_dup()\fR are available in all versions of SSLeay and OpenSSL.
\&\fIERR_get_error\fR\|(3)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2017 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

120
secure/lib/libcrypto/man/BN_generate_prime.3
View file

@ -128,64 +128,76 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BN_generate_prime 3"
.TH BN_generate_prime 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "BN_GENERATE_PRIME 3"
.TH BN_GENERATE_PRIME 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
BN_generate_prime_ex, BN_is_prime_ex, BN_is_prime_fasttest_ex, BN_GENCB_call,
BN_GENCB_set_old, BN_GENCB_set, BN_generate_prime, BN_is_prime,
BN_is_prime_fasttest \- generate primes and test for primality
BN_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
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #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_generate_prime_ex(BIGNUM *ret, int bits, int safe, const BIGNUM *add,
\& const BIGNUM *rem, BN_GENCB *cb);
\&
\& int BN_is_prime_ex(const BIGNUM *p,int nchecks, BN_CTX *ctx, BN_GENCB *cb);
\& int BN_is_prime_ex(const BIGNUM *p, int nchecks, BN_CTX *ctx, BN_GENCB *cb);
\&
\& int BN_is_prime_fasttest_ex(const BIGNUM *p,int nchecks, BN_CTX *ctx,
\& int do_trial_division, BN_GENCB *cb);
\& int BN_is_prime_fasttest_ex(const BIGNUM *p, int nchecks, BN_CTX *ctx,
\& int do_trial_division, BN_GENCB *cb);
\&
\& int BN_GENCB_call(BN_GENCB *cb, int a, int b);
\&
\& #define BN_GENCB_set_old(gencb, callback, cb_arg) ...
\& BN_GENCB *BN_GENCB_new(void);
\&
\& #define BN_GENCB_set(gencb, callback, cb_arg) ...
\& void BN_GENCB_free(BN_GENCB *cb);
\&
\& void BN_GENCB_set_old(BN_GENCB *gencb,
\& void (*callback)(int, int, void *), void *cb_arg);
\&
\& void BN_GENCB_set(BN_GENCB *gencb,
\& int (*callback)(int, int, BN_GENCB *), void *cb_arg);
\&
\& void *BN_GENCB_get_arg(BN_GENCB *cb);
.Ve
.PP
Deprecated:
.PP
.Vb 2
.Vb 4
\& #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);
\& 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(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);
\& void (*callback)(int, int, void *), BN_CTX *ctx,
\& void *cb_arg, int do_trial_division);
\& #endif
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fIBN_generate_prime_ex()\fR generates a pseudo-random prime number of
bit length \fBbits\fR.
at least bit length \fBbits\fR.
If \fBret\fR is not \fB\s-1NULL\s0\fR, it will be used to store the number.
.PP
If \fBcb\fR is not \fB\s-1NULL\s0\fR, it is used as follows:
.IP "\(bu" 4
.IP "\(bu" 2
\&\fBBN_GENCB_call(cb, 0, i)\fR is called after generating the i\-th
potential prime number.
.IP "\(bu" 4
.IP "\(bu" 2
While the number is being tested for primality,
\&\fBBN_GENCB_call(cb, 1, j)\fR is called as described below.
.IP "\(bu" 4
.IP "\(bu" 2
When a prime has been found, \fBBN_GENCB_call(cb, 2, i)\fR is called.
.IP "\(bu" 2
The callers of \fIBN_generate_prime_ex()\fR may call \fBBN_GENCB_call(cb, i, j)\fR with
other values as described in their respective man pages; see \*(L"\s-1SEE ALSO\*(R"\s0.
.PP
The prime may have to fulfill additional requirements for use in
Diffie-Hellman key exchange:
@ -231,29 +243,35 @@ after the j\-th iteration (j = 0, 1, ...). \fBctx\fR is a
pre-allocated \fB\s-1BN_CTX\s0\fR (to save the overhead of allocating and
freeing the structure in a loop), or \fB\s-1NULL\s0\fR.
.PP
BN_GENCB_call calls the callback function held in the \fB\s-1BN_GENCB\s0\fR structure
\&\fIBN_GENCB_call()\fR calls the callback function held in the \fB\s-1BN_GENCB\s0\fR structure
and passes the ints \fBa\fR and \fBb\fR as arguments. There are two types of
\&\fB\s-1BN_GENCB\s0\fR structure that are supported: \*(L"new\*(R" style and \*(L"old\*(R" style. New
programs should prefer the \*(L"new\*(R" style, whilst the \*(L"old\*(R" style is provided
for backwards compatibility purposes.
.PP
A \fB\s-1BN_GENCB\s0\fR structure should be created through a call to \fIBN_GENCB_new()\fR,
and freed through a call to \fIBN_GENCB_free()\fR.
.PP
For \*(L"new\*(R" style callbacks a \s-1BN_GENCB\s0 structure should be initialised with a
call to BN_GENCB_set, where \fBgencb\fR is a \fB\s-1BN_GENCB\s0 *\fR, \fBcallback\fR is of
call to \fIBN_GENCB_set()\fR, where \fBgencb\fR is a \fB\s-1BN_GENCB\s0 *\fR, \fBcallback\fR is of
type \fBint (*callback)(int, int, \s-1BN_GENCB\s0 *)\fR and \fBcb_arg\fR is a \fBvoid *\fR.
\&\*(L"Old\*(R" style callbacks are the same except they are initialised with a call
to BN_GENCB_set_old and \fBcallback\fR is of type
to \fIBN_GENCB_set_old()\fR and \fBcallback\fR is of type
\&\fBvoid (*callback)(int, int, void *)\fR.
.PP
A callback is invoked through a call to \fBBN_GENCB_call\fR. This will check
the type of the callback and will invoke \fBcallback(a, b, gencb)\fR for new
style callbacks or \fBcallback(a, b, cb_arg)\fR for old style.
.PP
BN_generate_prime (deprecated) works in the same way as
BN_generate_prime_ex but expects an old style callback function
It is possible to obtain the argument associated with a \s-1BN_GENCB\s0 structure
(set via a call to BN_GENCB_set or BN_GENCB_set_old) using BN_GENCB_get_arg.
.PP
\&\fIBN_generate_prime()\fR (deprecated) works in the same way as
\&\fIBN_generate_prime_ex()\fR but expects an old-style callback function
directly in the \fBcallback\fR parameter, and an argument to pass to it in
the \fBcb_arg\fR. Similarly BN_is_prime and BN_is_prime_fasttest are
deprecated and can be compared to BN_is_prime_ex and
BN_is_prime_fasttest_ex respectively.
the \fBcb_arg\fR. \fIBN_is_prime()\fR and \fIBN_is_prime_fasttest()\fR
can similarly be compared to \fIBN_is_prime_ex()\fR and
\&\fIBN_is_prime_fasttest_ex()\fR, respectively.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fIBN_generate_prime_ex()\fR return 1 on success or 0 on error.
@ -265,15 +283,47 @@ prime with an error probability of less than 0.25^\fBnchecks\fR, and
.PP
\&\fIBN_generate_prime()\fR returns the prime number on success, \fB\s-1NULL\s0\fR otherwise.
.PP
BN_GENCB_new returns a pointer to a \s-1BN_GENCB\s0 structure on success, or \fB\s-1NULL\s0\fR
otherwise.
.PP
BN_GENCB_get_arg returns the argument previously associated with a \s-1BN_GENCB\s0
structure.
.PP
Callback functions should return 1 on success or 0 on error.
.PP
The error codes can be obtained by \fIERR_get_error\fR\|(3).
.SH "REMOVED FUNCTIONALITY"
.IX Header "REMOVED FUNCTIONALITY"
As of OpenSSL 1.1.0 it is no longer possible to create a \s-1BN_GENCB\s0 structure
directly, as in:
.PP
.Vb 1
\& BN_GENCB callback;
.Ve
.PP
Instead applications should create a \s-1BN_GENCB\s0 structure using BN_GENCB_new:
.PP
.Vb 6
\& BN_GENCB *callback;
\& callback = BN_GENCB_new();
\& if (!callback)
\& /* error */
\& ...
\& BN_GENCB_free(callback);
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIbn\fR\|(3), \fIERR_get_error\fR\|(3), \fIrand\fR\|(3)
\&\fIDH_generate_parameters\fR\|(3), \fIDSA_generate_parameters\fR\|(3),
\&\fIRSA_generate_key\fR\|(3), \fIERR_get_error\fR\|(3), \fIRAND_bytes\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
The \fBcb_arg\fR arguments to \fIBN_generate_prime()\fR and to \fIBN_is_prime()\fR
were added in SSLeay 0.9.0. The \fBret\fR argument to \fIBN_generate_prime()\fR
was added in SSLeay 0.9.1.
\&\fIBN_is_prime_fasttest()\fR was added in OpenSSL 0.9.5.
\&\fIBN_GENCB_new()\fR, \fIBN_GENCB_free()\fR,
and \fIBN_GENCB_get_arg()\fR were added in OpenSSL 1.1.0
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

19
secure/lib/libcrypto/man/BN_mod_inverse.3
View file

@ -128,8 +128,8 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BN_mod_inverse 3"
.TH BN_mod_inverse 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "BN_MOD_INVERSE 3"
.TH BN_MOD_INVERSE 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
@ -142,7 +142,7 @@ BN_mod_inverse \- compute inverse modulo n
\& #include <openssl/bn.h>
\&
\& BIGNUM *BN_mod_inverse(BIGNUM *r, BIGNUM *a, const BIGNUM *n,
\& BN_CTX *ctx);
\& BN_CTX *ctx);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
@ -158,7 +158,12 @@ variables. \fBr\fR may be the same \fB\s-1BIGNUM\s0\fR as \fBa\fR or \fBn\fR.
\&\s-1NULL\s0 on error. The error codes can be obtained by \fIERR_get_error\fR\|(3).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIbn\fR\|(3), \fIERR_get_error\fR\|(3), \fIBN_add\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fIBN_mod_inverse()\fR is available in all versions of SSLeay and OpenSSL.
\&\fIERR_get_error\fR\|(3), \fIBN_add\fR\|(3)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2017 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

50
secure/lib/libcrypto/man/BN_mod_mul_montgomery.3
View file

@ -128,36 +128,33 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BN_mod_mul_montgomery 3"
.TH BN_mod_mul_montgomery 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "BN_MOD_MUL_MONTGOMERY 3"
.TH BN_MOD_MUL_MONTGOMERY 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
BN_mod_mul_montgomery, BN_MONT_CTX_new, BN_MONT_CTX_init,
BN_MONT_CTX_free, BN_MONT_CTX_set, BN_MONT_CTX_copy,
BN_from_montgomery, BN_to_montgomery \- Montgomery multiplication
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
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bn.h>
\&
\& BN_MONT_CTX *BN_MONT_CTX_new(void);
\& void BN_MONT_CTX_init(BN_MONT_CTX *ctx);
\& void BN_MONT_CTX_free(BN_MONT_CTX *mont);
\&
\& int BN_MONT_CTX_set(BN_MONT_CTX *mont, const BIGNUM *m, BN_CTX *ctx);
\& BN_MONT_CTX *BN_MONT_CTX_copy(BN_MONT_CTX *to, BN_MONT_CTX *from);
\&
\& int BN_mod_mul_montgomery(BIGNUM *r, BIGNUM *a, BIGNUM *b,
\& BN_MONT_CTX *mont, BN_CTX *ctx);
\& BN_MONT_CTX *mont, BN_CTX *ctx);
\&
\& int BN_from_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont,
\& BN_CTX *ctx);
\& BN_CTX *ctx);
\&
\& int BN_to_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont,
\& BN_CTX *ctx);
\& BN_CTX *ctx);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
@ -167,7 +164,6 @@ but they may be useful when several operations are to be performed
using the same modulus.
.PP
\&\fIBN_MONT_CTX_new()\fR allocates and initializes a \fB\s-1BN_MONT_CTX\s0\fR structure.
\&\fIBN_MONT_CTX_init()\fR initializes an existing uninitialized \fB\s-1BN_MONT_CTX\s0\fR.
.PP
\&\fIBN_MONT_CTX_set()\fR sets up the \fImont\fR structure from the modulus \fIm\fR
by precomputing its inverse and a value R.
@ -176,6 +172,7 @@ by precomputing its inverse and a value R.
.PP
\&\fIBN_MONT_CTX_free()\fR frees the components of the \fB\s-1BN_MONT_CTX\s0\fR, and, if
it was created by \fIBN_MONT_CTX_new()\fR, also the structure itself.
If \fBmont\fR is \s-1NULL,\s0 nothing is done.
.PP
\&\fIBN_mod_mul_montgomery()\fR computes Mont(\fIa\fR,\fIb\fR):=\fIa\fR*\fIb\fR*R^\-1 and places
the result in \fIr\fR.
@ -187,29 +184,12 @@ Note that \fIa\fR must be non-negative and smaller than the modulus.
.PP
For all functions, \fIctx\fR is a previously allocated \fB\s-1BN_CTX\s0\fR used for
temporary variables.
.PP
The \fB\s-1BN_MONT_CTX\s0\fR structure is defined as follows:
.PP
.Vb 10
\& typedef struct bn_mont_ctx_st
\& {
\& int ri; /* number of bits in R */
\& BIGNUM RR; /* R^2 (used to convert to Montgomery form) */
\& BIGNUM N; /* The modulus */
\& BIGNUM Ni; /* R*(1/R mod N) \- N*Ni = 1
\& * (Ni is only stored for bignum algorithm) */
\& BN_ULONG n0; /* least significant word of Ni */
\& int flags;
\& } BN_MONT_CTX;
.Ve
.PP
\&\fIBN_to_montgomery()\fR is a macro.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fIBN_MONT_CTX_new()\fR returns the newly allocated \fB\s-1BN_MONT_CTX\s0\fR, and \s-1NULL\s0
on error.
.PP
\&\fIBN_MONT_CTX_init()\fR and \fIBN_MONT_CTX_free()\fR have no return values.
\&\fIBN_MONT_CTX_free()\fR has no return value.
.PP
For the other functions, 1 is returned for success, 0 on error.
The error codes can be obtained by \fIERR_get_error\fR\|(3).
@ -219,12 +199,16 @@ The inputs must be reduced modulo \fBm\fR, otherwise the result will be
outside the expected range.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIbn\fR\|(3), \fIERR_get_error\fR\|(3), \fIBN_add\fR\|(3),
\&\fIERR_get_error\fR\|(3), \fIBN_add\fR\|(3),
\&\fIBN_CTX_new\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fIBN_MONT_CTX_new()\fR, \fIBN_MONT_CTX_free()\fR, \fIBN_MONT_CTX_set()\fR,
\&\fIBN_mod_mul_montgomery()\fR, \fIBN_from_montgomery()\fR and \fIBN_to_montgomery()\fR
are available in all versions of SSLeay and OpenSSL.
\&\fIBN_MONT_CTX_init()\fR was removed in OpenSSL 1.1.0
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2017 The OpenSSL Project Authors. All Rights Reserved.
.PP
\&\fIBN_MONT_CTX_init()\fR and \fIBN_MONT_CTX_copy()\fR were added in SSLeay 0.9.1b.
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

46
secure/lib/libcrypto/man/BN_mod_mul_reciprocal.3
View file

@ -128,32 +128,29 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BN_mod_mul_reciprocal 3"
.TH BN_mod_mul_reciprocal 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "BN_MOD_MUL_RECIPROCAL 3"
.TH BN_MOD_MUL_RECIPROCAL 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
BN_mod_mul_reciprocal, BN_div_recp, BN_RECP_CTX_new, BN_RECP_CTX_init,
BN_RECP_CTX_free, BN_RECP_CTX_set \- modular multiplication using
reciprocal
BN_mod_mul_reciprocal, BN_div_recp, BN_RECP_CTX_new, BN_RECP_CTX_free, BN_RECP_CTX_set \- modular multiplication using reciprocal
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bn.h>
\&
\& BN_RECP_CTX *BN_RECP_CTX_new(void);
\& void BN_RECP_CTX_init(BN_RECP_CTX *recp);
\& void BN_RECP_CTX_free(BN_RECP_CTX *recp);
\&
\& int BN_RECP_CTX_set(BN_RECP_CTX *recp, const BIGNUM *m, BN_CTX *ctx);
\&
\& int BN_div_recp(BIGNUM *dv, BIGNUM *rem, BIGNUM *a, BN_RECP_CTX *recp,
\& BN_CTX *ctx);
\& BN_CTX *ctx);
\&
\& int BN_mod_mul_reciprocal(BIGNUM *r, BIGNUM *a, BIGNUM *b,
\& BN_RECP_CTX *recp, BN_CTX *ctx);
\& BN_RECP_CTX *recp, BN_CTX *ctx);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
@ -164,10 +161,10 @@ using \fBrecp\fR=1/\fBm\fR, which is set as described below. \fBctx\fR is a
previously allocated \fB\s-1BN_CTX\s0\fR used for temporary variables.
.PP
\&\fIBN_RECP_CTX_new()\fR allocates and initializes a \fB\s-1BN_RECP\s0\fR structure.
\&\fIBN_RECP_CTX_init()\fR initializes an existing uninitialized \fB\s-1BN_RECP\s0\fR.
.PP
\&\fIBN_RECP_CTX_free()\fR frees the components of the \fB\s-1BN_RECP\s0\fR, and, if it
was created by \fIBN_RECP_CTX_new()\fR, also the structure itself.
If \fBrecp\fR is \s-1NULL,\s0 nothing is done.
.PP
\&\fIBN_RECP_CTX_set()\fR stores \fBm\fR in \fBrecp\fR and sets it up for computing
1/\fBm\fR and shifting it left by BN_num_bits(\fBm\fR)+1 to make it an
@ -177,35 +174,28 @@ later be stored in \fBrecp\fR.
\&\fIBN_div_recp()\fR divides \fBa\fR by \fBm\fR using \fBrecp\fR. It places the quotient
in \fBdv\fR and the remainder in \fBrem\fR.
.PP
The \fB\s-1BN_RECP_CTX\s0\fR structure is defined as follows:
.PP
.Vb 8
\& typedef struct bn_recp_ctx_st
\& {
\& BIGNUM N; /* the divisor */
\& BIGNUM Nr; /* the reciprocal */
\& int num_bits;
\& int shift;
\& int flags;
\& } BN_RECP_CTX;
.Ve
.PP
It cannot be shared between threads.
The \fB\s-1BN_RECP_CTX\s0\fR structure cannot be shared between threads.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fIBN_RECP_CTX_new()\fR returns the newly allocated \fB\s-1BN_RECP_CTX\s0\fR, and \s-1NULL\s0
on error.
.PP
\&\fIBN_RECP_CTX_init()\fR and \fIBN_RECP_CTX_free()\fR have no return values.
\&\fIBN_RECP_CTX_free()\fR has no return value.
.PP
For the other functions, 1 is returned for success, 0 on error.
The error codes can be obtained by \fIERR_get_error\fR\|(3).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIbn\fR\|(3), \fIERR_get_error\fR\|(3), \fIBN_add\fR\|(3),
\&\fIERR_get_error\fR\|(3), \fIBN_add\fR\|(3),
\&\fIBN_CTX_new\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fB\s-1BN_RECP_CTX\s0\fR was added in SSLeay 0.9.0. Before that, the function
\&\fIBN_reciprocal()\fR was used instead, and the \fIBN_mod_mul_reciprocal()\fR
arguments were different.
\&\fIBN_RECP_CTX_init()\fR was removed in OpenSSL 1.1.0
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2017 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

35
secure/lib/libcrypto/man/BN_new.3
View file

@ -128,14 +128,14 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BN_new 3"
.TH BN_new 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "BN_NEW 3"
.TH BN_NEW 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
BN_new, BN_init, BN_clear, BN_free, BN_clear_free \- allocate and free BIGNUMs
BN_new, BN_secure_new, BN_clear, BN_free, BN_clear_free \- allocate and free BIGNUMs
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
@ -143,7 +143,7 @@ BN_new, BN_init, BN_clear, BN_free, BN_clear_free \- allocate and free BIGNUMs
\&
\& BIGNUM *BN_new(void);
\&
\& void BN_init(BIGNUM *);
\& BIGNUM *BN_secure_new(void);
\&
\& void BN_clear(BIGNUM *a);
\&
@ -153,8 +153,9 @@ BN_new, BN_init, BN_clear, BN_free, BN_clear_free \- allocate and free BIGNUMs
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fIBN_new()\fR allocates and initializes a \fB\s-1BIGNUM\s0\fR structure. \fIBN_init()\fR
initializes an existing uninitialized \fB\s-1BIGNUM\s0\fR.
\&\fIBN_new()\fR allocates and initializes a \fB\s-1BIGNUM\s0\fR structure.
\&\fIBN_secure_new()\fR does the same except that the secure heap
\&\fIOPENSSL_secure_malloc\fR\|(3) is used to store the value.
.PP
\&\fIBN_clear()\fR is used to destroy sensitive data such as keys when they
are no longer needed. It erases the memory used by \fBa\fR and sets it
@ -166,18 +167,24 @@ overwrites the data before the memory is returned to the system.
If \fBa\fR is \s-1NULL,\s0 nothing is done.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fIBN_new()\fR returns a pointer to the \fB\s-1BIGNUM\s0\fR initialised to the value 0.
\&\fIBN_new()\fR and \fIBN_secure_new()\fR
return a pointer to the \fB\s-1BIGNUM\s0\fR initialised to the value 0.
If the allocation fails,
it returns \fB\s-1NULL\s0\fR and sets an error code that can be obtained
they return \fB\s-1NULL\s0\fR and set an error code that can be obtained
by \fIERR_get_error\fR\|(3).
.PP
\&\fIBN_init()\fR, \fIBN_clear()\fR, \fIBN_free()\fR and \fIBN_clear_free()\fR have no return
values.
\&\fIBN_clear()\fR, \fIBN_free()\fR and \fIBN_clear_free()\fR have no return values.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIbn\fR\|(3), \fIERR_get_error\fR\|(3)
\&\fIERR_get_error\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fIBN_new()\fR, \fIBN_clear()\fR, \fIBN_free()\fR and \fIBN_clear_free()\fR are available in
all versions on SSLeay and OpenSSL. \fIBN_init()\fR was added in SSLeay
0.9.1b.
\&\fIBN_init()\fR was removed in OpenSSL 1.1.0; use \fIBN_new()\fR instead.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2017 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

18
secure/lib/libcrypto/man/BN_num_bytes.3
View file

@ -128,8 +128,8 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BN_num_bytes 3"
.TH BN_num_bytes 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "BN_NUM_BYTES 3"
.TH BN_NUM_BYTES 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
@ -176,9 +176,13 @@ there's no real guarantee that will match the \*(L"key size\*(R", just a lot
more probability).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIbn\fR\|(3), \fIDH_size\fR\|(3), \fIDSA_size\fR\|(3),
\&\fIDH_size\fR\|(3), \fIDSA_size\fR\|(3),
\&\fIRSA_size\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fIBN_num_bytes()\fR, \fIBN_num_bits()\fR and \fIBN_num_bits_word()\fR are available in
all versions of SSLeay and OpenSSL.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2017 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

76
secure/lib/libcrypto/man/BN_rand.3
View file

@ -128,14 +128,14 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BN_rand 3"
.TH BN_rand 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "BN_RAND 3"
.TH BN_RAND 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
BN_rand, BN_pseudo_rand, BN_rand_range, BN_pseudo_rand_range \- generate pseudo\-random number
BN_rand, BN_priv_rand, BN_pseudo_rand, BN_rand_range, BN_priv_rand_range, BN_pseudo_rand_range \&\- generate pseudo\-random number
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
@ -143,10 +143,14 @@ BN_rand, BN_pseudo_rand, BN_rand_range, BN_pseudo_rand_range \- generate pseudo\
\&
\& 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);
.Ve
.SH "DESCRIPTION"
@ -154,38 +158,58 @@ BN_rand, BN_pseudo_rand, BN_rand_range, BN_pseudo_rand_range \- generate pseudo\
\&\fIBN_rand()\fR generates a cryptographically strong pseudo-random number of
\&\fBbits\fR in length and stores it in \fBrnd\fR.
If \fBbits\fR is less than zero, or too small to
accomodate the requirements specified by the \fBtop\fR and \fBbottom\fR
accommodate the requirements specified by the \fBtop\fR and \fBbottom\fR
parameters, an error is returned.
If \fBtop\fR is \-1, the
most significant bit of the random number can be zero. If \fBtop\fR is 0,
it is set to 1, and if \fBtop\fR is 1, the two most significant bits of
The \fBtop\fR parameters specifies
requirements on the most significant bit of the generated number.
If it is \fB\s-1BN_RAND_TOP_ANY\s0\fR, there is no constraint.
If it is \fB\s-1BN_RAND_TOP_ONE\s0\fR, the top bit must be one.
If it is \fB\s-1BN_RAND_TOP_TWO\s0\fR, 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*\fBbits\fR length. If \fBbottom\fR is true, the
number will be odd. The value of \fBbits\fR must be zero or greater. If \fBbits\fR is
1 then \fBtop\fR cannot also be 1.
.PP
\&\fIBN_pseudo_rand()\fR does the same, but pseudo-random numbers generated by
this function are not necessarily unpredictable. They can be used for
non-cryptographic purposes and for certain purposes in cryptographic
protocols, but usually not for key generation etc.
numbers will always have 2*\fBbits\fR length.
If \fBbottom\fR is \fB\s-1BN_RAND_BOTTOM_ODD\s0\fR, the number will be odd; if it
is \fB\s-1BN_RAND_BOTTOM_ANY\s0\fR it can be odd or even.
If \fBbits\fR is 1 then \fBtop\fR cannot also be \fB\s-1BN_RAND_FLG_TOPTWO\s0\fR.
.PP
\&\fIBN_rand_range()\fR generates a cryptographically strong pseudo-random
number \fBrnd\fR in the range 0 <= \fBrnd\fR < \fBrange\fR.
\&\fIBN_pseudo_rand_range()\fR does the same, but is based on \fIBN_pseudo_rand()\fR,
and hence numbers generated by it are not necessarily unpredictable.
.PP
The \s-1PRNG\s0 must be seeded prior to calling \fIBN_rand()\fR or \fIBN_rand_range()\fR.
\&\fIBN_priv_rand()\fR and \fIBN_priv_rand_range()\fR have the same semantics as
\&\fIBN_rand()\fR and \fIBN_rand_range()\fR respectively. They are intended to be
used for generating values that should remain private, and mirror the
same difference between \fIRAND_bytes\fR\|(3) and \fIRAND_priv_bytes\fR\|(3).
.SH "NOTES"
.IX Header "NOTES"
Always check the error return value of these functions and do not take
randomness for granted: an error occurs if the \s-1CSPRNG\s0 has not been
seeded with enough randomness to ensure an unpredictable byte sequence.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
The functions return 1 on success, 0 on error.
The error codes can be obtained by \fIERR_get_error\fR\|(3).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIbn\fR\|(3), \fIERR_get_error\fR\|(3), \fIrand\fR\|(3),
\&\fIRAND_add\fR\|(3), \fIRAND_bytes\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fIBN_rand()\fR is available in all versions of SSLeay and OpenSSL.
\&\fIBN_pseudo_rand()\fR was added in OpenSSL 0.9.5. The \fBtop\fR == \-1 case
and the function \fIBN_rand_range()\fR were added in OpenSSL 0.9.6a.
\&\fIBN_pseudo_rand_range()\fR was added in OpenSSL 0.9.6c.
.IP "\(bu" 2
Starting with OpenSSL release 1.1.0, \fIBN_pseudo_rand()\fR has been identical
to \fIBN_rand()\fR and \fIBN_pseudo_rand_range()\fR has been identical to
\&\fIBN_rand_range()\fR.
The \*(L"pseudo\*(R" functions should not be used and may be deprecated in
a future release.
.IP "\(bu" 2
\&\fIBN_priv_rand()\fR and \fIBN_priv_rand_range()\fR were added in OpenSSL 1.1.1.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIERR_get_error\fR\|(3),
\&\fIRAND_add\fR\|(3),
\&\fIRAND_bytes\fR\|(3),
\&\fIRAND_priv_bytes\fR\|(3),
\&\s-1\fIRAND\s0\fR\|(7),
\&\s-1\fIRAND_DRBG\s0\fR\|(7)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

54
secure/lib/libcrypto/man/X509_STORE_CTX_get_ex_new_index.3 → secure/lib/libcrypto/man/BN_security_bits.3
View file

@ -128,42 +128,50 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "X509_STORE_CTX_get_ex_new_index 3"
.TH X509_STORE_CTX_get_ex_new_index 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "BN_SECURITY_BITS 3"
.TH BN_SECURITY_BITS 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
X509_STORE_CTX_get_ex_new_index, X509_STORE_CTX_set_ex_data, X509_STORE_CTX_get_ex_data \- add application specific data to X509_STORE_CTX structures
BN_security_bits \- returns bits of security based on given numbers
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/x509_vfy.h>
\& #include <openssl/bn.h>
\&
\& int X509_STORE_CTX_get_ex_new_index(long argl, void *argp,
\& CRYPTO_EX_new *new_func,
\& CRYPTO_EX_dup *dup_func,
\& CRYPTO_EX_free *free_func);
\&
\& int X509_STORE_CTX_set_ex_data(X509_STORE_CTX *d, int idx, void *arg);
\&
\& void *X509_STORE_CTX_get_ex_data(X509_STORE_CTX *d, int idx);
\& int BN_security_bits(int L, int N);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
These functions handle application specific data in X509_STORE_CTX structures.
Their usage is identical to that of \fIRSA_get_ex_new_index()\fR, \fIRSA_set_ex_data()\fR
and \fIRSA_get_ex_data()\fR as described in \fIRSA_get_ex_new_index\fR\|(3).
\&\fIBN_security_bits()\fR returns the number of bits of security provided by a
specific algorithm and a particular key size. The bits of security is
defined in \s-1NIST SP800\-57.\s0 Currently, \fIBN_security_bits()\fR support two types
of asymmetric algorithms: the \s-1FFC\s0 (Finite Field Cryptography) and \s-1IFC\s0
(Integer Factorization Cryptography). For \s-1FFC,\s0 e.g., \s-1DSA\s0 and \s-1DH,\s0 both
parameters \fBL\fR and \fBN\fR are used to decide the bits of security, where
\&\fBL\fR is the size of the public key and \fBN\fR is the size of the private
key. For \s-1IFC,\s0 e.g., \s-1RSA,\s0 only \fBL\fR is used and it's commonly considered
to be the key size (modulus).
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
Number of security bits.
.SH "NOTES"
.IX Header "NOTES"
This mechanism is used internally by the \fBssl\fR library to store the \fB\s-1SSL\s0\fR
structure associated with a verification operation in an \fBX509_STORE_CTX\fR
structure.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIRSA_get_ex_new_index\fR\|(3)
\&\s-1ECC\s0 (Elliptic Curve Cryptography) is not covered by the \fIBN_security_bits()\fR
function. The symmetric algorithms are not covered neither.
.SH "HISTORY"
.IX Header "HISTORY"
\&\fIX509_STORE_CTX_get_ex_new_index()\fR, \fIX509_STORE_CTX_set_ex_data()\fR and
\&\fIX509_STORE_CTX_get_ex_data()\fR are available since OpenSSL 0.9.5.
\&\fIBN_security_bits()\fR was added in OpenSSL 1.1.0.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIDH_security_bits\fR\|(3), \fIDSA_security_bits\fR\|(3), \fIRSA_security_bits\fR\|(3)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

22
secure/lib/libcrypto/man/BN_set_bit.3
View file

@ -128,15 +128,14 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BN_set_bit 3"
.TH BN_set_bit 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "BN_SET_BIT 3"
.TH BN_SET_BIT 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "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
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
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
@ -186,9 +185,12 @@ All other functions return 1 for success, 0 on error. The error codes
can be obtained by \fIERR_get_error\fR\|(3).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIbn\fR\|(3), \fIBN_num_bytes\fR\|(3), \fIBN_add\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fIBN_set_bit()\fR, \fIBN_clear_bit()\fR, \fIBN_is_bit_set()\fR, \fIBN_mask_bits()\fR,
\&\fIBN_lshift()\fR, \fIBN_lshift1()\fR, \fIBN_rshift()\fR, and \fIBN_rshift1()\fR are available
in all versions of SSLeay and OpenSSL.
\&\fIBN_num_bytes\fR\|(3), \fIBN_add\fR\|(3)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2017 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

18
secure/lib/libcrypto/man/BN_swap.3
View file

@ -128,8 +128,8 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BN_swap 3"
.TH BN_swap 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "BN_SWAP 3"
.TH BN_SWAP 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
@ -146,8 +146,14 @@ BN_swap \- exchange BIGNUMs
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fIBN_swap()\fR exchanges the values of \fIa\fR and \fIb\fR.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fIBN_swap()\fR does not return a value.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved.
.PP
\&\fIbn\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
BN_swap was added in OpenSSL 0.9.7.
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

34
secure/lib/libcrypto/man/BN_zero.3
View file

@ -128,31 +128,30 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BN_zero 3"
.TH BN_zero 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "BN_ZERO 3"
.TH BN_ZERO 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
BN_zero, BN_one, BN_value_one, BN_set_word, BN_get_word \- BIGNUM assignment
operations
BN_zero, BN_one, BN_value_one, BN_set_word, BN_get_word \- BIGNUM assignment operations
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bn.h>
\&
\& int BN_zero(BIGNUM *a);
\& void BN_zero(BIGNUM *a);
\& int BN_one(BIGNUM *a);
\&
\& const BIGNUM *BN_value_one(void);
\&
\& int BN_set_word(BIGNUM *a, BN_ULONG w);
\& BN_ULONG BN_get_word(BIGNUM *a);
\& unsigned BN_ULONG BN_get_word(BIGNUM *a);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fB\s-1BN_ULONG\s0\fR is a macro that will be an unsigned integral type optimied
\&\fB\s-1BN_ULONG\s0\fR is a macro that will be an unsigned integral type optimized
for the most efficient implementation on the local platform.
.PP
\&\fIBN_zero()\fR, \fIBN_one()\fR and \fIBN_set_word()\fR set \fBa\fR to the values 0, 1 and
@ -165,10 +164,11 @@ is useful for use in comparisons and assignment.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fIBN_get_word()\fR returns the value \fBa\fR, or all-bits-set if \fBa\fR cannot
be represented as a \fB\s-1BN_ULONG\s0\fR.
be represented as a single integer.
.PP
\&\fIBN_zero()\fR, \fIBN_one()\fR and \fIBN_set_word()\fR return 1 on success, 0 otherwise.
\&\fIBN_one()\fR and \fIBN_set_word()\fR return 1 on success, 0 otherwise.
\&\fIBN_value_one()\fR returns the constant.
\&\fIBN_zero()\fR never fails and returns no value.
.SH "BUGS"
.IX Header "BUGS"
If a \fB\s-1BIGNUM\s0\fR is equal to the value of all-bits-set, it will collide
@ -178,12 +178,16 @@ as an error value.
\&\fB\s-1BN_ULONG\s0\fR should probably be a typedef.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIbn\fR\|(3), \fIBN_bn2bin\fR\|(3)
\&\fIBN_bn2bin\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fIBN_zero()\fR, \fIBN_one()\fR and \fIBN_set_word()\fR are available in all versions of
SSLeay and OpenSSL. \fIBN_value_one()\fR and \fIBN_get_word()\fR were added in
SSLeay 0.8.
In OpenSSL 0.9.8, \fIBN_zero()\fR was changed to not return a value; previous
versions returned an int.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved.
.PP
\&\fIBN_value_one()\fR was changed to return a true const \s-1BIGNUM\s0 * in OpenSSL
0.9.7.
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

62
secure/lib/libcrypto/man/buffer.3 → secure/lib/libcrypto/man/BUF_MEM_new.3
View file

@ -128,18 +128,14 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "buffer 3"
.TH buffer 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "BUF_MEM_NEW 3"
.TH BUF_MEM_NEW 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
BUF_MEM_new, BUF_MEM_new_ex, BUF_MEM_free, BUF_MEM_grow \- simple
character array structure
.PP
BUF_strdup, BUF_strndup, BUF_memdup, BUF_strlcpy, BUF_strlcat \-
standard C library equivalents
BUF_MEM_new, BUF_MEM_new_ex, BUF_MEM_free, BUF_MEM_grow, BUF_MEM_grow_clean, BUF_reverse \&\- simple character array structure
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
@ -147,21 +143,14 @@ standard C library equivalents
\&
\& BUF_MEM *BUF_MEM_new(void);
\&
\& void BUF_MEM_free(BUF_MEM *a);
\& BUF_MEM *BUF_MEM_new_ex(unsigned long flags);
\&
\& int BUF_MEM_grow(BUF_MEM *str, int len);
\& void BUF_MEM_free(BUF_MEM *a);
\&
\& char *BUF_strdup(const char *str);
\& int BUF_MEM_grow(BUF_MEM *str, int len);
\& size_t BUF_MEM_grow_clean(BUF_MEM *str, size_t len);
\&
\& char *BUF_strndup(const char *str, size_t siz);
\&
\& void *BUF_memdup(const void *data, size_t siz);
\&
\& size_t BUF_strlcpy(char *dst, const char *src, size_t size);
\&
\& size_t BUF_strlcat(char *dst, const char *src, size_t size);
\&
\& size_t BUF_strnlen(const char *str, size_t maxlen);
\& void BUF_reverse(unsigned char *out, const unsigned char *in, size_t size);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
@ -170,6 +159,10 @@ various purposes in the library, most notably memory BIOs.
.PP
\&\fIBUF_MEM_new()\fR allocates a new buffer of zero size.
.PP
\&\fIBUF_MEM_new_ex()\fR allocates a buffer with the specified flags.
The flag \fB\s-1BUF_MEM_FLAG_SECURE\s0\fR specifies that the \fBdata\fR pointer
should be allocated on the secure heap; see \fICRYPTO_secure_malloc\fR\|(3).
.PP
\&\fIBUF_MEM_free()\fR frees up an already existing buffer. The data is zeroed
before freeing up in case the buffer contains sensitive data.
.PP
@ -177,28 +170,31 @@ before freeing up in case the buffer contains sensitive data.
\&\fBlen\fR. Any data already in the buffer is preserved if it increases in
size.
.PP
\&\fIBUF_strdup()\fR, \fIBUF_strndup()\fR, \fIBUF_memdup()\fR, \fIBUF_strlcpy()\fR,
\&\fIBUF_strlcat()\fR and BUF_strnlen are equivalents of the standard C
library functions. The \fIdup()\fR functions use \fIOPENSSL_malloc()\fR underneath
and so should be used in preference to the standard library for memory
leak checking or replacing the \fImalloc()\fR function.
\&\fIBUF_MEM_grow_clean()\fR is similar to \fIBUF_MEM_grow()\fR but it sets any free'd
or additionally-allocated memory to zero.
.PP
Memory allocated from these functions should be freed up using the
\&\fIOPENSSL_free()\fR function.
.PP
BUF_strndup makes the explicit guarantee that it will never read past
the first \fBsiz\fR bytes of \fBstr\fR.
\&\fIBUF_reverse()\fR reverses \fBsize\fR bytes at \fBin\fR into \fBout\fR. If \fBin\fR
is \s-1NULL,\s0 the array is reversed in-place.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fIBUF_MEM_new()\fR returns the buffer or \s-1NULL\s0 on error.
.PP
\&\fIBUF_MEM_free()\fR has no return value.
.PP
\&\fIBUF_MEM_grow()\fR returns zero on error or the new size (i.e. \fBlen\fR).
\&\fIBUF_MEM_grow()\fR and \fIBUF_MEM_grow_clean()\fR return
zero on error or the new size (i.e., \fBlen\fR).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIbio\fR\|(3)
\&\fIbio\fR\|(7),
\&\fICRYPTO_secure_malloc\fR\|(3).
.SH "HISTORY"
.IX Header "HISTORY"
\&\fIBUF_MEM_new()\fR, \fIBUF_MEM_free()\fR and \fIBUF_MEM_grow()\fR are available in all
versions of SSLeay and OpenSSL. \fIBUF_strdup()\fR was added in SSLeay 0.8.
\&\fIBUF_MEM_new_ex()\fR was added in OpenSSL 1.1.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

18
secure/lib/libcrypto/man/CMS_add0_cert.3
View file

@ -128,14 +128,14 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CMS_add0_cert 3"
.TH CMS_add0_cert 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "CMS_ADD0_CERT 3"
.TH CMS_ADD0_CERT 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
CMS_add0_cert, CMS_add1_cert, CMS_get1_certs, CMS_add0_crl, CMS_add1_crl, CMS_get1_crls, \- CMS certificate and CRL utility functions
CMS_add0_cert, CMS_add1_cert, CMS_get1_certs, CMS_add0_crl, CMS_add1_crl, CMS_get1_crls \&\- CMS certificate and CRL utility functions
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
@ -186,7 +186,11 @@ in practice is if the \fBcms\fR type is invalid.
\&\fIERR_get_error\fR\|(3),
\&\fICMS_sign\fR\|(3),
\&\fICMS_encrypt\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fICMS_add0_cert()\fR, \fICMS_add1_cert()\fR, \fICMS_get1_certs()\fR, \fICMS_add0_crl()\fR
and \fICMS_get1_crls()\fR were all first added to OpenSSL 0.9.8
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2008\-2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

30
secure/lib/libcrypto/man/CMS_add1_recipient_cert.3
View file

@ -128,24 +128,28 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CMS_add1_recipient_cert 3"
.TH CMS_add1_recipient_cert 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "CMS_ADD1_RECIPIENT_CERT 3"
.TH CMS_ADD1_RECIPIENT_CERT 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
.Vb 1
\& CMS_add1_recipient_cert, CMS_add0_recipient_key \- add recipients to a CMS enveloped data structure
.Ve
CMS_add1_recipient_cert, CMS_add0_recipient_key \- add recipients to a CMS enveloped data structure
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/cms.h>
\&
\& CMS_RecipientInfo *CMS_add1_recipient_cert(CMS_ContentInfo *cms, X509 *recip, unsigned int flags);
\& 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);
\& 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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
@ -185,7 +189,11 @@ occurs.
.IX Header "SEE ALSO"
\&\fIERR_get_error\fR\|(3), \fICMS_decrypt\fR\|(3),
\&\fICMS_final\fR\|(3),
.SH "HISTORY"
.IX Header "HISTORY"
\&\fICMS_add1_recipient_cert()\fR and \fICMS_add0_recipient_key()\fR were added to OpenSSL
0.9.8
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2008\-2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

27
secure/lib/libcrypto/man/CMS_add1_signer.3
View file

@ -128,22 +128,22 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CMS_add1_signer 3"
.TH CMS_add1_signer 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "CMS_ADD1_SIGNER 3"
.TH CMS_ADD1_SIGNER 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
.Vb 1
\& CMS_add1_signer, CMS_SignerInfo_sign \- add a signer to a CMS_ContentInfo signed data structure.
.Ve
CMS_add1_signer, CMS_SignerInfo_sign \- add a signer to a CMS_ContentInfo signed data structure
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/cms.h>
\&
\& CMS_SignerInfo *CMS_add1_signer(CMS_ContentInfo *cms, X509 *signcert, EVP_PKEY *pkey, const EVP_MD *md, unsigned int flags);
\& 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);
.Ve
@ -185,7 +185,7 @@ structure. An error occurs if a matching digest value cannot be found to copy.
The returned CMS_ContentInfo structure will be valid and finalized when this
flag is set.
.PP
If \fB\s-1CMS_PARTIAL\s0\fR is set in addition to \fB\s-1CMS_REUSE_DIGEST\s0\fR then the
If \fB\s-1CMS_PARTIAL\s0\fR is set in addition to \fB\s-1CMS_REUSE_DIGEST\s0\fR then the
CMS_SignerInfo structure will not be finalized so additional attributes
can be added. In this case an explicit call to \fICMS_SignerInfo_sign()\fR is
needed to finalize it.
@ -214,7 +214,7 @@ If any of these algorithms is not available then it will not be included: for ex
not loaded.
.PP
\&\fICMS_add1_signer()\fR returns an internal pointer to the CMS_SignerInfo
structure just added, this can be used to set additional attributes
structure just added, this can be used to set additional attributes
before it is finalized.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
@ -224,6 +224,11 @@ structure just added or \s-1NULL\s0 if an error occurs.
.IX Header "SEE ALSO"
\&\fIERR_get_error\fR\|(3), \fICMS_sign\fR\|(3),
\&\fICMS_final\fR\|(3),
.SH "HISTORY"
.IX Header "HISTORY"
\&\fICMS_add1_signer()\fR was added to OpenSSL 0.9.8
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2014\-2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

15
secure/lib/libcrypto/man/CMS_compress.3
View file

@ -128,8 +128,8 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CMS_compress 3"
.TH CMS_compress 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "CMS_COMPRESS 3"
.TH CMS_COMPRESS 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
@ -195,5 +195,12 @@ occurred. The error can be obtained from \fIERR_get_error\fR\|(3).
\&\fIERR_get_error\fR\|(3), \fICMS_uncompress\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fICMS_compress()\fR was added to OpenSSL 0.9.8
The \fB\s-1CMS_STREAM\s0\fR flag was first supported in OpenSSL 1.0.0.
The \fB\s-1CMS_STREAM\s0\fR flag was added in OpenSSL 1.0.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2008\-2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

27
secure/lib/libcrypto/man/CMS_decrypt.3
View file

@ -128,22 +128,21 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CMS_decrypt 3"
.TH CMS_decrypt 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "CMS_DECRYPT 3"
.TH CMS_DECRYPT 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
.Vb 1
\& CMS_decrypt \- decrypt content from a CMS envelopedData structure
.Ve
CMS_decrypt \- decrypt content from a CMS envelopedData structure
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/cms.h>
\&
\& int CMS_decrypt(CMS_ContentInfo *cms, EVP_PKEY *pkey, X509 *cert, BIO *dcont, BIO *out, unsigned int flags);
\& int CMS_decrypt(CMS_ContentInfo *cms, EVP_PKEY *pkey, X509 *cert,
\& BIO *dcont, BIO *out, unsigned int flags);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
@ -156,9 +155,6 @@ The \fBdcont\fR parameter is used in the rare case where the encrypted content
is detached. It will normally be set to \s-1NULL.\s0
.SH "NOTES"
.IX Header "NOTES"
\&\fIOpenSSL_add_all_algorithms()\fR (or equivalent) should be called before using this
function or errors about unknown algorithms will occur.
.PP
Although the recipients certificate is not needed to decrypt the data it is
needed to locate the appropriate (of possible several) recipients in the \s-1CMS\s0
structure.
@ -183,7 +179,7 @@ in advance using the \s-1CMS\s0 utility functions such as \fICMS_set1_pkey()\fR.
case both \fBcert\fR and \fBpkey\fR should be set to \s-1NULL.\s0
.PP
To process KEKRecipientInfo types \fICMS_set1_key()\fR or \fICMS_RecipientInfo_set0_key()\fR
and \fICMS_ReceipientInfo_decrypt()\fR should be called before \fICMS_decrypt()\fR and
and \fICMS_RecipientInfo_decrypt()\fR should be called before \fICMS_decrypt()\fR and
\&\fBcert\fR and \fBpkey\fR set to \s-1NULL.\s0
.PP
The following flags can be passed in the \fBflags\fR parameter.
@ -202,6 +198,11 @@ mentioned in \fICMS_verify()\fR also applies to \fICMS_decrypt()\fR.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIERR_get_error\fR\|(3), \fICMS_encrypt\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fICMS_decrypt()\fR was added to OpenSSL 0.9.8
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2008\-2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

20
secure/lib/libcrypto/man/CMS_encrypt.3
View file

@ -128,22 +128,21 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CMS_encrypt 3"
.TH CMS_encrypt 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "CMS_ENCRYPT 3"
.TH CMS_ENCRYPT 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
.Vb 1
\& CMS_encrypt \- create a CMS envelopedData structure
.Ve
CMS_encrypt \- create a CMS envelopedData structure
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/cms.h>
\&
\& CMS_ContentInfo *CMS_encrypt(STACK_OF(X509) *certs, BIO *in, const EVP_CIPHER *cipher, unsigned int flags);
\& CMS_ContentInfo *CMS_encrypt(STACK_OF(X509) *certs, BIO *in,
\& const EVP_CIPHER *cipher, unsigned int flags);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
@ -219,5 +218,12 @@ occurred. The error can be obtained from \fIERR_get_error\fR\|(3).
\&\fIERR_get_error\fR\|(3), \fICMS_decrypt\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fICMS_decrypt()\fR was added to OpenSSL 0.9.8
The \fB\s-1CMS_STREAM\s0\fR flag was first supported in OpenSSL 1.0.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2008\-2018 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

21
secure/lib/libcrypto/man/CMS_final.3
View file

@ -128,16 +128,14 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CMS_final 3"
.TH CMS_final 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "CMS_FINAL 3"
.TH CMS_FINAL 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
.Vb 1
\& CMS_final \- finalise a CMS_ContentInfo structure
.Ve
CMS_final \- finalise a CMS_ContentInfo structure
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
@ -149,7 +147,7 @@
.IX Header "DESCRIPTION"
\&\fICMS_final()\fR finalises the structure \fBcms\fR. It's purpose is to perform any
operations necessary on \fBcms\fR (digest computation for example) and set the
appropriate fields. The parameter \fBdata\fR contains the content to be
appropriate fields. The parameter \fBdata\fR contains the content to be
processed. The \fBdcont\fR parameter contains a \s-1BIO\s0 to write content to after
processing: this is only used with detached data and will usually be set to
\&\s-1NULL.\s0
@ -165,6 +163,11 @@ I/O functions perform finalisation operations internally.
.IX Header "SEE ALSO"
\&\fIERR_get_error\fR\|(3), \fICMS_sign\fR\|(3),
\&\fICMS_encrypt\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fICMS_final()\fR was added to OpenSSL 0.9.8
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2008\-2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

38
secure/lib/libcrypto/man/CMS_get0_RecipientInfos.3
View file

@ -128,14 +128,14 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CMS_get0_RecipientInfos 3"
.TH CMS_get0_RecipientInfos 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "CMS_GET0_RECIPIENTINFOS 3"
.TH CMS_GET0_RECIPIENTINFOS 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
CMS_get0_RecipientInfos, CMS_RecipientInfo_type, CMS_RecipientInfo_ktri_get0_signer_id,CMS_RecipientInfo_ktri_cert_cmp, CMS_RecipientInfo_set0_pkey, CMS_RecipientInfo_kekri_get0_id, CMS_RecipientInfo_kekri_id_cmp, CMS_RecipientInfo_set0_key, CMS_RecipientInfo_decrypt, CMS_RecipientInfo_encrypt \- CMS envelopedData RecipientInfo routines
CMS_get0_RecipientInfos, CMS_RecipientInfo_type, CMS_RecipientInfo_ktri_get0_signer_id, CMS_RecipientInfo_ktri_cert_cmp, CMS_RecipientInfo_set0_pkey, CMS_RecipientInfo_kekri_get0_id, CMS_RecipientInfo_kekri_id_cmp, CMS_RecipientInfo_set0_key, CMS_RecipientInfo_decrypt, CMS_RecipientInfo_encrypt \&\- CMS envelopedData RecipientInfo routines
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
@ -144,13 +144,22 @@ CMS_get0_RecipientInfos, CMS_RecipientInfo_type, CMS_RecipientInfo_ktri_get0_sig
\& 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_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_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);
@ -212,11 +221,11 @@ of \fICMS_decrypt()\fR is not appropriate.
.PP
In typical usage and application will retrieve all CMS_RecipientInfo structures
using \fICMS_get0_RecipientInfos()\fR and check the type of each using
\&\fICMS_RecpientInfo_type()\fR. Depending on the type the CMS_RecipientInfo structure
\&\fICMS_RecipientInfo_type()\fR. 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
\&\fICMS_RecpientInfo_decrypt()\fR called. If successful \fICMS_decrypt()\fR can be called
\&\fICMS_RecipientInfo_decrypt()\fR called. If successful \fICMS_decrypt()\fR can be called
with a \s-1NULL\s0 key to decrypt the enveloped content.
.PP
The \fICMS_RecipientInfo_encrypt()\fR can be used to add a new recipient to an
@ -242,6 +251,11 @@ Any error can be obtained from \fIERR_get_error\fR\|(3).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIERR_get_error\fR\|(3), \fICMS_decrypt\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
These functions were first was added to OpenSSL 0.9.8
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2008\-2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

22
secure/lib/libcrypto/man/CMS_get0_SignerInfos.3
View file

@ -128,14 +128,14 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CMS_get0_SignerInfos 3"
.TH CMS_get0_SignerInfos 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "CMS_GET0_SIGNERINFOS 3"
.TH CMS_GET0_SIGNERINFOS 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
CMS_get0_SignerInfos, CMS_SignerInfo_get0_signer_id, CMS_SignerInfo_get0_signature, CMS_SignerInfo_cert_cmp, CMS_set1_signer_cert \- CMS signedData signer functions.
CMS_SignerInfo_set1_signer_cert, CMS_get0_SignerInfos, CMS_SignerInfo_get0_signer_id, CMS_SignerInfo_get0_signature, CMS_SignerInfo_cert_cmp \&\- CMS signedData signer functions
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
@ -143,7 +143,8 @@ CMS_get0_SignerInfos, CMS_SignerInfo_get0_signer_id, CMS_SignerInfo_get0_signatu
\&
\& 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);
\& 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);
@ -158,7 +159,7 @@ associated with a specific CMS_SignerInfo structure \fBsi\fR. Either the
keyidentifier will be set in \fBkeyid\fR or \fBboth\fR issuer name and serial number
in \fBissuer\fR and \fBsno\fR.
.PP
\&\fICMS_SignerInfo_get0_signature()\fR retrieves the signature associated with
\&\fICMS_SignerInfo_get0_signature()\fR retrieves the signature associated with
\&\fBsi\fR in a pointer to an \s-1ASN1_OCTET_STRING\s0 structure. This pointer returned
corresponds to the internal signature value if \fBsi\fR so it may be read or
modified.
@ -203,6 +204,11 @@ Any error can be obtained from \fIERR_get_error\fR\|(3)
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIERR_get_error\fR\|(3), \fICMS_verify\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
These functions were first was added to OpenSSL 0.9.8
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2008\-2018 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

22
secure/lib/libcrypto/man/CMS_get0_type.3
View file

@ -128,22 +128,20 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CMS_get0_type 3"
.TH CMS_get0_type 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "CMS_GET0_TYPE 3"
.TH CMS_GET0_TYPE 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
.Vb 1
\& CMS_get0_type, CMS_set1_eContentType, CMS_get0_eContentType, CMS_get0_content \- get and set CMS content types and content
.Ve
CMS_get0_type, CMS_set1_eContentType, CMS_get0_eContentType, CMS_get0_content \- get and set CMS content types and content
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/cms.h>
\&
\& const ASN1_OBJECT *CMS_get0_type(CMS_ContentInfo *cms);
\& const ASN1_OBJECT *CMS_get0_type(const CMS_ContentInfo *cms);
\& int CMS_set1_eContentType(CMS_ContentInfo *cms, const ASN1_OBJECT *oid);
\& const ASN1_OBJECT *CMS_get0_eContentType(CMS_ContentInfo *cms);
\& ASN1_OCTET_STRING **CMS_get0_content(CMS_ContentInfo *cms);
@ -204,7 +202,11 @@ error can be obtained from \fIERR_get_error\fR\|(3).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIERR_get_error\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fICMS_get0_type()\fR, \fICMS_set1_eContentType()\fR and \fICMS_get0_eContentType()\fR were all
first added to OpenSSL 0.9.8
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2008\-2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

33
secure/lib/libcrypto/man/CMS_get1_ReceiptRequest.3
View file

@ -128,25 +128,29 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CMS_get1_ReceiptRequest 3"
.TH CMS_get1_ReceiptRequest 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "CMS_GET1_RECEIPTREQUEST 3"
.TH CMS_GET1_RECEIPTREQUEST 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
.Vb 1
\& CMS_ReceiptRequest_create0, CMS_add1_ReceiptRequest, CMS_get1_ReceiptRequest, CMS_ReceiptRequest_get0_values \- CMS signed receipt request functions.
.Ve
CMS_ReceiptRequest_create0, CMS_add1_ReceiptRequest, CMS_get1_ReceiptRequest, CMS_ReceiptRequest_get0_values \- CMS signed receipt request functions
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #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);
\& 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);
\& void CMS_ReceiptRequest_get0_values(CMS_ReceiptRequest *rr, ASN1_STRING **pcid,
\& int *pallorfirst,
\& STACK_OF(GENERAL_NAMES) **plist,
\& STACK_OF(GENERAL_NAMES) **prto);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
@ -178,7 +182,7 @@ corresponding CMS_ContentInfo structure can be successfully verified using
\&\fICMS_verify()\fR.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fICMS_ReceiptRequest_create0()\fR returns a signed receipt request structure or
\&\fICMS_ReceiptRequest_create0()\fR returns a signed receipt request structure or
\&\s-1NULL\s0 if an error occurred.
.PP
\&\fICMS_add1_ReceiptRequest()\fR returns 1 for success or 0 if an error occurred.
@ -191,8 +195,11 @@ it is present but malformed.
\&\fIERR_get_error\fR\|(3), \fICMS_sign\fR\|(3),
\&\fICMS_sign_receipt\fR\|(3), \fICMS_verify\fR\|(3)
\&\fICMS_verify_receipt\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fICMS_ReceiptRequest_create0()\fR, \fICMS_add1_ReceiptRequest()\fR,
\&\fICMS_get1_ReceiptRequest()\fR and \fICMS_ReceiptRequest_get0_values()\fR were added to
OpenSSL 0.9.8
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2008\-2018 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

23
secure/lib/libcrypto/man/CMS_sign.3
View file

@ -128,22 +128,21 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CMS_sign 3"
.TH CMS_sign 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "CMS_SIGN 3"
.TH CMS_SIGN 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
.Vb 1
\& CMS_sign \- create a CMS SignedData structure
.Ve
CMS_sign \- create a CMS SignedData structure
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/cms.h>
\&
\& CMS_ContentInfo *CMS_sign(X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs, BIO *data, unsigned int flags);
\& CMS_ContentInfo *CMS_sign(X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs,
\& BIO *data, unsigned int flags);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
@ -229,7 +228,7 @@ suitable for many purposes. For finer control of the output format the
\&\fBcerts\fR, \fBsigncert\fR and \fBpkey\fR parameters can all be \fB\s-1NULL\s0\fR and the
\&\fB\s-1CMS_PARTIAL\s0\fR flag set. Then one or more signers can be added using the
function \fICMS_sign_add1_signer()\fR, non default digests can be used and custom
attributes added. \fB\f(BICMS_final()\fB\fR must then be called to finalize the
attributes added. \fICMS_final()\fR must then be called to finalize the
structure if streaming is not enabled.
.SH "BUGS"
.IX Header "BUGS"
@ -243,7 +242,13 @@ occurred. The error can be obtained from \fIERR_get_error\fR\|(3).
\&\fIERR_get_error\fR\|(3), \fICMS_verify\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fICMS_sign()\fR was added to OpenSSL 0.9.8
.PP
The \fB\s-1CMS_STREAM\s0\fR 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.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2008\-2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

23
secure/lib/libcrypto/man/CMS_sign_receipt.3
View file

@ -128,22 +128,22 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CMS_sign_receipt 3"
.TH CMS_sign_receipt 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "CMS_SIGN_RECEIPT 3"
.TH CMS_SIGN_RECEIPT 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
.Vb 1
\& CMS_sign_receipt \- create a CMS signed receipt
.Ve
CMS_sign_receipt \- create a CMS signed receipt
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/cms.h>
\&
\& CMS_ContentInfo *CMS_sign_receipt(CMS_SignerInfo *si, X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs, unsigned int flags);
\& CMS_ContentInfo *CMS_sign_receipt(CMS_SignerInfo *si, X509 *signcert,
\& EVP_PKEY *pkey, STACK_OF(X509) *certs,
\& unsigned int flags);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
@ -169,6 +169,11 @@ an error occurred. The error can be obtained from \fIERR_get_error\fR\|(3).
\&\fIERR_get_error\fR\|(3),
\&\fICMS_verify_receipt\fR\|(3),
\&\fICMS_sign\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fICMS_sign_receipt()\fR was added to OpenSSL 0.9.8
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2008\-2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

19
secure/lib/libcrypto/man/CMS_uncompress.3
View file

@ -128,16 +128,14 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CMS_uncompress 3"
.TH CMS_uncompress 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "CMS_UNCOMPRESS 3"
.TH CMS_UNCOMPRESS 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
.Vb 1
\& CMS_uncompress \- uncompress a CMS CompressedData structure
.Ve
CMS_uncompress \- uncompress a CMS CompressedData structure
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
@ -177,6 +175,11 @@ mentioned in \fICMS_verify()\fR also applies to \fICMS_decompress()\fR.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIERR_get_error\fR\|(3), \fICMS_compress\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fICMS_uncompress()\fR was added to OpenSSL 0.9.8
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2008\-2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

26
secure/lib/libcrypto/man/CMS_verify.3
View file

@ -128,8 +128,8 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CMS_verify 3"
.TH CMS_verify 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "CMS_VERIFY 3"
.TH CMS_VERIFY 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
@ -141,7 +141,8 @@ CMS_verify, CMS_get0_signers \- verify a CMS SignedData structure
.Vb 1
\& #include <openssl/cms.h>
\&
\& int CMS_verify(CMS_ContentInfo *cms, STACK_OF(X509) *certs, X509_STORE *store, BIO *indata, BIO *out, unsigned int flags);
\& 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);
.Ve
@ -199,7 +200,7 @@ returned.
If \fB\s-1CMS_NO_SIGNER_CERT_VERIFY\s0\fR is set the signing certificates are not
verified.
.PP
If \fB\s-1CMS_NO_ATTR_VERIFY\s0\fR is set the signed attributes signature is not
If \fB\s-1CMS_NO_ATTR_VERIFY\s0\fR is set the signed attributes signature is not
verified.
.PP
If \fB\s-1CMS_NO_CONTENT_VERIFY\s0\fR is set then the content digest is not checked.
@ -212,13 +213,13 @@ certificates supplied in \fBcerts\fR then the verify will fail because the
signer cannot be found.
.PP
In some cases the standard techniques for looking up and validating
certificates are not appropriate: for example an application may wish to
certificates are not appropriate: for example an application may wish to
lookup certificates in a database or perform customised verification. This
can be achieved by setting and verifying the signers certificates manually
can be achieved by setting and verifying the signers certificates manually
using the signed data utility functions.
.PP
Care should be taken when modifying the default verify behaviour, for example
setting \fB\s-1CMS_NO_CONTENT_VERIFY\s0\fR will totally disable all content verification
setting \fB\s-1CMS_NO_CONTENT_VERIFY\s0\fR 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 \fBout\fR and its validity
is not considered important.
@ -246,6 +247,11 @@ be held in memory if it is not detached.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIERR_get_error\fR\|(3), \fICMS_sign\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fICMS_verify()\fR was added to OpenSSL 0.9.8
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2008\-2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

23
secure/lib/libcrypto/man/CMS_verify_receipt.3
View file

@ -128,22 +128,22 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CMS_verify_receipt 3"
.TH CMS_verify_receipt 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "CMS_VERIFY_RECEIPT 3"
.TH CMS_VERIFY_RECEIPT 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
.Vb 1
\& CMS_verify_receipt \- verify a CMS signed receipt
.Ve
CMS_verify_receipt \- verify a CMS signed receipt
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/cms.h>
\&
\& int CMS_verify_receipt(CMS_ContentInfo *rcms, CMS_ContentInfo *ocms, STACK_OF(X509) *certs, X509_STORE *store, unsigned int flags);
\& int CMS_verify_receipt(CMS_ContentInfo *rcms, CMS_ContentInfo *ocms,
\& STACK_OF(X509) *certs, X509_STORE *store,
\& unsigned int flags);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
@ -171,6 +171,11 @@ The error can be obtained from \fIERR_get_error\fR\|(3)
\&\fIERR_get_error\fR\|(3),
\&\fICMS_sign_receipt\fR\|(3),
\&\fICMS_verify\fR\|(3),
.SH "HISTORY"
.IX Header "HISTORY"
\&\fICMS_verify_receipt()\fR was added to OpenSSL 0.9.8
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2008\-2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

44
secure/lib/libcrypto/man/CONF_modules_free.3
View file

@ -128,30 +128,36 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CONF_modules_free 3"
.TH CONF_modules_free 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "CONF_MODULES_FREE 3"
.TH CONF_MODULES_FREE 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
.Vb 2
\& CONF_modules_free, CONF_modules_finish, CONF_modules_unload \-
\& OpenSSL configuration cleanup functions
.Ve
CONF_modules_free, CONF_modules_finish, CONF_modules_unload \- OpenSSL configuration cleanup functions
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/conf.h>
\&
\& void CONF_modules_free(void);
\& void CONF_modules_finish(void);
\& void CONF_modules_unload(int all);
.Ve
.PP
Deprecated:
.PP
.Vb 3
\& #if OPENSSL_API_COMPAT < 0x10100000L
\& void CONF_modules_free(void)
\& #endif
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fICONF_modules_free()\fR closes down and frees up all memory allocated by all
configuration modules.
configuration modules. Normally, in versions of OpenSSL prior to 1.1.0,
applications called
\&\fICONF_modules_free()\fR at exit to tidy up any configuration performed.
.PP
\&\fICONF_modules_finish()\fR calls each configuration modules \fBfinish\fR handler
to free up any configuration that module may have performed.
@ -159,18 +165,22 @@ to free up any configuration that module may have performed.
\&\fICONF_modules_unload()\fR finishes and unloads configuration modules. If
\&\fBall\fR is set to \fB0\fR only modules loaded from DSOs will be unloads. If
\&\fBall\fR is \fB1\fR all modules, including builtin modules will be unloaded.
.SH "NOTES"
.IX Header "NOTES"
Normally applications will only call \fICONF_modules_free()\fR at application to
tidy up any configuration performed.
.SH "RETURN VALUE"
.IX Header "RETURN VALUE"
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
None of the functions return a value.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIconf\fR\|(5), \fIOPENSSL_config\fR\|(3),
\&\fIconfig\fR\|(5), \fIOPENSSL_config\fR\|(3),
\&\fICONF_modules_load_file\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fICONF_modules_free()\fR, \fICONF_modules_unload()\fR, and \fICONF_modules_finish()\fR
first appeared in OpenSSL 0.9.7.
\&\fICONF_modules_free()\fR was deprecated in OpenSSL 1.1.0; do not use it.
For more information see \fIOPENSSL_init_crypto\fR\|(3).
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2004\-2018 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

85
secure/lib/libcrypto/man/CONF_modules_load_file.3
View file

@ -128,25 +128,23 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CONF_modules_load_file 3"
.TH CONF_modules_load_file 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "CONF_MODULES_LOAD_FILE 3"
.TH CONF_MODULES_LOAD_FILE 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
.Vb 1
\& CONF_modules_load_file, CONF_modules_load \- OpenSSL configuration functions
.Ve
CONF_modules_load_file, CONF_modules_load \- OpenSSL configuration functions
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/conf.h>
\&
\& int CONF_modules_load_file(const char *filename, const char *appname,
\& unsigned long flags);
\& unsigned long flags);
\& int CONF_modules_load(const CONF *cnf, const char *appname,
\& unsigned long flags);
\& unsigned long flags);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
@ -154,9 +152,9 @@ The function \fICONF_modules_load_file()\fR configures OpenSSL using file
\&\fBfilename\fR and application name \fBappname\fR. If \fBfilename\fR is \s-1NULL\s0
the standard OpenSSL configuration file is used. If \fBappname\fR is
\&\s-1NULL\s0 the standard OpenSSL application name \fBopenssl_conf\fR is used.
The behaviour can be cutomized using \fBflags\fR.
The behaviour can be customized using \fBflags\fR.
.PP
\&\fICONF_modules_load()\fR is idential to \fICONF_modules_load_file()\fR except it
\&\fICONF_modules_load()\fR is identical to \fICONF_modules_load_file()\fR except it
reads configuration information from \fBcnf\fR.
.SH "NOTES"
.IX Header "NOTES"
@ -179,12 +177,6 @@ return an error.
\&\fB\s-1CONF_MFLAGS_DEFAULT_SECTION\s0\fR if set and \fBappname\fR is not \s-1NULL\s0 will use the
default section pointed to by \fBopenssl_conf\fR if \fBappname\fR does not exist.
.PP
Applications should call these functions after loading builtin modules using
\&\fIOPENSSL_load_builtin_modules()\fR, any ENGINEs for example using
\&\fIENGINE_load_builtin_engines()\fR, any algorithms for example
\&\fIOPENSSL_add_all_algorithms()\fR and (if the application uses libssl)
\&\fISSL_library_init()\fR.
.PP
By using \fICONF_modules_load_file()\fR 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
@ -205,9 +197,9 @@ considered fatal):
.PP
.Vb 5
\& if (CONF_modules_load_file(NULL, NULL, 0) <= 0) {
\& fprintf(stderr, "FATAL: error loading configuration file\en");
\& ERR_print_errors_fp(stderr);
\& exit(1);
\& fprintf(stderr, "FATAL: error loading configuration file\en");
\& ERR_print_errors_fp(stderr);
\& exit(1);
\& }
.Ve
.PP
@ -217,9 +209,9 @@ tolerate missing files, but exit on other errors:
.Vb 6
\& if (CONF_modules_load_file(NULL, "myapp",
\& CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) {
\& fprintf(stderr, "FATAL: error loading configuration file\en");
\& ERR_print_errors_fp(stderr);
\& exit(1);
\& fprintf(stderr, "FATAL: error loading configuration file\en");
\& ERR_print_errors_fp(stderr);
\& exit(1);
\& }
.Ve
.PP
@ -229,35 +221,36 @@ missing configuration file ignored:
.Vb 5
\& if (CONF_modules_load_file("/something/app.cnf", "myapp",
\& CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) {
\& fprintf(stderr, "WARNING: error loading configuration file\en");
\& ERR_print_errors_fp(stderr);
\& fprintf(stderr, "WARNING: error loading configuration file\en");
\& ERR_print_errors_fp(stderr);
\& }
.Ve
.PP
Load and parse configuration file manually, custom error handling:
.PP
.Vb 10
.Vb 3
\& FILE *fp;
\& CONF *cnf = NULL;
\& long eline;
\&
\& fp = fopen("/somepath/app.cnf", "r");
\& if (fp == NULL) {
\& fprintf(stderr, "Error opening configuration file\en");
\& /* Other missing configuration file behaviour */
\& fprintf(stderr, "Error opening configuration file\en");
\& /* 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\en", 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\en");
\& ERR_print_errors_fp(stderr);
\& /* Other configuration error behaviour */
\& }
\& fclose(fp);
\& NCONF_free(cnf);
\& }
\& cnf = NCONF_new(NULL);
\& if (NCONF_load_fp(cnf, fp, &eline) == 0) {
\& fprintf(stderr, "Error on line %ld of configuration file\en", 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\en");
\& ERR_print_errors_fp(stderr);
\& /* Other configuration error behaviour */
\& }
\& fclose(fp);
\& NCONF_free(cnf);
\& }
.Ve
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
@ -266,8 +259,12 @@ 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).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIconf\fR\|(5), \fIOPENSSL_config\fR\|(3),
\&\fICONF_free\fR\|(3), \fIerr\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
CONF_modules_load_file and CONF_modules_load first appeared in OpenSSL 0.9.7.
\&\fIconfig\fR\|(5), \fIOPENSSL_config\fR\|(3)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2004\-2017 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

279
secure/lib/libcrypto/man/CRYPTO_THREAD_run_once.3 Normal file
View file

@ -0,0 +1,279 @@
.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CRYPTO_THREAD_RUN_ONCE 3"
.TH CRYPTO_THREAD_RUN_ONCE 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "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
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
OpenSSL can be safely used in multi-threaded applications provided that
support for the underlying \s-1OS\s0 threading \s-1API\s0 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 \s-1API\s0 that is not yet
supported by OpenSSL.
.PP
The following multi-threading function are provided:
.IP "\(bu" 2
\&\fICRYPTO_THREAD_run_once()\fR can be used to perform one-time initialization.
The \fBonce\fR argument must be a pointer to a static object of type
\&\fB\s-1CRYPTO_ONCE\s0\fR that was statically initialized to the value
\&\fB\s-1CRYPTO_ONCE_STATIC_INIT\s0\fR.
The \fBinit\fR 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.
.IP "\(bu" 2
\&\fICRYPTO_THREAD_lock_new()\fR allocates, initializes and returns a new read/write
lock.
.IP "\(bu" 2
\&\fICRYPTO_THREAD_read_lock()\fR locks the provided \fBlock\fR for reading.
.IP "\(bu" 2
\&\fICRYPTO_THREAD_write_lock()\fR locks the provided \fBlock\fR for writing.
.IP "\(bu" 2
\&\fICRYPTO_THREAD_unlock()\fR unlocks the previously locked \fBlock\fR.
.IP "\(bu" 2
\&\fICRYPTO_THREAD_lock_free()\fR frees the provided \fBlock\fR.
.IP "\(bu" 2
\&\fICRYPTO_atomic_add()\fR atomically adds \fBamount\fR to \fBval\fR and returns the
result of the operation in \fBret\fR. \fBlock\fR will be locked, unless atomic
operations are supported on the specific platform. Because of this, if a
variable is modified by \fICRYPTO_atomic_add()\fR then \fICRYPTO_atomic_add()\fR must
be the only way that the variable is modified.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fICRYPTO_THREAD_run_once()\fR returns 1 on success, or 0 on error.
.PP
\&\fICRYPTO_THREAD_lock_new()\fR returns the allocated lock, or \s-1NULL\s0 on error.
.PP
\&\fICRYPTO_THREAD_lock_free()\fR returns no value.
.PP
The other functions return 1 on success, or 0 on error.
.SH "NOTES"
.IX Header "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.
.SH "EXAMPLE"
.IX Header "EXAMPLE"
This example safely initializes and uses a lock.
.PP
.Vb 4
\& #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;
\& }
.Ve
.PP
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 \*(L"leak\*(R" the lock in applications and not
repeatedly load/unload shared libraries that allocate locks.
.SH "NOTES"
.IX Header "NOTES"
You can find out if OpenSSL was configured with thread support:
.PP
.Vb 6
\& #include <openssl/opensslconf.h>
\& #if defined(OPENSSL_THREADS)
\& /* thread support enabled */
\& #else
\& /* no thread support */
\& #endif
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIcrypto\fR\|(7)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

294
secure/lib/libcrypto/man/CRYPTO_get_ex_new_index.3 Normal file
View file

@ -0,0 +1,294 @@
.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CRYPTO_GET_EX_NEW_INDEX 3"
.TH CRYPTO_GET_EX_NEW_INDEX 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "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
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Several OpenSSL structures can have application-specific data attached to them,
known as \*(L"exdata.\*(R"
The specific structures are:
.PP
.Vb 10
\& APP
\& BIO
\& DH
\& DRBG
\& DSA
\& EC_KEY
\& ENGINE
\& RSA
\& SSL
\& SSL_CTX
\& SSL_SESSION
\& UI
\& UI_METHOD
\& X509
\& X509_STORE
\& X509_STORE_CTX
.Ve
.PP
Each is identified by an \fBCRYPTO_EX_INDEX_xxx\fR define in the \fBcrypto.h\fR
header file. In addition, \fB\s-1CRYPTO_EX_INDEX_APP\s0\fR is reserved for
applications to use this facility for their own structures.
.PP
The \s-1API\s0 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 \fBvoid *\fR type.
.PP
The \fB\s-1CRYPTO_EX_DATA\s0\fR type is opaque. To initialize the exdata part of
a structure, call \fICRYPTO_new_ex_data()\fR. This is only necessary for
\&\fB\s-1CRYPTO_EX_INDEX_APP\s0\fR objects.
.PP
Exdata types are identified by an \fBindex\fR, an integer guaranteed to be
unique within structures for the lifetime of the program. Applications
using exdata typically call \fBCRYPTO_get_ex_new_index\fR at startup, and
store the result in a global variable, or write a wrapper function to
provide lazy evaluation. The \fBclass_index\fR should be one of the
\&\fBCRYPTO_EX_INDEX_xxx\fR values. The \fBargl\fR and \fBargp\fR 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.
.PP
When copying or releasing objects with exdata, the callback functions
are called in increasing order of their \fBindex\fR value.
.PP
If a dynamic library can be unloaded, it should call \fICRYPTO_free_ex_index()\fR
when this is done.
This will replace the callbacks with no-ops
so that applications don't crash. Any existing exdata will be leaked.
.PP
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 \fB\s-1CRYPTO_EX_DATA\s0\fR field is not accessible. In both \s-1API\s0's, the
\&\fBidx\fR parameter should be an already-created index value.
.PP
When setting exdata, the pointer specified with a particular index is saved,
and returned on a subsequent \*(L"get\*(R" call. If the application is going to
release the data, it must make sure to set a \fB\s-1NULL\s0\fR value at the index,
to avoid likely double-free crashes.
.PP
The function \fBCRYPTO_free_ex_data\fR is used to free all exdata attached
to a structure. The appropriate type-specific routine must be used.
The \fBclass_index\fR identifies the structure type, the \fBobj\fR is
be the pointer to the actual structure, and \fBr\fR is a pointer to the
structure's exdata field.
.SS "Callback Functions"
.IX Subsection "Callback Functions"
This section describes how the callback functions are used. Applications
that are defining their own exdata using \fB\s-1CYPRTO_EX_INDEX_APP\s0\fR must
call them as described here.
.PP
When a structure is initially allocated (such as \fIRSA_new()\fR) then the
\&\fInew_func()\fR is called for every defined index. There is no requirement
that the entire parent, or containing, structure has been set up.
The \fInew_func()\fR is typically used only to allocate memory to store the
exdata, and perhaps an \*(L"initialized\*(R" flag within that memory.
The exdata value should be set by calling \fICRYPTO_set_ex_data()\fR.
.PP
When a structure is free'd (such as \fISSL_CTX_free()\fR) then the
\&\fIfree_func()\fR is called for every defined index. Again, the state of the
parent structure is not guaranteed. The \fIfree_func()\fR may be called with a
\&\s-1NULL\s0 pointer.
.PP
Both \fInew_func()\fR and \fIfree_func()\fR take the same parameters.
The \fBparent\fR is the pointer to the structure that contains the exdata.
The \fBptr\fR is the current exdata item; for \fInew_func()\fR this will typically
be \s-1NULL.\s0 The \fBr\fR parameter is a pointer to the exdata field of the object.
The \fBidx\fR is the index and is the value returned when the callbacks were
initially registered via \fICRYPTO_get_ex_new_index()\fR and can be used if
the same callback handles different types of exdata.
.PP
\&\fIdup_func()\fR is called when a structure is being copied. This is only done
for \fB\s-1SSL\s0\fR, \fB\s-1SSL_SESSION\s0\fR, \fB\s-1EC_KEY\s0\fR objects and \fB\s-1BIO\s0\fR chains via
\&\fIBIO_dup_chain()\fR. The \fBto\fR and \fBfrom\fR parameters
are pointers to the destination and source \fB\s-1CRYPTO_EX_DATA\s0\fR structures,
respectively. The \fBfrom_d\fR parameter needs to be cast to a \fBvoid **pptr\fR
as the \s-1API\s0 has currently the wrong signature; that will be changed in a
future version. The \fB*pptr\fR is a pointer to the source exdata.
When the \fIdup_func()\fR returns, the value in \fB*pptr\fR is copied to the
destination ex_data. If the pointer contained in \fB*pptr\fR is not modified
by the \fIdup_func()\fR, then both \fBto\fR and \fBfrom\fR will point to the same data.
The \fBidx\fR, \fBargl\fR and \fBargp\fR parameters are as described for the other
two callbacks. If the \fIdup_func()\fR returns \fB0\fR the whole \fICRYPTO_dup_ex_data()\fR
will fail.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fICRYPTO_get_ex_new_index()\fR returns a new index or \-1 on failure.
.PP
\&\fICRYPTO_free_ex_index()\fR and
\&\fICRYPTO_set_ex_data()\fR return 1 on success or 0 on failure.
.PP
\&\fICRYPTO_get_ex_data()\fR returns the application data or \s-1NULL\s0 on failure;
note that \s-1NULL\s0 may be a valid value.
.PP
\&\fIdup_func()\fR should return 0 for failure and 1 for success.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2015\-2018 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

175
secure/lib/libcrypto/man/CTLOG_STORE_get0_log_by_id.3 Normal file
View file

@ -0,0 +1,175 @@
.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CTLOG_STORE_GET0_LOG_BY_ID 3"
.TH CTLOG_STORE_GET0_LOG_BY_ID 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
CTLOG_STORE_get0_log_by_id \- Get a Certificate Transparency log from a CTLOG_STORE
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
A Signed Certificate Timestamp (\s-1SCT\s0) identifies the Certificate Transparency
(\s-1CT\s0) log that issued it using the log's LogID (see \s-1RFC 6962,\s0 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.
.PP
\&\fICTLOG_STORE_get0_log_by_id()\fR provides a way to do this. It will find a \s-1CTLOG\s0
in a \s-1CTLOG_STORE\s0 that has a given LogID.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBCTLOG_STORE_get0_log_by_id\fR returns a \s-1CTLOG\s0 with the given LogID, if it
exists in the given \s-1CTLOG_STORE,\s0 otherwise it returns \s-1NULL.\s0
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIct\fR\|(7),
\&\fICTLOG_STORE_new\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
This function was added in OpenSSL 1.1.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

205
secure/lib/libcrypto/man/CTLOG_STORE_new.3 Normal file
View file

@ -0,0 +1,205 @@
.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CTLOG_STORE_NEW 3"
.TH CTLOG_STORE_NEW 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
CTLOG_STORE_new, CTLOG_STORE_free, CTLOG_STORE_load_default_file, CTLOG_STORE_load_file \- Create and populate a Certificate Transparency log list
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
A \s-1CTLOG_STORE\s0 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 \s-1RFC 6962,\s0 Section 3.2, for the definition of a LogID).
.PP
\&\fICTLOG_STORE_new()\fR creates an empty list of \s-1CT\s0 logs. This is then populated
by \fICTLOG_STORE_load_default_file()\fR or \fICTLOG_STORE_load_file()\fR.
\&\fICTLOG_STORE_load_default_file()\fR loads from the default file, which is named
\&\*(L"ct_log_list.cnf\*(R" in \s-1OPENSSLDIR\s0 (see the output of version). This can be
overridden using an environment variable named \*(L"\s-1CTLOG_FILE\*(R".\s0
\&\fICTLOG_STORE_load_file()\fR loads from a caller-specified file path instead.
Both of these functions append any loaded \s-1CT\s0 logs to the \s-1CTLOG_STORE.\s0
.PP
The expected format of the file is:
.PP
.Vb 1
\& enabled_logs=foo,bar
\&
\& [foo]
\& description = Log 1
\& key = <base64\-encoded DER SubjectPublicKeyInfo here>
\&
\& [bar]
\& description = Log 2
\& key = <base64\-encoded DER SubjectPublicKeyInfo here>
.Ve
.PP
Once a \s-1CTLOG_STORE\s0 is no longer required, it should be passed to
\&\fICTLOG_STORE_free()\fR. This will delete all of the CTLOGs stored within, along
with the \s-1CTLOG_STORE\s0 itself.
.SH "NOTES"
.IX Header "NOTES"
If there are any invalid \s-1CT\s0 logs in a file, they are skipped and the remaining
valid logs will still be added to the \s-1CTLOG_STORE. A CT\s0 log will be considered
invalid if it is missing a \*(L"key\*(R" or \*(L"description\*(R" field.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
Both \fBCTLOG_STORE_load_default_file\fR and \fBCTLOG_STORE_load_file\fR return 1 if
all \s-1CT\s0 logs in the file are successfully parsed and loaded, 0 otherwise.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIct\fR\|(7),
\&\fICTLOG_STORE_get0_log_by_id\fR\|(3),
\&\fISSL_CTX_set_ctlog_list_file\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
These functions were added in OpenSSL 1.1.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

197
secure/lib/libcrypto/man/CTLOG_new.3 Normal file
View file

@ -0,0 +1,197 @@
.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CTLOG_NEW 3"
.TH CTLOG_NEW 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "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
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fICTLOG_new()\fR returns a new \s-1CTLOG\s0 that represents the Certificate Transparency
(\s-1CT\s0) 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.
.PP
\&\fICTLOG_new_from_base64()\fR also creates a new \s-1CTLOG,\s0 but takes the public key in
base64\-encoded \s-1DER\s0 form and sets the ct_log pointer to point to the new \s-1CTLOG.\s0
The base64 will be decoded and the public key parsed.
.PP
Regardless of whether \fICTLOG_new()\fR or \fICTLOG_new_from_base64()\fR is used, it is the
caller's responsibility to pass the \s-1CTLOG\s0 to \fICTLOG_free()\fR once it is no longer
needed. This will delete it and, if created by \fICTLOG_new()\fR, the \s-1EVP_PKEY\s0 that
was passed to it.
.PP
\&\fICTLOG_get0_name()\fR returns the name of the log, as provided when the \s-1CTLOG\s0 was
created. Ownership of the string remains with the \s-1CTLOG.\s0
.PP
\&\fICTLOG_get0_log_id()\fR sets *log_id to point to a string containing that log's
LogID (see \s-1RFC 6962\s0). It sets *log_id_len to the length of that LogID. For a
v1 \s-1CT\s0 log, the LogID will be a \s-1SHA\-256\s0 hash (i.e. 32 bytes long). Ownership of
the string remains with the \s-1CTLOG.\s0
.PP
\&\fICTLOG_get0_public_key()\fR returns the public key of the \s-1CT\s0 log. Ownership of the
\&\s-1EVP_PKEY\s0 remains with the \s-1CTLOG.\s0
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fICTLOG_new()\fR will return \s-1NULL\s0 if an error occurs.
.PP
\&\fICTLOG_new_from_base64()\fR will return 1 on success, 0 otherwise.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIct\fR\|(7)
.SH "HISTORY"
.IX Header "HISTORY"
These functions were added in OpenSSL 1.1.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

225
secure/lib/libcrypto/man/CT_POLICY_EVAL_CTX_new.3 Normal file
View file

@ -0,0 +1,225 @@
.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CT_POLICY_EVAL_CTX_NEW 3"
.TH CT_POLICY_EVAL_CTX_NEW 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "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
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
A \fB\s-1CT_POLICY_EVAL_CTX\s0\fR is used by functions that evaluate whether Signed
Certificate Timestamps (SCTs) fulfil a Certificate Transparency (\s-1CT\s0) policy.
This policy may be, for example, that at least one valid \s-1SCT\s0 is available. To
determine this, an \s-1SCT\s0's timestamp and signature must be verified.
This requires:
.IP "\(bu" 2
the public key of the log that issued the \s-1SCT\s0
.IP "\(bu" 2
the certificate that the \s-1SCT\s0 was issued for
.IP "\(bu" 2
the issuer certificate (if the \s-1SCT\s0 was issued for a pre-certificate)
.IP "\(bu" 2
the current time
.PP
The above requirements are met using the setters described below.
.PP
\&\fICT_POLICY_EVAL_CTX_new()\fR creates an empty policy evaluation context. This
should then be populated using:
.IP "\(bu" 2
\&\fICT_POLICY_EVAL_CTX_set1_cert()\fR to provide the certificate the SCTs were issued for
.Sp
Increments the reference count of the certificate.
.IP "\(bu" 2
\&\fICT_POLICY_EVAL_CTX_set1_issuer()\fR to provide the issuer certificate
.Sp
Increments the reference count of the certificate.
.IP "\(bu" 2
\&\fICT_POLICY_EVAL_CTX_set_shared_CTLOG_STORE()\fR to provide a list of logs that are trusted as sources of SCTs
.Sp
Holds a pointer to the \s-1CTLOG_STORE,\s0 so the \s-1CTLOG_STORE\s0 must outlive the
\&\s-1CT_POLICY_EVAL_CTX.\s0
.IP "\(bu" 2
\&\fICT_POLICY_EVAL_CTX_set_time()\fR to set the time SCTs should be compared with to determine if they are valid
.Sp
The \s-1SCT\s0 timestamp will be compared to this time to check whether the \s-1SCT\s0 was
issued in the future. \s-1RFC6962\s0 states that \*(L"\s-1TLS\s0 clients \s-1MUST\s0 reject SCTs whose
timestamp is in the future\*(R". By default, this will be set to 5 minutes in the
future (e.g. (\fItime()\fR + 300) * 1000), to allow for clock drift.
.Sp
The time should be in milliseconds since the Unix epoch.
.PP
Each setter has a matching getter for accessing the current value.
.PP
When no longer required, the \fB\s-1CT_POLICY_EVAL_CTX\s0\fR should be passed to
\&\fICT_POLICY_EVAL_CTX_free()\fR to delete it.
.SH "NOTES"
.IX Header "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 \s-1TLS SCT\s0 extension or \s-1OCSP\s0 response.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fICT_POLICY_EVAL_CTX_new()\fR will return \s-1NULL\s0 if malloc fails.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIct\fR\|(7)
.SH "HISTORY"
.IX Header "HISTORY"
These functions were added in OpenSSL 1.1.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

400
secure/lib/libcrypto/man/DEFINE_STACK_OF.3 Normal file
View file

@ -0,0 +1,400 @@
.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "DEFINE_STACK_OF 3"
.TH DEFINE_STACK_OF 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "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
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #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);
.Ve
.SH "DESCRIPTION"
.IX Header "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 \fBOPENSSL_sk_\fR \s-1API.\s0
In the description here, \fI\s-1TYPE\s0\fR is used
as a placeholder for any of the OpenSSL datatypes, such as \fIX509\fR.
.PP
\&\s-1\fISTACK_OF\s0()\fR returns the name for a stack of the specified \fB\s-1TYPE\s0\fR.
\&\s-1\fIDEFINE_STACK_OF\s0()\fR creates set of functions for a stack of \fB\s-1TYPE\s0\fR. This
will mean that type \fB\s-1TYPE\s0\fR is stored in each stack, the type is referenced by
\&\s-1STACK_OF\s0(\s-1TYPE\s0) and each function name begins with \fIsk_TYPE_\fR. For example:
.PP
.Vb 1
\& TYPE *sk_TYPE_value(STACK_OF(TYPE) *sk, int idx);
.Ve
.PP
\&\s-1\fIDEFINE_STACK_OF_CONST\s0()\fR is identical to \s-1\fIDEFINE_STACK_OF\s0()\fR except
each element is constant. For example:
.PP
.Vb 1
\& const TYPE *sk_TYPE_value(STACK_OF(TYPE) *sk, int idx);
.Ve
.PP
\&\s-1\fIDEFINE_SPECIAL_STACK_OF\s0()\fR defines a stack of \fB\s-1TYPE\s0\fR but
each function uses \fB\s-1FUNCNAME\s0\fR in the function name. For example:
.PP
.Vb 1
\& TYPE *sk_FUNCNAME_value(STACK_OF(TYPE) *sk, int idx);
.Ve
.PP
\&\s-1\fIDEFINE_SPECIAL_STACK_OF_CONST\s0()\fR is similar except that each element is
constant:
.PP
.Vb 1
\& const TYPE *sk_FUNCNAME_value(STACK_OF(TYPE) *sk, int idx);
.Ve
.PP
\&\fIsk_TYPE_num()\fR returns the number of elements in \fBsk\fR or \-1 if \fBsk\fR is
\&\fB\s-1NULL\s0\fR.
.PP
\&\fIsk_TYPE_value()\fR returns element \fBidx\fR in \fBsk\fR, where \fBidx\fR starts at
zero. If \fBidx\fR is out of range then \fB\s-1NULL\s0\fR is returned.
.PP
\&\fIsk_TYPE_new()\fR allocates a new empty stack using comparison function \fBcompare\fR.
If \fBcompare\fR is \fB\s-1NULL\s0\fR then no comparison function is used. This function is
equivalent to sk_TYPE_new_reserve(compare, 0).
.PP
\&\fIsk_TYPE_new_null()\fR allocates a new empty stack with no comparison function. This
function is equivalent to sk_TYPE_new_reserve(\s-1NULL, 0\s0).
.PP
\&\fIsk_TYPE_reserve()\fR allocates additional memory in the \fBsk\fR structure
such that the next \fBn\fR calls to \fIsk_TYPE_insert()\fR, \fIsk_TYPE_push()\fR
or \fIsk_TYPE_unshift()\fR will not fail or cause memory to be allocated
or reallocated. If \fBn\fR is zero, any excess space allocated in the
\&\fBsk\fR structure is freed. On error \fBsk\fR is unchanged.
.PP
\&\fIsk_TYPE_new_reserve()\fR allocates a new stack. The new stack will have additional
memory allocated to hold \fBn\fR elements if \fBn\fR is positive. The next \fBn\fR calls
to \fIsk_TYPE_insert()\fR, \fIsk_TYPE_push()\fR or \fIsk_TYPE_unshift()\fR will not fail or cause
memory to be allocated or reallocated. If \fBn\fR is zero or less than zero, no
memory is allocated. \fIsk_TYPE_new_reserve()\fR also sets the comparison function
\&\fBcompare\fR to the newly created stack. If \fBcompare\fR is \fB\s-1NULL\s0\fR then no
comparison function is used.
.PP
\&\fIsk_TYPE_set_cmp_func()\fR sets the comparison function of \fBsk\fR to \fBcompare\fR.
The previous comparison function is returned or \fB\s-1NULL\s0\fR if there was
no previous comparison function.
.PP
\&\fIsk_TYPE_free()\fR frees up the \fBsk\fR structure. It does \fBnot\fR free up any
elements of \fBsk\fR. After this call \fBsk\fR is no longer valid.
.PP
\&\fIsk_TYPE_zero()\fR sets the number of elements in \fBsk\fR to zero. It does not free
\&\fBsk\fR so after this call \fBsk\fR is still valid.
.PP
\&\fIsk_TYPE_pop_free()\fR frees up all elements of \fBsk\fR and \fBsk\fR itself. The
free function \fIfreefunc()\fR is called on each element to free it.
.PP
\&\fIsk_TYPE_delete()\fR deletes element \fBi\fR from \fBsk\fR. It returns the deleted
element or \fB\s-1NULL\s0\fR if \fBi\fR is out of range.
.PP
\&\fIsk_TYPE_delete_ptr()\fR deletes element matching \fBptr\fR from \fBsk\fR. It returns
the deleted element or \fB\s-1NULL\s0\fR if no element matching \fBptr\fR was found.
.PP
\&\fIsk_TYPE_insert()\fR inserts \fBptr\fR into \fBsk\fR at position \fBidx\fR. Any existing
elements at or after \fBidx\fR are moved downwards. If \fBidx\fR is out of range
the new element is appended to \fBsk\fR. \fIsk_TYPE_insert()\fR either returns the
number of elements in \fBsk\fR after the new element is inserted or zero if
an error (such as memory allocation failure) occurred.
.PP
\&\fIsk_TYPE_push()\fR appends \fBptr\fR to \fBsk\fR it is equivalent to:
.PP
.Vb 1
\& sk_TYPE_insert(sk, ptr, \-1);
.Ve
.PP
\&\fIsk_TYPE_unshift()\fR inserts \fBptr\fR at the start of \fBsk\fR it is equivalent to:
.PP
.Vb 1
\& sk_TYPE_insert(sk, ptr, 0);
.Ve
.PP
\&\fIsk_TYPE_pop()\fR returns and removes the last element from \fBsk\fR.
.PP
\&\fIsk_TYPE_shift()\fR returns and removes the first element from \fBsk\fR.
.PP
\&\fIsk_TYPE_set()\fR sets element \fBidx\fR of \fBsk\fR to \fBptr\fR replacing the current
element. The new element value is returned or \fB\s-1NULL\s0\fR if an error occurred:
this will only happen if \fBsk\fR is \fB\s-1NULL\s0\fR or \fBidx\fR is out of range.
.PP
\&\fIsk_TYPE_find()\fR searches \fBsk\fR for the element \fBptr\fR. In the case
where no comparison function has been specified, the function performs
a linear search for a pointer equal to \fBptr\fR. The index of the first
matching element is returned or \fB\-1\fR if there is no match. In the case
where a comparison function has been specified, \fBsk\fR is sorted then
\&\fIsk_TYPE_find()\fR returns the index of a matching element or \fB\-1\fR 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 \fBsk\fR could change.
.PP
\&\fIsk_TYPE_find_ex()\fR operates like \fIsk_TYPE_find()\fR except when a comparison
function has been specified and no matching element is found. Instead
of returning \fB\-1\fR, \fIsk_TYPE_find_ex()\fR returns the index of the element
either before or after the location where \fBptr\fR would be if it were
present in \fBsk\fR.
.PP
\&\fIsk_TYPE_sort()\fR sorts \fBsk\fR using the supplied comparison function.
.PP
\&\fIsk_TYPE_is_sorted()\fR returns \fB1\fR if \fBsk\fR is sorted and \fB0\fR otherwise.
.PP
\&\fIsk_TYPE_dup()\fR returns a copy of \fBsk\fR. Note the pointers in the copy
are identical to the original.
.PP
\&\fIsk_TYPE_deep_copy()\fR returns a new stack where each element has been copied.
Copying is performed by the supplied \fIcopyfunc()\fR and freeing by \fIfreefunc()\fR. The
function \fIfreefunc()\fR is only called if an error occurs.
.SH "NOTES"
.IX Header "NOTES"
Care should be taken when accessing stacks in multi-threaded environments.
Any operation which increases the size of a stack such as \fIsk_TYPE_insert()\fR or
\&\fIsk_push()\fR can \*(L"grow\*(R" the size of an internal array and cause race conditions
if the same stack is accessed in a different thread. Operations such as
\&\fIsk_find()\fR and \fIsk_sort()\fR can also reorder the stack.
.PP
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 \fBa\fR is equal to, greater than
or less than \fBb\fR respectively.
.PP
Care should be taken when checking the return values of the functions
\&\fIsk_TYPE_find()\fR and \fIsk_TYPE_find_ex()\fR. They return an index to the
matching element. In particular \fB0\fR indicates a matching first element.
A failed search is indicated by a \fB\-1\fR return value.
.PP
\&\s-1\fISTACK_OF\s0()\fR, \s-1\fIDEFINE_STACK_OF\s0()\fR, \s-1\fIDEFINE_STACK_OF_CONST\s0()\fR, and
\&\s-1\fIDEFINE_SPECIAL_STACK_OF\s0()\fR are implemented as macros.
.PP
The underlying utility \fBOPENSSL_sk_\fR \s-1API\s0 should not be used directly.
It defines these functions: \fIOPENSSL_sk_deep_copy()\fR,
\&\fIOPENSSL_sk_delete()\fR, \fIOPENSSL_sk_delete_ptr()\fR, \fIOPENSSL_sk_dup()\fR,
\&\fIOPENSSL_sk_find()\fR, \fIOPENSSL_sk_find_ex()\fR, \fIOPENSSL_sk_free()\fR,
\&\fIOPENSSL_sk_insert()\fR, \fIOPENSSL_sk_is_sorted()\fR, \fIOPENSSL_sk_new()\fR,
\&\fIOPENSSL_sk_new_null()\fR, \fIOPENSSL_sk_num()\fR, \fIOPENSSL_sk_pop()\fR,
\&\fIOPENSSL_sk_pop_free()\fR, \fIOPENSSL_sk_push()\fR, \fIOPENSSL_sk_reserve()\fR,
\&\fIOPENSSL_sk_set()\fR, \fIOPENSSL_sk_set_cmp_func()\fR, \fIOPENSSL_sk_shift()\fR,
\&\fIOPENSSL_sk_sort()\fR, \fIOPENSSL_sk_unshift()\fR, \fIOPENSSL_sk_value()\fR,
\&\fIOPENSSL_sk_zero()\fR.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fIsk_TYPE_num()\fR returns the number of elements in the stack or \fB\-1\fR if the
passed stack is \fB\s-1NULL\s0\fR.
.PP
\&\fIsk_TYPE_value()\fR returns a pointer to a stack element or \fB\s-1NULL\s0\fR if the
index is out of range.
.PP
\&\fIsk_TYPE_new()\fR, \fIsk_TYPE_new_null()\fR and \fIsk_TYPE_new_reserve()\fR return an empty
stack or \fB\s-1NULL\s0\fR if an error occurs.
.PP
\&\fIsk_TYPE_reserve()\fR returns \fB1\fR on successful allocation of the required memory
or \fB0\fR on error.
.PP
\&\fIsk_TYPE_set_cmp_func()\fR returns the old comparison function or \fB\s-1NULL\s0\fR if
there was no old comparison function.
.PP
\&\fIsk_TYPE_free()\fR, \fIsk_TYPE_zero()\fR, \fIsk_TYPE_pop_free()\fR and \fIsk_TYPE_sort()\fR do
not return values.
.PP
\&\fIsk_TYPE_pop()\fR, \fIsk_TYPE_shift()\fR, \fIsk_TYPE_delete()\fR and \fIsk_TYPE_delete_ptr()\fR
return a pointer to the deleted element or \fB\s-1NULL\s0\fR on error.
.PP
\&\fIsk_TYPE_insert()\fR, \fIsk_TYPE_push()\fR and \fIsk_TYPE_unshift()\fR return the total
number of elements in the stack and 0 if an error occurred.
.PP
\&\fIsk_TYPE_set()\fR returns a pointer to the replacement element or \fB\s-1NULL\s0\fR on
error.
.PP
\&\fIsk_TYPE_find()\fR and \fIsk_TYPE_find_ex()\fR return an index to the found element
or \fB\-1\fR on error.
.PP
\&\fIsk_TYPE_is_sorted()\fR returns \fB1\fR if the stack is sorted and \fB0\fR if it is
not.
.PP
\&\fIsk_TYPE_dup()\fR and \fIsk_TYPE_deep_copy()\fR return a pointer to the copy of the
stack.
.SH "HISTORY"
.IX Header "HISTORY"
Before OpenSSL 1.1.0, this was implemented via macros and not inline functions
and was not a public \s-1API.\s0
.PP
\&\fIsk_TYPE_reserve()\fR and \fIsk_TYPE_new_reserve()\fR were added in OpenSSL 1.1.1.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2017 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

240
secure/lib/libcrypto/man/des.3 → secure/lib/libcrypto/man/DES_random_key.3
View file

@ -128,22 +128,14 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "des 3"
.TH des 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "DES_RANDOM_KEY 3"
.TH DES_RANDOM_KEY 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "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_cbcm_encrypt, DES_ede3_cfb64_encrypt, DES_ede3_ofb64_encrypt,
DES_cbc_cksum, DES_quad_cksum, DES_string_to_key, DES_string_to_2keys,
DES_fcrypt, DES_crypt, DES_enc_read, DES_enc_write \- DES encryption
DES_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
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
@ -153,87 +145,77 @@ DES_fcrypt, DES_crypt, DES_enc_read, DES_enc_write \- DES encryption
\&
\& 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);
\& 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_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_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);
\& 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);
\& 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);
\& 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);
\& 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_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_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_cbcm_encrypt(const unsigned char *in, unsigned char *out,
\& long length, DES_key_schedule *ks1, DES_key_schedule *ks2,
\& DES_key_schedule *ks3, DES_cblock *ivec1, DES_cblock *ivec2,
\& int enc);
\& void DES_ede3_cfb64_encrypt(const unsigned char *in, unsigned char *out,
\& 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);
\& 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);
\& 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);
\& 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);
\&
\& int DES_enc_read(int fd, void *buf, int len, DES_key_schedule *sched,
\& DES_cblock *iv);
\& int DES_enc_write(int fd, const void *buf, int len,
\& DES_key_schedule *sched, DES_cblock *iv);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
@ -248,7 +230,7 @@ each byte is the parity bit. The key schedule is an expanded form of
the key; it is used to speed the encryption process.
.PP
\&\fIDES_random_key()\fR generates a random key. The \s-1PRNG\s0 must be seeded
prior to using this function (see \fIrand\fR\|(3)). If the \s-1PRNG\s0
prior to using this function (see \fIRAND_bytes\fR\|(3)). If the \s-1PRNG\s0
could not generate a secure key, 0 is returned.
.PP
Before a \s-1DES\s0 key can be used, it must be converted into the
@ -382,8 +364,12 @@ is thread safe, unlike the normal crypt.
.PP
\&\fIDES_crypt()\fR is a faster replacement for the normal system \fIcrypt()\fR.
This function calls \fIDES_fcrypt()\fR with a static array passed as the
third parameter. This emulates the normal non-thread safe semantics
third parameter. This mostly emulates the normal non-thread-safe semantics
of \fIcrypt\fR\|(3).
The \fBsalt\fR must be two \s-1ASCII\s0 characters.
.PP
The values returned by \fIDES_fcrypt()\fR and \fIDES_crypt()\fR are terminated by \s-1NUL\s0
character.
.PP
\&\fIDES_enc_write()\fR writes \fIlen\fR bytes to file descriptor \fIfd\fR from
buffer \fIbuf\fR. The data is encrypted via \fIpcbc_encrypt\fR (default)
@ -392,35 +378,8 @@ data send down \fIfd\fR 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.
.PP
\&\fIDES_enc_read()\fR is used to read \fIlen\fR bytes from file descriptor
\&\fIfd\fR into buffer \fIbuf\fR. The data being read from \fIfd\fR is assumed to
have come from \fIDES_enc_write()\fR and is decrypted using \fIsched\fR for
the key schedule and \fIiv\fR for the initial vector.
.PP
\&\fBWarning:\fR The data format used by \fIDES_enc_write()\fR and \fIDES_enc_read()\fR
has a cryptographic weakness: When asked to write more than \s-1MAXWRITE\s0
bytes, \fIDES_enc_write()\fR will split the data into several chunks that
are all encrypted using the same \s-1IV.\s0 So don't use these functions
unless you are sure you know what you do (in which case you might not
want to use them anyway). They cannot handle non-blocking sockets.
\&\fIDES_enc_read()\fR uses an internal state and thus cannot be used on
multiple files.
.PP
\&\fIDES_rw_mode\fR is used to specify the encryption mode to use with
\&\fIDES_enc_read()\fR and \fIDES_end_write()\fR. If set to \fI\s-1DES_PCBC_MODE\s0\fR (the
default), DES_pcbc_encrypt is used. If set to \fI\s-1DES_CBC_MODE\s0\fR
DES_cbc_encrypt is used.
.SH "NOTES"
.IX Header "NOTES"
Single-key \s-1DES\s0 is insecure due to its short key size. \s-1ECB\s0 mode is
not suitable for most applications; see \fIdes_modes\fR\|(7).
.PP
The \fIevp\fR\|(3) library provides higher-level encryption functions.
.SH "BUGS"
.IX Header "BUGS"
\&\fIDES_3cbc_encrypt()\fR is flawed and must not be used in applications.
.PP
\&\fIDES_cbc_encrypt()\fR does not modify \fBivec\fR; use \fIDES_ncbc_encrypt()\fR
instead.
.PP
@ -437,46 +396,43 @@ get ugly!
\&\fIDES_string_to_key()\fR is available for backward compatibility with the
\&\s-1MIT\s0 library. New applications should use a cryptographic hash function.
The same applies for \fIDES_string_to_2key()\fR.
.SH "CONFORMING TO"
.IX Header "CONFORMING TO"
\&\s-1ANSI X3.106\s0
.PP
.SH "NOTES"
.IX Header "NOTES"
The \fBdes\fR library was written to be source code compatible with
the \s-1MIT\s0 Kerberos library.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIcrypt\fR\|(3), \fIdes_modes\fR\|(7), \fIevp\fR\|(3), \fIrand\fR\|(3)
.PP
Applications should use the higher level functions
\&\fIEVP_EncryptInit\fR\|(3) etc. instead of calling these
functions directly.
.PP
Single-key \s-1DES\s0 is insecure due to its short key size. \s-1ECB\s0 mode is
not suitable for most applications; see \fIdes_modes\fR\|(7).
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fIDES_set_key()\fR, \fIDES_key_sched()\fR, \fIDES_set_key_checked()\fR and \fIDES_is_weak_key()\fR
return 0 on success or negative values on error.
.PP
\&\fIDES_cbc_cksum()\fR and \fIDES_quad_cksum()\fR return 4\-byte integer representing the
last 4 bytes of the checksum of the input.
.PP
\&\fIDES_fcrypt()\fR returns a pointer to the caller-provided buffer and \fIDES_crypt()\fR \-
to a static buffer on success; otherwise they return \s-1NULL.\s0
.SH "HISTORY"
.IX Header "HISTORY"
In OpenSSL 0.9.7, all des_ functions were renamed to \s-1DES_\s0 to avoid
clashes with older versions of libdes. Compatibility des_ functions
are provided for a short while, as well as \fIcrypt()\fR.
Declarations for these are in <openssl/des_old.h>. There is no \s-1DES_\s0
variant for \fIdes_random_seed()\fR.
This will happen to other functions
as well if they are deemed redundant (\fIdes_random_seed()\fR just calls
\&\fIRAND_seed()\fR and is present for backward compatibility only), buggy or
already scheduled for removal.
The requirement that the \fBsalt\fR parameter to \fIDES_crypt()\fR and \fIDES_fcrypt()\fR
be two \s-1ASCII\s0 characters was first enforced in
OpenSSL 1.1.0. Previous versions tried to use the letter uppercase \fBA\fR
if both character were not present, and could crash when given non-ASCII
on some platforms.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIdes_modes\fR\|(7),
\&\fIEVP_EncryptInit\fR\|(3)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved.
.PP
\&\fIdes_cbc_cksum()\fR, \fIdes_cbc_encrypt()\fR, \fIdes_ecb_encrypt()\fR,
\&\fIdes_is_weak_key()\fR, \fIdes_key_sched()\fR, \fIdes_pcbc_encrypt()\fR,
\&\fIdes_quad_cksum()\fR, \fIdes_random_key()\fR and \fIdes_string_to_key()\fR
are available in the \s-1MIT\s0 Kerberos library;
\&\fIdes_check_key_parity()\fR, \fIdes_fixup_key_parity()\fR and \fIdes_is_weak_key()\fR
are available in newer versions of that library.
.PP
\&\fIdes_set_key_checked()\fR and \fIdes_set_key_unchecked()\fR were added in
OpenSSL 0.9.5.
.PP
\&\fIdes_generate_random_block()\fR, \fIdes_init_random_number_generator()\fR,
\&\fIdes_new_random_key()\fR, \fIdes_set_random_generator_seed()\fR and
\&\fIdes_set_sequence_number()\fR and \fIdes_rand_data()\fR are used in newer
versions of Kerberos but are not implemented here.
.PP
\&\fIdes_random_key()\fR generated cryptographically weak random data in
SSLeay and in OpenSSL prior version 0.9.5, as well as in the original
\&\s-1MIT\s0 library.
.SH "AUTHOR"
.IX Header "AUTHOR"
Eric Young (eay@cryptsoft.com). Modified for the OpenSSL project
(http://www.openssl.org).
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

18
secure/lib/libcrypto/man/DH_generate_key.3
View file

@ -128,8 +128,8 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "DH_generate_key 3"
.TH DH_generate_key 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "DH_GENERATE_KEY 3"
.TH DH_GENERATE_KEY 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
@ -171,8 +171,12 @@ on error.
The error codes can be obtained by \fIERR_get_error\fR\|(3).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIdh\fR\|(3), \fIERR_get_error\fR\|(3), \fIrand\fR\|(3), \fIDH_size\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fIDH_generate_key()\fR and \fIDH_compute_key()\fR are available in all versions
of SSLeay and OpenSSL.
\&\fIDH_new\fR\|(3), \fIERR_get_error\fR\|(3), \fIRAND_bytes\fR\|(3), \fIDH_size\fR\|(3)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

120
secure/lib/libcrypto/man/DH_generate_parameters.3
View file

@ -128,37 +128,45 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "DH_generate_parameters 3"
.TH DH_generate_parameters 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "DH_GENERATE_PARAMETERS 3"
.TH DH_GENERATE_PARAMETERS 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
DH_generate_parameters_ex, DH_generate_parameters,
DH_check \- generate and check Diffie\-Hellman parameters
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
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/dh.h>
\&
\& int DH_generate_parameters_ex(DH *dh, int prime_len,int generator, BN_GENCB *cb);
\& int DH_generate_parameters_ex(DH *dh, int prime_len, int generator, BN_GENCB *cb);
\&
\& int DH_check(DH *dh, int *codes);
\& int DH_check_params(DH *dh, int *codes);
\&
\& 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);
.Ve
.PP
Deprecated:
.PP
.Vb 2
.Vb 4
\& #if OPENSSL_API_COMPAT < 0x00908000L
\& DH *DH_generate_parameters(int prime_len, int generator,
\& void (*callback)(int, int, void *), void *cb_arg);
\& void (*callback)(int, int, void *), void *cb_arg);
\& #endif
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fIDH_generate_parameters_ex()\fR generates Diffie-Hellman parameters that can
be shared among a group of users, and stores them in the provided \fB\s-1DH\s0\fR
structure. The pseudo-random number generator must be
seeded prior to calling \fIDH_generate_parameters()\fR.
seeded before calling it.
The parameters generated by \fIDH_generate_parameters_ex()\fR should not be used in
signature schemes.
.PP
\&\fBprime_len\fR is the length in bits of the safe prime to be generated.
\&\fBgenerator\fR is a small number > 1, typically 2 or 5.
@ -167,43 +175,85 @@ A callback function may be used to provide feedback about the progress
of the key generation. If \fBcb\fR is not \fB\s-1NULL\s0\fR, it will be
called as described in \fIBN_generate_prime\fR\|(3) while a random prime
number is generated, and when a prime has been found, \fBBN_GENCB_call(cb, 3, 0)\fR
is called. See \fIBN_generate_prime\fR\|(3) for information on
is called. See \fIBN_generate_prime_ex\fR\|(3) for information on
the \fIBN_GENCB_call()\fR function.
.PP
\&\fIDH_check()\fR validates Diffie-Hellman parameters. It checks that \fBp\fR is
a safe prime, and that \fBg\fR is a suitable generator. In the case of an
error, the bit flags \s-1DH_CHECK_P_NOT_SAFE_PRIME\s0 or
\&\s-1DH_NOT_SUITABLE_GENERATOR\s0 are set in \fB*codes\fR.
\&\s-1DH_UNABLE_TO_CHECK_GENERATOR\s0 is set if the generator cannot be
checked, i.e. it does not equal 2 or 5.
\&\fIDH_generate_parameters()\fR is similar to \fIDH_generate_prime_ex()\fR but
expects an old-style callback function; see
\&\fIBN_generate_prime\fR\|(3) for information on the old-style callback.
.PP
\&\fIDH_check_params()\fR confirms that the \fBp\fR and \fBg\fR are likely enough to
be valid.
This is a lightweight check, if a more thorough check is needed, use
\&\fIDH_check()\fR.
The value of \fB*codes\fR is updated with any problems found.
If \fB*codes\fR is zero then no problems were found, otherwise the
following bits may be set:
.IP "\s-1DH_CHECK_P_NOT_PRIME\s0" 4
.IX Item "DH_CHECK_P_NOT_PRIME"
The parameter \fBp\fR has been determined to not being an odd prime.
Note that the lack of this bit doesn't guarantee that \fBp\fR is a
prime.
.IP "\s-1DH_NOT_SUITABLE_GENERATOR\s0" 4
.IX Item "DH_NOT_SUITABLE_GENERATOR"
The generator \fBg\fR is not suitable.
Note that the lack of this bit doesn't guarantee that \fBg\fR is
suitable, unless \fBp\fR is known to be a strong prime.
.PP
\&\fIDH_check()\fR confirms that the Diffie-Hellman parameters \fBdh\fR are valid. The
value of \fB*codes\fR is updated with any problems found. If \fB*codes\fR is zero then
no problems were found, otherwise the following bits may be set:
.IP "\s-1DH_CHECK_P_NOT_PRIME\s0" 4
.IX Item "DH_CHECK_P_NOT_PRIME"
The parameter \fBp\fR is not prime.
.IP "\s-1DH_CHECK_P_NOT_SAFE_PRIME\s0" 4
.IX Item "DH_CHECK_P_NOT_SAFE_PRIME"
The parameter \fBp\fR is not a safe prime and no \fBq\fR value is present.
.IP "\s-1DH_UNABLE_TO_CHECK_GENERATOR\s0" 4
.IX Item "DH_UNABLE_TO_CHECK_GENERATOR"
The generator \fBg\fR cannot be checked for suitability.
.IP "\s-1DH_NOT_SUITABLE_GENERATOR\s0" 4
.IX Item "DH_NOT_SUITABLE_GENERATOR"
The generator \fBg\fR is not suitable.
.IP "\s-1DH_CHECK_Q_NOT_PRIME\s0" 4
.IX Item "DH_CHECK_Q_NOT_PRIME"
The parameter \fBq\fR is not prime.
.IP "\s-1DH_CHECK_INVALID_Q_VALUE\s0" 4
.IX Item "DH_CHECK_INVALID_Q_VALUE"
The parameter \fBq\fR is invalid.
.IP "\s-1DH_CHECK_INVALID_J_VALUE\s0" 4
.IX Item "DH_CHECK_INVALID_J_VALUE"
The parameter \fBj\fR is invalid.
.PP
\&\fIDH_check_ex()\fR, \fIDH_check_params()\fR and \fIDH_check_pub_key_ex()\fR are similar to
\&\fIDH_check()\fR and \fIDH_check_params()\fR respectively, but the error reasons are added
to the thread's error queue instead of provided as return values from the
function.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fIDH_generate_parameters_ex()\fR and \fIDH_check()\fR return 1 if the check could be
performed, 0 otherwise.
\&\fIDH_generate_parameters_ex()\fR, \fIDH_check()\fR and \fIDH_check_params()\fR return 1
if the check could be performed, 0 otherwise.
.PP
\&\fIDH_generate_parameters()\fR (deprecated) returns a pointer to the \s-1DH\s0 structure, or
\&\s-1NULL\s0 if the parameter generation fails.
\&\fIDH_generate_parameters()\fR returns a pointer to the \s-1DH\s0 structure or \s-1NULL\s0 if
the parameter generation fails.
.PP
\&\fIDH_check_ex()\fR, \fIDH_check_params()\fR and \fIDH_check_pub_key_ex()\fR return 1 if the
check is successful, 0 for failed.
.PP
The error codes can be obtained by \fIERR_get_error\fR\|(3).
.SH "NOTES"
.IX Header "NOTES"
\&\fIDH_generate_parameters_ex()\fR and \fIDH_generate_parameters()\fR may run for several
hours before finding a suitable prime.
.PP
The parameters generated by \fIDH_generate_parameters_ex()\fR and \fIDH_generate_parameters()\fR
are not to be used in signature schemes.
.SH "BUGS"
.IX Header "BUGS"
If \fBgenerator\fR is not 2 or 5, \fBdh\->g\fR=\fBgenerator\fR is not
a usable generator.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIdh\fR\|(3), \fIERR_get_error\fR\|(3), \fIrand\fR\|(3),
\&\fIDH_new\fR\|(3), \fIERR_get_error\fR\|(3), \fIRAND_bytes\fR\|(3),
\&\fIDH_free\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fIDH_check()\fR is available in all versions of SSLeay and OpenSSL.
The \fBcb_arg\fR argument to \fIDH_generate_parameters()\fR was added in SSLeay 0.9.0.
\&\fIDH_generate_parameters()\fR was deprecated in OpenSSL 0.9.8; use
\&\fIDH_generate_parameters_ex()\fR instead.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved.
.PP
In versions before OpenSSL 0.9.5, \s-1DH_CHECK_P_NOT_STRONG_PRIME\s0 is used
instead of \s-1DH_CHECK_P_NOT_SAFE_PRIME.\s0
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

250
secure/lib/libcrypto/man/DH_get0_pqg.3 Normal file
View file

@ -0,0 +1,250 @@
.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "DH_GET0_PQG 3"
.TH DH_GET0_PQG 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "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
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
A \s-1DH\s0 object contains the parameters \fBp\fR, \fBq\fR and \fBg\fR. Note that the \fBq\fR
parameter is optional. It also contains a public key (\fBpub_key\fR) and
(optionally) a private key (\fBpriv_key\fR).
.PP
The \fBp\fR, \fBq\fR and \fBg\fR parameters can be obtained by calling \fIDH_get0_pqg()\fR.
If the parameters have not yet been set then \fB*p\fR, \fB*q\fR and \fB*g\fR will be set
to \s-1NULL.\s0 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 \fBp\fR, \fBq\fR, and \fBg\fR can be \s-1NULL,\s0 in which case no
value will be returned for that parameter.
.PP
The \fBp\fR, \fBq\fR and \fBg\fR values can be set by calling \fIDH_set0_pqg()\fR and passing
the new values for \fBp\fR, \fBq\fR and \fBg\fR as parameters to the function. Calling
this function transfers the memory management of the values to the \s-1DH\s0 object,
and therefore the values that have been passed in should not be freed directly
after this function has been called. The \fBq\fR parameter may be \s-1NULL.\s0
.PP
To get the public and private key values use the \fIDH_get0_key()\fR function. A
pointer to the public key will be stored in \fB*pub_key\fR, and a pointer to the
private key will be stored in \fB*priv_key\fR. Either may be \s-1NULL\s0 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 \fBpub_key\fR and \fBpriv_key\fR can be \s-1NULL,\s0 in which case
no value will be returned for that parameter.
.PP
The public and private key values can be set using \fIDH_set0_key()\fR. Either
parameter may be \s-1NULL,\s0 which means the corresponding \s-1DH\s0 field is left
untouched. As with \fIDH_set0_pqg()\fR this function transfers the memory management
of the key values to the \s-1DH\s0 object, and therefore they should not be freed
directly after this function has been called.
.PP
Any of the values \fBp\fR, \fBq\fR, \fBg\fR, \fBpriv_key\fR, and \fBpub_key\fR can also be
retrieved separately by the corresponding function \fIDH_get0_p()\fR, \fIDH_get0_q()\fR,
\&\fIDH_get0_g()\fR, \fIDH_get0_priv_key()\fR, and \fIDH_get0_pub_key()\fR, respectively.
.PP
\&\fIDH_set_flags()\fR sets the flags in the \fBflags\fR parameter on the \s-1DH\s0 object.
Multiple flags can be passed in one go (bitwise ORed together). Any flags that
are already set are left set. \fIDH_test_flags()\fR tests to see whether the flags
passed in the \fBflags\fR parameter are currently set in the \s-1DH\s0 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. \fIDH_clear_flags()\fR clears the specified flags
within the \s-1DH\s0 object.
.PP
\&\fIDH_get0_engine()\fR returns a handle to the \s-1ENGINE\s0 that has been set for this \s-1DH\s0
object, or \s-1NULL\s0 if no such \s-1ENGINE\s0 has been set.
.PP
The \fIDH_get_length()\fR and \fIDH_set_length()\fR functions get and set the optional
length parameter associated with this \s-1DH\s0 object. If the length is non-zero then
it is used, otherwise it is ignored. The \fBlength\fR parameter indicates the
length of the secret exponent (private key) in bits.
.SH "NOTES"
.IX Header "NOTES"
Values retrieved with \fIDH_get0_key()\fR are owned by the \s-1DH\s0 object used
in the call and may therefore \fInot\fR be passed to \fIDH_set0_key()\fR. If
needed, duplicate the received value using \fIBN_dup()\fR and pass the
duplicate. The same applies to \fIDH_get0_pqg()\fR and \fIDH_set0_pqg()\fR.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fIDH_set0_pqg()\fR and \fIDH_set0_key()\fR return 1 on success or 0 on failure.
.PP
\&\fIDH_get0_p()\fR, \fIDH_get0_q()\fR, \fIDH_get0_g()\fR, \fIDH_get0_priv_key()\fR, and \fIDH_get0_pub_key()\fR
return the respective value, or \s-1NULL\s0 if it is unset.
.PP
\&\fIDH_test_flags()\fR returns the current state of the flags in the \s-1DH\s0 object.
.PP
\&\fIDH_get0_engine()\fR returns the \s-1ENGINE\s0 set for the \s-1DH\s0 object or \s-1NULL\s0 if no \s-1ENGINE\s0
has been set.
.PP
\&\fIDH_get_length()\fR returns the length of the secret exponent (private key) in bits,
or zero if no such length has been explicitly set.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIDH_new\fR\|(3), \fIDH_new\fR\|(3), \fIDH_generate_parameters\fR\|(3), \fIDH_generate_key\fR\|(3),
\&\fIDH_set_method\fR\|(3), \fIDH_size\fR\|(3), \fIDH_meth_new\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
The functions described here were added in OpenSSL 1.1.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2016\-2018 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

187
secure/lib/libcrypto/man/DH_get_1024_160.3 Normal file
View file

@ -0,0 +1,187 @@
.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "DH_GET_1024_160 3"
.TH DH_GET_1024_160 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "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
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 4
\& #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)
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fIDH_get_1024_160()\fR, \fIDH_get_2048_224()\fR, and \fIDH_get_2048_256()\fR each return
a \s-1DH\s0 object for the \s-1IETF RFC 5114\s0 value.
.PP
\&\fIBN_get0_nist_prime_192()\fR, \fIBN_get0_nist_prime_224()\fR, \fIBN_get0_nist_prime_256()\fR,
\&\fIBN_get0_nist_prime_384()\fR, and \fIBN_get0_nist_prime_521()\fR functions return
a \s-1BIGNUM\s0 for the specific \s-1NIST\s0 prime curve (e.g., P\-256).
.PP
\&\fIBN_get_rfc2409_prime_768()\fR, \fIBN_get_rfc2409_prime_1024()\fR,
\&\fIBN_get_rfc3526_prime_1536()\fR, \fIBN_get_rfc3526_prime_2048()\fR,
\&\fIBN_get_rfc3526_prime_3072()\fR, \fIBN_get_rfc3526_prime_4096()\fR,
\&\fIBN_get_rfc3526_prime_6144()\fR, and \fIBN_get_rfc3526_prime_8192()\fR functions
return a \s-1BIGNUM\s0 for the specified size from \s-1IETF RFC 2409.\s0 If \fBbn\fR
is not \s-1NULL,\s0 the \s-1BIGNUM\s0 will be set into that location as well.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
Defined above.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

290
secure/lib/libcrypto/man/DH_meth_new.3 Normal file
View file

@ -0,0 +1,290 @@
.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "DH_METH_NEW 3"
.TH DH_METH_NEW 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "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
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #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 *));
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \fB\s-1DH_METHOD\s0\fR type is a structure used for the provision of custom \s-1DH\s0
implementations. It provides a set of functions used by OpenSSL for the
implementation of the various \s-1DH\s0 capabilities.
.PP
\&\fIDH_meth_new()\fR creates a new \fB\s-1DH_METHOD\s0\fR structure. It should be given a
unique \fBname\fR and a set of \fBflags\fR. The \fBname\fR should be a \s-1NULL\s0 terminated
string, which will be duplicated and stored in the \fB\s-1DH_METHOD\s0\fR object. It is
the callers responsibility to free the original string. The flags will be used
during the construction of a new \fB\s-1DH\s0\fR object based on this \fB\s-1DH_METHOD\s0\fR. Any
new \fB\s-1DH\s0\fR object will have those flags set by default.
.PP
\&\fIDH_meth_dup()\fR creates a duplicate copy of the \fB\s-1DH_METHOD\s0\fR object passed as a
parameter. This might be useful for creating a new \fB\s-1DH_METHOD\s0\fR based on an
existing one, but with some differences.
.PP
\&\fIDH_meth_free()\fR destroys a \fB\s-1DH_METHOD\s0\fR structure and frees up any memory
associated with it.
.PP
\&\fIDH_meth_get0_name()\fR will return a pointer to the name of this \s-1DH_METHOD.\s0 This
is a pointer to the internal name string and so should not be freed by the
caller. \fIDH_meth_set1_name()\fR sets the name of the \s-1DH_METHOD\s0 to \fBname\fR. The
string is duplicated and the copy is stored in the \s-1DH_METHOD\s0 structure, so the
caller remains responsible for freeing the memory associated with the name.
.PP
\&\fIDH_meth_get_flags()\fR returns the current value of the flags associated with this
\&\s-1DH_METHOD.\s0 \fIDH_meth_set_flags()\fR provides the ability to set these flags.
.PP
The functions \fIDH_meth_get0_app_data()\fR and \fIDH_meth_set0_app_data()\fR provide the
ability to associate implementation specific data with the \s-1DH_METHOD.\s0 It is
the application's responsibility to free this data before the \s-1DH_METHOD\s0 is
freed via a call to \fIDH_meth_free()\fR.
.PP
\&\fIDH_meth_get_generate_key()\fR and \fIDH_meth_set_generate_key()\fR get and set the
function used for generating a new \s-1DH\s0 key pair respectively. This function will
be called in response to the application calling \fIDH_generate_key()\fR. The
parameter for the function has the same meaning as for \fIDH_generate_key()\fR.
.PP
\&\fIDH_meth_get_compute_key()\fR and \fIDH_meth_set_compute_key()\fR get and set the
function used for computing a new \s-1DH\s0 shared secret respectively. This function
will be called in response to the application calling \fIDH_compute_key()\fR. The
parameters for the function have the same meaning as for \fIDH_compute_key()\fR.
.PP
\&\fIDH_meth_get_bn_mod_exp()\fR and \fIDH_meth_set_bn_mod_exp()\fR get and set the function
used for computing the following value:
.PP
.Vb 1
\& r = a ^ p mod m
.Ve
.PP
This function will be called by the default OpenSSL function for
\&\fIDH_generate_key()\fR. The result is stored in the \fBr\fR parameter. This function
may be \s-1NULL\s0 unless using the default generate key function, in which case it
must be present.
.PP
\&\fIDH_meth_get_init()\fR and \fIDH_meth_set_init()\fR get and set the function used
for creating a new \s-1DH\s0 instance respectively. This function will be
called in response to the application calling \fIDH_new()\fR (if the current default
\&\s-1DH_METHOD\s0 is this one) or \fIDH_new_method()\fR. The \fIDH_new()\fR and \fIDH_new_method()\fR
functions will allocate the memory for the new \s-1DH\s0 object, and a pointer to this
newly allocated structure will be passed as a parameter to the function. This
function may be \s-1NULL.\s0
.PP
\&\fIDH_meth_get_finish()\fR and \fIDH_meth_set_finish()\fR get and set the function used
for destroying an instance of a \s-1DH\s0 object respectively. This function will be
called in response to the application calling \fIDH_free()\fR. A pointer to the \s-1DH\s0
to be destroyed is passed as a parameter. The destroy function should be used
for \s-1DH\s0 implementation specific clean up. The memory for the \s-1DH\s0 itself should
not be freed by this function. This function may be \s-1NULL.\s0
.PP
\&\fIDH_meth_get_generate_params()\fR and \fIDH_meth_set_generate_params()\fR get and set the
function used for generating \s-1DH\s0 parameters respectively. This function will be
called in response to the application calling \fIDH_generate_parameters_ex()\fR (or
\&\fIDH_generate_parameters()\fR). The parameters for the function have the same
meaning as for \fIDH_generate_parameters_ex()\fR. This function may be \s-1NULL.\s0
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fIDH_meth_new()\fR and \fIDH_meth_dup()\fR return the newly allocated \s-1DH_METHOD\s0 object
or \s-1NULL\s0 on failure.
.PP
\&\fIDH_meth_get0_name()\fR and \fIDH_meth_get_flags()\fR return the name and flags
associated with the \s-1DH_METHOD\s0 respectively.
.PP
All other DH_meth_get_*() functions return the appropriate function pointer
that has been set in the \s-1DH_METHOD,\s0 or \s-1NULL\s0 if no such pointer has yet been
set.
.PP
\&\fIDH_meth_set1_name()\fR and all DH_meth_set_*() functions return 1 on success or
0 on failure.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIDH_new\fR\|(3), \fIDH_new\fR\|(3), \fIDH_generate_parameters\fR\|(3), \fIDH_generate_key\fR\|(3),
\&\fIDH_set_method\fR\|(3), \fIDH_size\fR\|(3), \fIDH_get0_pqg\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
The functions described here were added in OpenSSL 1.1.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2016\-2018 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

18
secure/lib/libcrypto/man/DH_new.3
View file

@ -128,8 +128,8 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "DH_new 3"
.TH DH_new 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "DH_NEW 3"
.TH DH_NEW 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
@ -151,6 +151,7 @@ DH_new, DH_free \- allocate and free DH objects
.PP
\&\fIDH_free()\fR frees the \fB\s-1DH\s0\fR structure and its components. The values are
erased before the memory is returned to the system.
If \fBdh\fR is \s-1NULL\s0 nothing is done.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
If the allocation fails, \fIDH_new()\fR returns \fB\s-1NULL\s0\fR and sets an error
@ -160,9 +161,14 @@ a pointer to the newly allocated structure.
\&\fIDH_free()\fR returns no value.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIdh\fR\|(3), \fIERR_get_error\fR\|(3),
\&\fIDH_new\fR\|(3), \fIERR_get_error\fR\|(3),
\&\fIDH_generate_parameters\fR\|(3),
\&\fIDH_generate_key\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fIDH_new()\fR and \fIDH_free()\fR are available in all versions of SSLeay and OpenSSL.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

168
secure/lib/libcrypto/man/DH_new_by_nid.3 Normal file
View file

@ -0,0 +1,168 @@
.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "DH_NEW_BY_NID 3"
.TH DH_NEW_BY_NID 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
DH_new_by_nid, DH_get_nid \- get or find DH named parameters
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\& #include <openssl/dh.h>
\& DH *DH_new_by_nid(int nid);
\& int *DH_get_nid(const DH *dh);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fIDH_new_by_nid()\fR creates and returns a \s-1DH\s0 structure containing named parameters
\&\fBnid\fR. Currently \fBnid\fR must be \fBNID_ffdhe2048\fR, \fBNID_ffdhe3072\fR,
\&\fBNID_ffdhe4096\fR, \fBNID_ffdhe6144\fR or \fBNID_ffdhe8192\fR.
.PP
\&\fIDH_get_nid()\fR determines if the parameters contained in \fBdh\fR match
any named set. It returns the \s-1NID\s0 corresponding to the matching parameters or
\&\fBNID_undef\fR if there is no match.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fIDH_new_by_nid()\fR returns a set of \s-1DH\s0 parameters or \fB\s-1NULL\s0\fR if an error occurred.
.PP
\&\fIDH_get_nid()\fR returns the \s-1NID\s0 of the matching set of parameters or
\&\fBNID_undef\fR if there is no match.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

80
secure/lib/libcrypto/man/DH_set_method.3
View file

@ -128,20 +128,18 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "DH_set_method 3"
.TH DH_set_method 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "DH_SET_METHOD 3"
.TH DH_SET_METHOD 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
DH_set_default_method, DH_get_default_method,
DH_set_method, DH_new_method, DH_OpenSSL \- select DH method
DH_set_default_method, DH_get_default_method, DH_set_method, DH_new_method, DH_OpenSSL \- select DH method
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
.Vb 1
\& #include <openssl/dh.h>
\& #include <openssl/engine.h>
\&
\& void DH_set_default_method(const DH_METHOD *meth);
\&
@ -165,8 +163,11 @@ Initially, the default \s-1DH_METHOD\s0 is the OpenSSL internal implementation,
returned by \fIDH_OpenSSL()\fR.
.PP
\&\fIDH_set_default_method()\fR makes \fBmeth\fR the default method for all \s-1DH\s0
structures created later. \fB\s-1NB\s0\fR: This is true only whilst no \s-1ENGINE\s0 has been set
structures created later.
\&\fB\s-1NB\s0\fR: This is true only whilst no \s-1ENGINE\s0 has been set
as a default for \s-1DH,\s0 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.
.PP
\&\fIDH_get_default_method()\fR returns a pointer to the current default \s-1DH_METHOD.\s0
However, the meaningfulness of this result is dependent on whether the \s-1ENGINE
@ -184,37 +185,9 @@ for the key can have unexpected results.
be used for the \s-1DH\s0 operations. If \fBengine\fR is \s-1NULL,\s0 the default \s-1ENGINE\s0 for \s-1DH\s0
operations is used, and if no default \s-1ENGINE\s0 is set, the \s-1DH_METHOD\s0 controlled by
\&\fIDH_set_default_method()\fR is used.
.SH "THE DH_METHOD STRUCTURE"
.IX Header "THE DH_METHOD STRUCTURE"
.Vb 4
\& typedef struct dh_meth_st
\& {
\& /* name of the implementation */
\& const char *name;
\&
\& /* generate private and public DH values for key agreement */
\& int (*generate_key)(DH *dh);
\&
\& /* compute shared secret */
\& int (*compute_key)(unsigned char *key, BIGNUM *pub_key, DH *dh);
\&
\& /* compute r = a ^ p mod m (May be NULL for some implementations) */
\& int (*bn_mod_exp)(DH *dh, BIGNUM *r, BIGNUM *a, const BIGNUM *p,
\& const BIGNUM *m, BN_CTX *ctx,
\& BN_MONT_CTX *m_ctx);
\&
\& /* called at DH_new */
\& int (*init)(DH *dh);
\&
\& /* called at DH_free */
\& int (*finish)(DH *dh);
\&
\& int flags;
\&
\& char *app_data; /* ?? */
\&
\& } DH_METHOD;
.Ve
.PP
A new \s-1DH_METHOD\s0 object may be constructed using \fIDH_meth_new()\fR (see
\&\fIDH_meth_new\fR\|(3)).
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fIDH_OpenSSL()\fR and \fIDH_get_default_method()\fR return pointers to the respective
@ -229,29 +202,14 @@ method was supplied by an \s-1ENGINE\s0).
\&\fIDH_new_method()\fR returns \s-1NULL\s0 and sets an error code that can be obtained by
\&\fIERR_get_error\fR\|(3) if the allocation fails. Otherwise it
returns a pointer to the newly allocated structure.
.SH "NOTES"
.IX Header "NOTES"
As of version 0.9.7, \s-1DH_METHOD\s0 implementations are grouped together with other
algorithmic APIs (eg. \s-1RSA_METHOD, EVP_CIPHER,\s0 etc) in \fB\s-1ENGINE\s0\fR modules. If a
default \s-1ENGINE\s0 is specified for \s-1DH\s0 functionality using an \s-1ENGINE API\s0 function,
that will override any \s-1DH\s0 defaults set using the \s-1DH API\s0 (ie.
\&\fIDH_set_default_method()\fR). For this reason, the \s-1ENGINE API\s0 is the recommended way
to control default implementations for use in \s-1DH\s0 and other cryptographic
algorithms.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIdh\fR\|(3), \fIDH_new\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fIDH_set_default_method()\fR, \fIDH_get_default_method()\fR, \fIDH_set_method()\fR,
\&\fIDH_new_method()\fR and \fIDH_OpenSSL()\fR were added in OpenSSL 0.9.4.
\&\fIDH_new\fR\|(3), \fIDH_new\fR\|(3), \fIDH_meth_new\fR\|(3)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
\&\fIDH_set_default_openssl_method()\fR and \fIDH_get_default_openssl_method()\fR replaced
\&\fIDH_set_default_method()\fR and \fIDH_get_default_method()\fR respectively, and
\&\fIDH_set_method()\fR and \fIDH_new_method()\fR were altered to use \fB\s-1ENGINE\s0\fRs rather than
\&\fB\s-1DH_METHOD\s0\fRs during development of the engine version of OpenSSL 0.9.6. For
0.9.7, the handling of defaults in the \s-1ENGINE API\s0 was restructured so that this
change was reversed, and behaviour of the other functions resembled more closely
the previous behaviour. The behaviour of defaults in the \s-1ENGINE API\s0 now
transparently overrides the behaviour of defaults in the \s-1DH API\s0 without
requiring changing these function prototypes.
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

46
secure/lib/libcrypto/man/DH_size.3
View file

@ -128,34 +128,56 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "DH_size 3"
.TH DH_size 3 "2018-08-14" "1.0.2p" "OpenSSL"
.IX Title "DH_SIZE 3"
.TH DH_SIZE 3 "2018-09-11" "1.1.1" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
DH_size \- get Diffie\-Hellman prime size
DH_size, DH_bits, DH_security_bits \- get Diffie\-Hellman prime size and security bits
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/dh.h>
\&
\& int DH_size(DH *dh);
\& int DH_size(const DH *dh);
\&
\& int DH_bits(const DH *dh);
\&
\& int DH_security_bits(const DH *dh);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This function returns the Diffie-Hellman size in bytes. It can be used
\&\fIDH_size()\fR 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 \fIDH_compute_key()\fR.
computed by \fIDH_compute_key\fR\|(3).
.PP
\&\fBdh\->p\fR must not be \fB\s-1NULL\s0\fR.
.SH "RETURN VALUE"
.IX Header "RETURN VALUE"
The size in bytes.
\&\fIDH_bits()\fR returns the number of significant bits.
.PP
\&\fBdh\fR and \fBdh\->p\fR must not be \fB\s-1NULL\s0\fR.
.PP
\&\fIDH_security_bits()\fR returns the number of security bits of the given \fBdh\fR
key. See \fIBN_security_bits\fR\|(3).
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fIDH_size()\fR returns the prime size of Diffie-Hellman in bytes.
.PP
\&\fIDH_bits()\fR returns the number of bits in the key.
.PP
\&\fIDH_security_bits()\fR returns the number of security bits.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIdh\fR\|(3), \fIDH_generate_key\fR\|(3)
\&\fIDH_new\fR\|(3), \fIDH_generate_key\fR\|(3),
\&\fIBN_num_bits\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fIDH_size()\fR is available in all versions of SSLeay and OpenSSL.
\&\fIDH_bits()\fR was added in OpenSSL 1.1.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.

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