laantungir/nostr_core_lib
1
1
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

.

Browse Source
This commit is contained in:
Laan Tungir
2025-08-14 18:30:16 -04:00
parent 9191d446d3
commit d6a0bd67b2
9309 changed files with 47274 additions and 396945 deletions
Download Patch File Download Diff File Expand all files Collapse all files

311
openssl-3.4.2/doc/man/man3/ADMISSIONS.3
View File

@@ -1,311 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 3ossl"
.TH ADMISSIONS 3ossl "2025-07-01" "3.4.2" "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 \fBd2i_X509\fR\|(3).
The conventional routines to allocate and free the types are defined
in \fBX509_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\fBDEFINE_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 \fBNAMING_AUTHORITY_get0_authorityId()\fR,
\&\fBNAMING_AUTHORITY_get0_get0_authorityURL()\fR, and
\&\fBNAMING_AUTHORITY_get0_get0_authorityText()\fR, functions return pointers
to those values within the object.
The \fBNAMING_AUTHORITY_set0_authorityId()\fR,
\&\fBNAMING_AUTHORITY_set0_get0_authorityURL()\fR, and
\&\fBNAMING_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 \fBADMISSION_SYNTAX_get0_admissionAuthority()\fR
and \fBADMISSION_SYNTAX_get0_contentsOfAdmissions()\fR functions return pointers
to those values within the object.
The
\&\fBADMISSION_SYNTAX_set0_admissionAuthority()\fR and
\&\fBADMISSION_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-1PROFESSION_INFO\s0\fR items.
The \fBADMISSIONS_get0_admissionAuthority()\fR, \fBADMISSIONS_get0_namingAuthority()\fR,
and \fBADMISSIONS_get0_professionInfos()\fR
functions return pointers to those values within the object.
The
\&\fBADMISSIONS_set0_admissionAuthority()\fR,
\&\fBADMISSIONS_set0_namingAuthority()\fR, and
\&\fBADMISSIONS_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 \fBPROFESSION_INFO_get0_addProfessionInfo()\fR,
\&\fBPROFESSION_INFO_get0_namingAuthority()\fR, \fBPROFESSION_INFO_get0_professionItems()\fR,
\&\fBPROFESSION_INFO_get0_professionOIDs()\fR, and
\&\fBPROFESSION_INFO_get0_registrationNumber()\fR
functions return pointers to those values within the object.
The
\&\fBPROFESSION_INFO_set0_addProfessionInfo()\fR,
\&\fBPROFESSION_INFO_set0_namingAuthority()\fR,
\&\fBPROFESSION_INFO_set0_professionItems()\fR,
\&\fBPROFESSION_INFO_set0_professionOIDs()\fR, and
\&\fBPROFESSION_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"
\&\fBX509_dup\fR\|(3),
\&\fBd2i_X509\fR\|(3),
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2017\-2018 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

299
openssl-3.4.2/doc/man/man3/ASN1_EXTERN_FUNCS.3
View File

@@ -1,299 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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_EXTERN_FUNCS 3ossl"
.TH ASN1_EXTERN_FUNCS 3ossl "2025-07-01" "3.4.2" "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_EXTERN_FUNCS, ASN1_ex_d2i, ASN1_ex_d2i_ex, ASN1_ex_i2d, ASN1_ex_new_func,
ASN1_ex_new_ex_func, ASN1_ex_free_func, ASN1_ex_print_func,
IMPLEMENT_EXTERN_ASN1
\&\- ASN.1 external function support
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/asn1t.h>
\&
\& typedef int ASN1_ex_d2i(ASN1_VALUE **pval, const unsigned char **in, long len,
\& const ASN1_ITEM *it, int tag, int aclass, char opt,
\& ASN1_TLC *ctx);
\& typedef int ASN1_ex_d2i_ex(ASN1_VALUE **pval, const unsigned char **in, long len,
\& const ASN1_ITEM *it, int tag, int aclass, char opt,
\& ASN1_TLC *ctx, OSSL_LIB_CTX *libctx,
\& const char *propq);
\& typedef int ASN1_ex_i2d(const ASN1_VALUE **pval, unsigned char **out,
\& const ASN1_ITEM *it, int tag, int aclass);
\& typedef int ASN1_ex_new_func(ASN1_VALUE **pval, const ASN1_ITEM *it);
\& typedef int ASN1_ex_new_ex_func(ASN1_VALUE **pval, const ASN1_ITEM *it,
\& OSSL_LIB_CTX *libctx, const char *propq);
\& typedef void ASN1_ex_free_func(ASN1_VALUE **pval, const ASN1_ITEM *it);
\& typedef int ASN1_ex_print_func(BIO *out, const ASN1_VALUE **pval,
\& int indent, const char *fname,
\& const ASN1_PCTX *pctx);
\&
\& struct ASN1_EXTERN_FUNCS_st {
\& void *app_data;
\& ASN1_ex_new_func *asn1_ex_new;
\& ASN1_ex_free_func *asn1_ex_free;
\& ASN1_ex_free_func *asn1_ex_clear;
\& ASN1_ex_d2i *asn1_ex_d2i;
\& ASN1_ex_i2d *asn1_ex_i2d;
\& ASN1_ex_print_func *asn1_ex_print;
\& ASN1_ex_new_ex_func *asn1_ex_new_ex;
\& ASN1_ex_d2i_ex *asn1_ex_d2i_ex;
\& };
\& typedef struct ASN1_EXTERN_FUNCS_st ASN1_EXTERN_FUNCS;
\&
\& #define IMPLEMENT_EXTERN_ASN1(sname, tag, fptrs)
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\s-1ASN.1\s0 data structures templates are typically defined in OpenSSL using a series
of macros such as \s-1\fBASN1_SEQUENCE\s0()\fR, \s-1\fBASN1_SEQUENCE_END\s0()\fR and so on. Instead
templates can also be defined based entirely on external functions. These
external functions are called to perform operations such as creating a new
\&\fB\s-1ASN1_VALUE\s0\fR or converting an \fB\s-1ASN1_VALUE\s0\fR to or from \s-1DER\s0 encoding.
.PP
The macro \s-1\fBIMPLEMENT_EXTERN_ASN1\s0()\fR can be used to create such an externally
defined structure. The name of the structure should be supplied in the \fIsname\fR
parameter. The tag for the structure (e.g. typically \fBV_ASN1_SEQUENCE\fR) should
be supplied in the \fItag\fR parameter. Finally a pointer to an
\&\fB\s-1ASN1_EXTERN_FUNCS\s0\fR structure should be supplied in the \fIfptrs\fR parameter.
.PP
The \fB\s-1ASN1_EXTERN_FUNCS\s0\fR structure has the following entries.
.IP "\fIapp_data\fR" 4
.IX Item "app_data"
A pointer to arbitrary application specific data.
.IP "\fIasn1_ex_new\fR" 4
.IX Item "asn1_ex_new"
A \*(L"new\*(R" function responsible for constructing a new \fB\s-1ASN1_VALUE\s0\fR object. The
newly constructed value should be stored in \fI*pval\fR. The \fIit\fR parameter is a
pointer to the \fB\s-1ASN1_ITEM\s0\fR template object created via the
\&\s-1\fBIMPLEMENT_EXTERN_ASN1\s0()\fR macro.
.Sp
Returns a positive value on success or 0 on error.
.IP "\fIasn1_ex_free\fR" 4
.IX Item "asn1_ex_free"
A \*(L"free\*(R" function responsible for freeing the \fB\s-1ASN1_VALUE\s0\fR passed in \fI*pval\fR
that was previously allocated via a \*(L"new\*(R" function. The \fIit\fR parameter is a
pointer to the \fB\s-1ASN1_ITEM\s0\fR template object created via the
\&\s-1\fBIMPLEMENT_EXTERN_ASN1\s0()\fR macro.
.IP "\fIasn1_ex_clear\fR" 4
.IX Item "asn1_ex_clear"
A \*(L"clear\*(R" function responsible for clearing any data in the \fB\s-1ASN1_VALUE\s0\fR passed
in \fI*pval\fR and making it suitable for reuse. The \fIit\fR parameter is a pointer
to the \fB\s-1ASN1_ITEM\s0\fR template object created via the \s-1\fBIMPLEMENT_EXTERN_ASN1\s0()\fR
macro.
.IP "\fIasn1_ex_d2i\fR" 4
.IX Item "asn1_ex_d2i"
A \*(L"d2i\*(R" function responsible for converting \s-1DER\s0 data with the tag \fItag\fR and
class \fIclass\fR into an \fB\s-1ASN1_VALUE\s0\fR. If \fI*pval\fR is non-NULL then the
\&\fB\s-1ASN_VALUE\s0\fR it points to should be reused. Otherwise a new \fB\s-1ASN1_VALUE\s0\fR
should be allocated and stored in \fI*pval\fR. \fI*in\fR points to the \s-1DER\s0 data to be
decoded and \fIlen\fR is the length of that data. After decoding \fI*in\fR should be
updated to point at the next byte after the decoded data. If the \fB\s-1ASN1_VALUE\s0\fR
is considered optional in this context then \fIopt\fR will be nonzero. Otherwise
it will be zero. The \fIit\fR parameter is a pointer to the \fB\s-1ASN1_ITEM\s0\fR template
object created via the \s-1\fBIMPLEMENT_EXTERN_ASN1\s0()\fR macro. A pointer to the current
\&\fB\s-1ASN1_TLC\s0\fR context (which may be required for other \s-1ASN1\s0 function calls) is
passed in the \fIctx\fR parameter.
.Sp
The \fIasn1_ex_d2i\fR entry may be \s-1NULL\s0 if \fIasn1_ex_d2i_ex\fR has been specified
instead.
.Sp
Returns <= 0 on error or a positive value on success.
.IP "\fIasn1_ex_i2d\fR" 4
.IX Item "asn1_ex_i2d"
An \*(L"i2d\*(R" function responsible for converting an \fB\s-1ASN1_VALUE\s0\fR into \s-1DER\s0 encoding.
On entry \fI*pval\fR will contain the \fB\s-1ASN1_VALUE\s0\fR to be encoded. If default
tagging is to be used then \fItag\fR will be \-1 on entry. Otherwise if implicit
tagging should be used then \fItag\fR and \fIaclass\fR will be the tag and associated
class.
.Sp
If \fIout\fR is not \s-1NULL\s0 then this function should write the \s-1DER\s0 encoded data to
the buffer in \fI*out\fR, and then increment \fI*out\fR to point to immediately after
the data just written.
.Sp
If \fIout\fR is \s-1NULL\s0 then no data should be written but the length calculated and
returned as if it were.
.Sp
The \fIasn1_ex_i2d\fR entry may be \s-1NULL\s0 if \fIasn1_ex_i2d_ex\fR has been specified
instead.
.Sp
The return value should be negative if a fatal error occurred, or 0 if a
non-fatal error occurred. Otherwise it should return the length of the encoded
data.
.IP "\fIasn1_ex_print\fR" 4
.IX Item "asn1_ex_print"
A \*(L"print\*(R" function. \fIout\fR is the \s-1BIO\s0 to print the output to. \fI*pval\fR is the
\&\fB\s-1ASN1_VALUE\s0\fR to be printed. \fIindent\fR is the number of spaces of indenting to
be printed before any data is printed. \fIfname\fR is currently unused and is
always "". \fIpctx\fR is a pointer to the \fB\s-1ASN1_PCTX\s0\fR for the print operation.
.Sp
Returns 0 on error or a positive value on success. If the return value is 2 then
an additional newline will be printed after the data printed by this function.
.IP "\fIasn1_ex_new_ex\fR" 4
.IX Item "asn1_ex_new_ex"
This is the same as \fIasn1_ex_new\fR except that it is additionally passed the
\&\s-1OSSL_LIB_CTX\s0 to be used in \fIlibctx\fR and any property query string to be used
for algorithm fetching in the \fIpropq\fR parameter. See
\&\*(L"\s-1ALGORITHM FETCHING\*(R"\s0 in \fBcrypto\fR\|(7) for further details. If \fIasn1_ex_new_ex\fR is
non \s-1NULL,\s0 then it will always be called in preference to \fIasn1_ex_new\fR.
.IP "\fIasn1_ex_d2i_ex\fR" 4
.IX Item "asn1_ex_d2i_ex"
This is the same as \fIasn1_ex_d2i\fR except that it is additionally passed the
\&\s-1OSSL_LIB_CTX\s0 to be used in \fIlibctx\fR and any property query string to be used
for algorithm fetching in the \fIpropq\fR parameter. See
\&\*(L"\s-1ALGORITHM FETCHING\*(R"\s0 in \fBcrypto\fR\|(7) for further details. If \fIasn1_ex_d2i_ex\fR is
non \s-1NULL,\s0 then it will always be called in preference to \fIasn1_ex_d2i\fR.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
Return values for the various callbacks are as described above.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBASN1_item_new_ex\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
The \fIasn1_ex_new_ex\fR and \fIasn1_ex_d2i_ex\fR callbacks were added in OpenSSL 3.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

262
openssl-3.4.2/doc/man/man3/ASN1_INTEGER_get_int64.3
View File

@@ -1,262 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 3ossl"
.TH ASN1_INTEGER_GET_INT64 3ossl "2025-07-01" "3.4.2" "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(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_ENUMERATED *a);
\& long ASN1_ENUMERATED_get(const ASN1_ENUMERATED *a);
\&
\& int ASN1_ENUMERATED_set_int64(ASN1_ENUMERATED *a, int64_t r);
\& int ASN1_ENUMERATED_set(ASN1_ENUMERATED *a, long v);
\&
\& ASN1_ENUMERATED *BN_to_ASN1_ENUMERATED(const BIGNUM *bn, ASN1_ENUMERATED *ai);
\& BIGNUM *ASN1_ENUMERATED_to_BN(const 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
\&\fBASN1_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 \fI*pr\fR to the value of \fIa\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
\&\fBASN1_INTEGER_get_uint64()\fR is similar to \fBASN1_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
\&\fBASN1_INTEGER_get()\fR also returns the value of \fIa\fR but it returns 0 if \fIa\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 \fBASN1_INTEGER_get_int64()\fR
instead.
.PP
\&\fBASN1_INTEGER_set_int64()\fR sets the value of \fB\s-1ASN1_INTEGER\s0\fR \fIa\fR to the
\&\fBint64_t\fR value \fIr\fR.
.PP
\&\fBASN1_INTEGER_set_uint64()\fR sets the value of \fB\s-1ASN1_INTEGER\s0\fR \fIa\fR to the
\&\fBuint64_t\fR value \fIr\fR.
.PP
\&\fBASN1_INTEGER_set()\fR sets the value of \fB\s-1ASN1_INTEGER\s0\fR \fIa\fR to the \fIlong\fR value
\&\fIv\fR.
.PP
\&\fBBN_to_ASN1_INTEGER()\fR converts \fB\s-1BIGNUM\s0\fR \fIbn\fR to an \fB\s-1ASN1_INTEGER\s0\fR. If \fIai\fR
is \s-1NULL\s0 a new \fB\s-1ASN1_INTEGER\s0\fR structure is returned. If \fIai\fR is not \s-1NULL\s0 then
the existing structure will be used instead.
.PP
\&\fBASN1_INTEGER_to_BN()\fR converts \s-1ASN1_INTEGER\s0 \fIai\fR into a \fB\s-1BIGNUM\s0\fR. If \fIbn\fR is
\&\s-1NULL\s0 a new \fB\s-1BIGNUM\s0\fR structure is returned. If \fIbn\fR is not \s-1NULL\s0 then the
existing structure will be used instead.
.PP
\&\fBASN1_ENUMERATED_get_int64()\fR, \fBASN1_ENUMERATED_set_int64()\fR,
\&\fBASN1_ENUMERATED_set()\fR, \fBBN_to_ASN1_ENUMERATED()\fR and \fBASN1_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
\&\fBASN1_ENUMERATED_get()\fR returns the value of \fIa\fR in a similar way to
\&\fBASN1_INTEGER_get()\fR but it returns \fB0xffffffffL\fR if the value of \fIa\fR will not
fit in a long type. New applications should use \fBASN1_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 \fBASN1_INTEGER_get()\fR and \fBASN1_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"
\&\fBASN1_INTEGER_set_int64()\fR, \fBASN1_INTEGER_set()\fR, \fBASN1_ENUMERATED_set_int64()\fR and
\&\fBASN1_ENUMERATED_set()\fR return 1 for success and 0 for failure. They will only
fail if a memory allocation error occurs.
.PP
\&\fBASN1_INTEGER_get_int64()\fR and \fBASN1_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
\&\fBBN_to_ASN1_INTEGER()\fR and \fBBN_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
\&\fBASN1_INTEGER_to_BN()\fR and \fBASN1_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"
\&\fBERR_get_error\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fBASN1_INTEGER_set_int64()\fR, \fBASN1_INTEGER_get_int64()\fR,
\&\fBASN1_ENUMERATED_set_int64()\fR and \fBASN1_ENUMERATED_get_int64()\fR
were added in OpenSSL 1.1.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2015\-2020 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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
openssl-3.4.2/doc/man/man3/ASN1_INTEGER_new.3
View File

@@ -1,175 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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_NEW 3ossl"
.TH ASN1_INTEGER_NEW 3ossl "2025-07-01" "3.4.2" "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_new, ASN1_INTEGER_free \- ASN1_INTEGER allocation functions
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/asn1.h>
\&
\& ASN1_INTEGER *ASN1_INTEGER_new(void);
\& void ASN1_INTEGER_free(ASN1_INTEGER *a);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBASN1_INTEGER_new()\fR returns an allocated \fB\s-1ASN1_INTEGER\s0\fR structure.
.PP
\&\fBASN1_INTEGER_free()\fR frees up a single \fB\s-1ASN1_INTEGER\s0\fR object.
If the argument is \s-1NULL,\s0 nothing is done.
.PP
\&\fB\s-1ASN1_INTEGER\s0\fR structure representing the \s-1ASN.1 INTEGER\s0 type
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBASN1_INTEGER_new()\fR return a valid \fB\s-1ASN1_INTEGER\s0\fR structure or \s-1NULL\s0
if an error occurred.
.PP
\&\fBASN1_INTEGER_free()\fR does not return a value.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBERR_get_error\fR\|(3)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2020\-2024 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

171
openssl-3.4.2/doc/man/man3/ASN1_ITEM_lookup.3
View File

@@ -1,171 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 3ossl"
.TH ASN1_ITEM_LOOKUP 3ossl "2025-07-01" "3.4.2" "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"
\&\fBASN1_ITEM_lookup()\fR returns the \fB\s-1ASN1_ITEM\s0\fR named \fIname\fR.
.PP
\&\fBASN1_ITEM_get()\fR returns the \fB\s-1ASN1_ITEM\s0\fR with index \fIi\fR. This function
returns \s-1NULL\s0 if the index \fIi\fR is out of range.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBASN1_ITEM_lookup()\fR and \fBASN1_ITEM_get()\fR return a valid \fB\s-1ASN1_ITEM\s0\fR structure
or \s-1NULL\s0 if an error occurred.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBERR_get_error\fR\|(3)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

182
openssl-3.4.2/doc/man/man3/ASN1_OBJECT_new.3
View File

@@ -1,182 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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_OBJECT_NEW 3ossl"
.TH ASN1_OBJECT_NEW 3ossl "2025-07-01" "3.4.2" "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
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/asn1.h>
\&
\& ASN1_OBJECT *ASN1_OBJECT_new(void);
\& void ASN1_OBJECT_free(ASN1_OBJECT *a);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \fB\s-1ASN1_OBJECT\s0\fR allocation routines, allocate and free an
\&\fB\s-1ASN1_OBJECT\s0\fR structure, which represents an \s-1ASN1 OBJECT IDENTIFIER.\s0
.PP
\&\fBASN1_OBJECT_new()\fR allocates and initializes an \fB\s-1ASN1_OBJECT\s0\fR structure.
.PP
\&\fBASN1_OBJECT_free()\fR frees up the \fB\s-1ASN1_OBJECT\s0\fR structure \fIa\fR.
If \fIa\fR is \s-1NULL,\s0 nothing is done.
.SH "NOTES"
.IX Header "NOTES"
Although \fBASN1_OBJECT_new()\fR allocates a new \fB\s-1ASN1_OBJECT\s0\fR structure it
is almost never used in applications. The \s-1ASN1\s0 object utility functions
such as \fBOBJ_nid2obj()\fR are used instead.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
If the allocation fails, \fBASN1_OBJECT_new()\fR returns \s-1NULL\s0 and sets an error
code that can be obtained by \fBERR_get_error\fR\|(3).
Otherwise it returns a pointer to the newly allocated structure.
.PP
\&\fBASN1_OBJECT_free()\fR returns no value.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBERR_get_error\fR\|(3), \fBd2i_ASN1_OBJECT\fR\|(3)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2002\-2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

196
openssl-3.4.2/doc/man/man3/ASN1_STRING_TABLE_add.3
View File

@@ -1,196 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 3ossl"
.TH ASN1_STRING_TABLE_ADD 3ossl "2025-07-01" "3.4.2" "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"
\&\fBASN1_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 \fInid\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., \fIminsize\fR
and \fImaxsize\fR >= 0, \fImask\fR and \fIflags\fR != 0). If the \fInid\fR is standard,
a copy of the standard \fB\s-1ASN1_STRING_TABLE\s0\fR is created and updated with
other parameters.
.PP
\&\fBASN1_STRING_TABLE_get()\fR searches for an \fB\s-1ASN1_STRING_TABLE\s0\fR item based
on \fInid\fR. It will search the local table first, then the standard one.
.PP
\&\fBASN1_STRING_TABLE_cleanup()\fR frees all \fB\s-1ASN1_STRING_TABLE\s0\fR items added
by \fBASN1_STRING_TABLE_add()\fR.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBASN1_STRING_TABLE_add()\fR returns 1 on success, 0 if an error occurred.
.PP
\&\fBASN1_STRING_TABLE_get()\fR returns a valid \fB\s-1ASN1_STRING_TABLE\s0\fR structure
or \s-1NULL\s0 if nothing is found.
.PP
\&\fBASN1_STRING_TABLE_cleanup()\fR does not return a value.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBERR_get_error\fR\|(3)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2017\-2020 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

244
openssl-3.4.2/doc/man/man3/ASN1_STRING_length.3
View File

@@ -1,244 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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_LENGTH 3ossl"
.TH ASN1_STRING_LENGTH 3ossl "2025-07-01" "3.4.2" "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_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(const ASN1_STRING *a);
\&
\& int ASN1_STRING_cmp(ASN1_STRING *a, ASN1_STRING *b);
\&
\& int ASN1_STRING_set(ASN1_STRING *str, const void *data, int len);
\&
\& int ASN1_STRING_type(const ASN1_STRING *x);
\&
\& int ASN1_STRING_to_UTF8(unsigned char **out, const ASN1_STRING *in);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
These functions allow an \fB\s-1ASN1_STRING\s0\fR structure to be manipulated.
.PP
\&\fBASN1_STRING_length()\fR returns the length of the content of \fIx\fR.
.PP
\&\fBASN1_STRING_get0_data()\fR returns an internal pointer to the data of \fIx\fR.
Since this is an internal pointer it should \fBnot\fR be freed or
modified in any way.
.PP
\&\fBASN1_STRING_data()\fR is similar to \fBASN1_STRING_get0_data()\fR except the
returned value is not constant. This function is deprecated:
applications should use \fBASN1_STRING_get0_data()\fR instead.
.PP
\&\fBASN1_STRING_dup()\fR returns a copy of the structure \fIa\fR.
.PP
\&\fBASN1_STRING_cmp()\fR compares \fIa\fR and \fIb\fR returning 0 if the two
are identical. The string types and content are compared.
.PP
\&\fBASN1_STRING_set()\fR sets the data of string \fIstr\fR to the buffer
\&\fIdata\fR or length \fIlen\fR. The supplied data is copied. If \fIlen\fR
is \-1 then the length is determined by strlen(data).
.PP
\&\fBASN1_STRING_type()\fR returns the type of \fIx\fR, using standard constants
such as \fBV_ASN1_OCTET_STRING\fR.
.PP
\&\fBASN1_STRING_to_UTF8()\fR converts the string \fIin\fR to \s-1UTF8\s0 format, the
converted data is allocated in a buffer in \fI*out\fR. The length of
\&\fIout\fR is returned or a negative error code. The buffer \fI*out\fR
should be freed using \fBOPENSSL_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 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
\&\fBTime\fR.
.PP
These functions should \fBnot\fR be used to examine or modify \fB\s-1ASN1_INTEGER\s0\fR
or \fB\s-1ASN1_ENUMERATED\s0\fR types: the relevant \fB\s-1INTEGER\s0\fR or \fB\s-1ENUMERATED\s0\fR
utility functions should be used instead.
.PP
In general it cannot be assumed that the data returned by \fBASN1_STRING_data()\fR
is null terminated or does not contain embedded nulls. The actual format
of the data will depend on the actual string type itself: for example
for an IA5String the data will be \s-1ASCII,\s0 for a BMPString two bytes per
character in big endian format, and for a UTF8String it will be in \s-1UTF8\s0 format.
.PP
Similar care should be take to ensure the data is in the correct format
when calling \fBASN1_STRING_set()\fR.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBASN1_STRING_length()\fR returns the length of the content of \fIx\fR.
.PP
\&\fBASN1_STRING_get0_data()\fR and \fBASN1_STRING_data()\fR return an internal pointer to
the data of \fIx\fR.
.PP
\&\fBASN1_STRING_dup()\fR returns a valid \fB\s-1ASN1_STRING\s0\fR structure or \s-1NULL\s0 if an
error occurred.
.PP
\&\fBASN1_STRING_cmp()\fR returns an integer greater than, equal to, or less than 0,
according to whether \fIa\fR is greater than, equal to, or less than \fIb\fR.
.PP
\&\fBASN1_STRING_set()\fR returns 1 on success or 0 on error.
.PP
\&\fBASN1_STRING_type()\fR returns the type of \fIx\fR.
.PP
\&\fBASN1_STRING_to_UTF8()\fR returns the number of bytes in output string \fIout\fR or a
negative value if an error occurred.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBERR_get_error\fR\|(3)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2002\-2020 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

183
openssl-3.4.2/doc/man/man3/ASN1_STRING_new.3
View File

@@ -1,183 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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_NEW 3ossl"
.TH ASN1_STRING_NEW 3ossl "2025-07-01" "3.4.2" "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
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/asn1.h>
\&
\& ASN1_STRING *ASN1_STRING_new(void);
\& ASN1_STRING *ASN1_STRING_type_new(int type);
\& void ASN1_STRING_free(ASN1_STRING *a);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBASN1_STRING_new()\fR returns an allocated \fB\s-1ASN1_STRING\s0\fR structure. Its type
is undefined.
.PP
\&\fBASN1_STRING_type_new()\fR returns an allocated \fB\s-1ASN1_STRING\s0\fR structure of
type \fItype\fR.
.PP
\&\fBASN1_STRING_free()\fR frees up \fIa\fR.
If \fIa\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
\&\fBASN1_OCTET_STRING_new()\fR calls ASN1_STRING_type_new(V_ASN1_OCTET_STRING).
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBASN1_STRING_new()\fR and \fBASN1_STRING_type_new()\fR return a valid
\&\fB\s-1ASN1_STRING\s0\fR structure or \s-1NULL\s0 if an error occurred.
.PP
\&\fBASN1_STRING_free()\fR does not return a value.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBERR_get_error\fR\|(3)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2002\-2023 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

246
openssl-3.4.2/doc/man/man3/ASN1_STRING_print_ex.3
View File

@@ -1,246 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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_PRINT_EX 3ossl"
.TH ASN1_STRING_PRINT_EX 3ossl "2025-07-01" "3.4.2" "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_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, 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"
These functions output an \fB\s-1ASN1_STRING\s0\fR structure. \fB\s-1ASN1_STRING\s0\fR is used to
represent all the \s-1ASN1\s0 string types.
.PP
\&\fBASN1_STRING_print_ex()\fR outputs \fIstr\fR to \fIout\fR, the format is determined by
the options \fIflags\fR. \fBASN1_STRING_print_ex_fp()\fR is identical except it outputs
to \fIfp\fR instead.
.PP
\&\fBASN1_STRING_print()\fR prints \fIstr\fR to \fIout\fR but using a different format to
\&\fBASN1_STRING_print_ex()\fR. It replaces unprintable characters (other than \s-1CR, LF\s0)
with '.'.
.PP
\&\fBASN1_tag2str()\fR returns a human-readable name of the specified \s-1ASN.1\s0 \fItag\fR.
.SH "NOTES"
.IX Header "NOTES"
\&\fBASN1_STRING_print()\fR is a deprecated function which should be avoided; use
\&\fBASN1_STRING_print_ex()\fR instead.
.PP
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 \fIflags\fR is listed below.
.PP
Various characters can be escaped. If \fB\s-1ASN1_STRFLGS_ESC_2253\s0\fR is set the characters
determined by \s-1RFC2253\s0 are escaped. If \fB\s-1ASN1_STRFLGS_ESC_CTRL\s0\fR is set control
characters are escaped. If \fB\s-1ASN1_STRFLGS_ESC_MSB\s0\fR is set characters with the
\&\s-1MSB\s0 set are escaped: this option should \fBnot\fR be used if the terminal correctly
interprets \s-1UTF8\s0 sequences.
.PP
Escaping takes several forms.
.PP
If the character being escaped is a 16 bit character then the form \*(L"\eUXXXX\*(R" is used
using exactly four characters for the hex representation. If it is 32 bits then
\&\*(L"\eWXXXXXXXX\*(R" is used using eight characters of its hex representation. These forms
will only be used if \s-1UTF8\s0 conversion is not set (see below).
.PP
Printable characters are normally escaped using the backslash '\e' character. If
\&\fB\s-1ASN1_STRFLGS_ESC_QUOTE\s0\fR is set then the whole string is instead surrounded by
double quote characters: this is arguably more readable than the backslash
notation. Other characters use the \*(L"\eXX\*(R" using exactly two characters of the hex
representation.
.PP
If \fB\s-1ASN1_STRFLGS_UTF8_CONVERT\s0\fR is set then characters are converted to \s-1UTF8\s0
format first. If the terminal supports the display of \s-1UTF8\s0 sequences then this
option will correctly display multi byte characters.
.PP
If \fB\s-1ASN1_STRFLGS_IGNORE_TYPE\s0\fR is set then the string type is not interpreted at
all: everything is assumed to be one byte per character. This is primarily for
debugging purposes and can result in confusing output in multi character strings.
.PP
If \fB\s-1ASN1_STRFLGS_SHOW_TYPE\s0\fR is set then the string type itself is printed out
before its value (for example \*(L"\s-1BMPSTRING\*(R"\s0), this actually uses \fBASN1_tag2str()\fR.
.PP
The content of a string instead of being interpreted can be \*(L"dumped\*(R": this just
outputs the value of the string using the form #XXXX using hex format for each
octet.
.PP
If \fB\s-1ASN1_STRFLGS_DUMP_ALL\s0\fR is set then any type is dumped.
.PP
Normally non character string types (such as \s-1OCTET STRING\s0) are assumed to be
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
\&\fB\s-1ASN1_STRFLGS_DUMP_DER\s0\fR is set then the complete encoding is dumped
instead (including tag and length octets).
.PP
\&\fB\s-1ASN1_STRFLGS_RFC2253\s0\fR includes all the flags required by \s-1RFC2253.\s0 It is
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"
\&\fBASN1_STRING_print_ex()\fR and \fBASN1_STRING_print_ex_fp()\fR return the number of
characters written or \-1 if an error occurred.
.PP
\&\fBASN1_STRING_print()\fR returns 1 on success or 0 on error.
.PP
\&\fBASN1_tag2str()\fR returns a human-readable name of the specified \s-1ASN.1\s0 \fItag\fR.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBX509_NAME_print_ex\fR\|(3),
\&\fBASN1_tag2str\fR\|(3)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2002\-2018 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

419
openssl-3.4.2/doc/man/man3/ASN1_TIME_set.3
View File

@@ -1,419 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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_TIME_SET 3ossl"
.TH ASN1_TIME_SET 3ossl "2025-07-01" "3.4.2" "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_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_TIME_print_ex, 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,
ASN1_TIME_dup, ASN1_UTCTIME_dup, ASN1_GENERALIZEDTIME_dup \- ASN.1 Time functions
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 4
\& ASN1_TIME *ASN1_TIME_set(ASN1_TIME *s, time_t t);
\& ASN1_UTCTIME *ASN1_UTCTIME_set(ASN1_UTCTIME *s, time_t t);
\& ASN1_GENERALIZEDTIME *ASN1_GENERALIZEDTIME_set(ASN1_GENERALIZEDTIME *s,
\& time_t t);
\&
\& ASN1_TIME *ASN1_TIME_adj(ASN1_TIME *s, time_t t, int offset_day,
\& long offset_sec);
\& ASN1_UTCTIME *ASN1_UTCTIME_adj(ASN1_UTCTIME *s, time_t t,
\& int offset_day, long offset_sec);
\& ASN1_GENERALIZEDTIME *ASN1_GENERALIZEDTIME_adj(ASN1_GENERALIZEDTIME *s,
\& time_t t, int offset_day,
\& long offset_sec);
\&
\& int ASN1_TIME_set_string(ASN1_TIME *s, const char *str);
\& int ASN1_TIME_set_string_X509(ASN1_TIME *s, const char *str);
\& int ASN1_UTCTIME_set_string(ASN1_UTCTIME *s, const char *str);
\& int ASN1_GENERALIZEDTIME_set_string(ASN1_GENERALIZEDTIME *s,
\& const char *str);
\&
\& int ASN1_TIME_normalize(ASN1_TIME *s);
\&
\& int ASN1_TIME_check(const ASN1_TIME *t);
\& int ASN1_UTCTIME_check(const ASN1_UTCTIME *t);
\& int ASN1_GENERALIZEDTIME_check(const ASN1_GENERALIZEDTIME *t);
\&
\& int ASN1_TIME_print(BIO *b, const ASN1_TIME *s);
\& int ASN1_TIME_print_ex(BIO *bp, const ASN1_TIME *tm, unsigned long flags);
\& 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);
\&
\& ASN1_TIME *ASN1_TIME_dup(const ASN1_TIME *t);
\& ASN1_UTCTIME *ASN1_UTCTIME_dup(const ASN1_UTCTIME *t);
\& ASN1_GENERALIZEDTIME *ASN1_GENERALIZEDTIME_dup(const ASN1_GENERALIZEDTIME *t);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \fBASN1_TIME_set()\fR, \fBASN1_UTCTIME_set()\fR and \fBASN1_GENERALIZEDTIME_set()\fR
functions set the structure \fIs\fR to the time represented by the time_t
value \fIt\fR. If \fIs\fR is \s-1NULL\s0 a new time structure is allocated and returned.
.PP
The \fBASN1_TIME_adj()\fR, \fBASN1_UTCTIME_adj()\fR and \fBASN1_GENERALIZEDTIME_adj()\fR
functions set the time structure \fIs\fR to the time represented
by the time \fIoffset_day\fR and \fIoffset_sec\fR after the time_t value \fIt\fR.
The values of \fIoffset_day\fR or \fIoffset_sec\fR can be negative to set a
time before \fIt\fR. The \fIoffset_sec\fR value can also exceed the number of
seconds in a day. If \fIs\fR is \s-1NULL\s0 a new structure is allocated
and returned.
.PP
The \fBASN1_TIME_set_string()\fR, \fBASN1_UTCTIME_set_string()\fR and
\&\fBASN1_GENERALIZEDTIME_set_string()\fR functions set the time structure \fIs\fR
to the time represented by string \fIstr\fR which must be in appropriate \s-1ASN.1\s0
time format (for example \s-1YYMMDDHHMMSSZ\s0 or \s-1YYYYMMDDHHMMSSZ\s0). If \fIs\fR is \s-1NULL\s0
this function performs a format check on \fIstr\fR only. The string \fIstr\fR
is copied into \fIs\fR.
.PP
\&\fBASN1_TIME_set_string_X509()\fR sets \fB\s-1ASN1_TIME\s0\fR structure \fIs\fR to the time
represented by string \fIstr\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 \fIs\fR is \s-1NULL\s0 this function performs a format check
on \fIstr\fR only.
.PP
The \fBASN1_TIME_normalize()\fR function converts an \fB\s-1ASN1_GENERALIZEDTIME\s0\fR or
\&\fB\s-1ASN1_UTCTIME\s0\fR into a time value that can be used in a certificate. It
should be used after the \fBASN1_TIME_set_string()\fR functions and before
\&\fBASN1_TIME_print()\fR functions to get consistent (i.e. \s-1GMT\s0) results.
.PP
The \fBASN1_TIME_check()\fR, \fBASN1_UTCTIME_check()\fR and \fBASN1_GENERALIZEDTIME_check()\fR
functions check the syntax of the time structure \fIs\fR.
.PP
The \fBASN1_TIME_print()\fR, \fBASN1_UTCTIME_print()\fR and \fBASN1_GENERALIZEDTIME_print()\fR
functions print the time structure \fIs\fR to \s-1BIO\s0 \fIb\fR in human readable
format. It will be of the format \s-1MMM DD\s0 HH:MM:SS[.s*] \s-1YYYY GMT,\s0 for example
\&\*(L"Feb 3 00:55:52 2015 \s-1GMT\*(R",\s0 which does not include a newline.
If the time structure has invalid format it prints out \*(L"Bad time value\*(R" and
returns an error. The output for generalized time may include a fractional part
following the second.
.PP
\&\fBASN1_TIME_print_ex()\fR provides \fIflags\fR to specify the output format of the
datetime. This can be either \fB\s-1ASN1_DTFLGS_RFC822\s0\fR or \fB\s-1ASN1_DTFLGS_ISO8601\s0\fR.
.PP
\&\fBASN1_TIME_to_tm()\fR converts the time \fIs\fR to the standard \fItm\fR structure.
If \fIs\fR is \s-1NULL,\s0 then the current time is converted. The output time is \s-1GMT.\s0
The \fItm_sec\fR, \fItm_min\fR, \fItm_hour\fR, \fItm_mday\fR, \fItm_wday\fR, \fItm_yday\fR,
\&\fItm_mon\fR and \fItm_year\fR fields of \fItm\fR structure are set to proper values,
whereas all other fields are set to 0. If \fItm\fR is \s-1NULL\s0 this function performs
a format check on \fIs\fR only. If \fIs\fR is in Generalized format with fractional
seconds, e.g. \s-1YYYYMMDDHHMMSS.SSSZ,\s0 the fractional seconds will be lost while
converting \fIs\fR to \fItm\fR structure.
.PP
\&\fBASN1_TIME_diff()\fR sets \fI*pday\fR and \fI*psec\fR to the time difference between
\&\fIfrom\fR and \fIto\fR. If \fIto\fR represents a time later than \fIfrom\fR then
one or both (depending on the time difference) of \fI*pday\fR and \fI*psec\fR
will be positive. If \fIto\fR represents a time earlier than \fIfrom\fR then
one or both of \fI*pday\fR and \fI*psec\fR will be negative. If \fIto\fR and \fIfrom\fR
represent the same time then \fI*pday\fR and \fI*psec\fR will both be zero.
If both \fI*pday\fR and \fI*psec\fR are nonzero they will always have the same
sign. The value of \fI*psec\fR will always be less than the number of seconds
in a day. If \fIfrom\fR or \fIto\fR is \s-1NULL\s0 the current time is used.
.PP
The \fBASN1_TIME_cmp_time_t()\fR and \fBASN1_UTCTIME_cmp_time_t()\fR functions compare
the two times represented by the time structure \fIs\fR and the time_t \fIt\fR.
.PP
The \fBASN1_TIME_compare()\fR function compares the two times represented by the
time structures \fIa\fR and \fIb\fR.
.PP
The \fBASN1_TIME_to_generalizedtime()\fR function converts an \fB\s-1ASN1_TIME\s0\fR to an
\&\fB\s-1ASN1_GENERALIZEDTIME\s0\fR, regardless of year. If either \fIout\fR or
\&\fI*out\fR are \s-1NULL,\s0 then a new object is allocated and must be freed after use.
.PP
The \fBASN1_TIME_dup()\fR, \fBASN1_UTCTIME_dup()\fR and \fBASN1_GENERALIZEDTIME_dup()\fR functions
duplicate the time structure \fIt\fR and return the duplicated result
correspondingly.
.SH "NOTES"
.IX Header "NOTES"
The \fB\s-1ASN1_TIME\s0\fR structure corresponds to the \s-1ASN.1\s0 structure \fBTime\fR
defined in \s-1RFC5280\s0 et al. The time setting functions obey the rules outlined
in \s-1RFC5280:\s0 if the date can be represented by UTCTime it is used, else
GeneralizedTime is used.
.PP
The \fB\s-1ASN1_TIME\s0\fR, \fB\s-1ASN1_UTCTIME\s0\fR and \fB\s-1ASN1_GENERALIZEDTIME\s0\fR structures are
represented as an \fB\s-1ASN1_STRING\s0\fR internally and can be freed up using
\&\fBASN1_STRING_free()\fR.
.PP
The \fB\s-1ASN1_TIME\s0\fR 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
\&\fB\s-1ASN1_UTCTIME\s0\fR 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 \fBASN1_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 \fBASN1_TIME_adj()\fR instead and pass the offset value
in the \fIoffset_sec\fR and \fIoffset_day\fR parameters instead of directly
manipulating a time_t value.
.PP
\&\fBASN1_TIME_adj()\fR may change the type from \fB\s-1ASN1_GENERALIZEDTIME\s0\fR to
\&\fB\s-1ASN1_UTCTIME\s0\fR, or vice versa, based on the resulting year.
\&\fBASN1_GENERALIZEDTIME_adj()\fR and \fBASN1_UTCTIME_adj()\fR will not modify the type
of the return structure.
.PP
It is recommended that functions starting with \fB\s-1ASN1_TIME\s0\fR be used instead of
those starting with \fB\s-1ASN1_UTCTIME\s0\fR or \fB\s-1ASN1_GENERALIZEDTIME\s0\fR. The functions
starting with \fB\s-1ASN1_UTCTIME\s0\fR and \fB\s-1ASN1_GENERALIZEDTIME\s0\fR act only on that
specific time format. The functions starting with \fB\s-1ASN1_TIME\s0\fR will operate on
either format.
.PP
Users familiar with \s-1RFC822\s0 should note that when specifying the flag
\&\fB\s-1ASN1_DTFLGS_RFC822\s0\fR the year will be formatted as documented above,
i.e., using 4 digits, not 2 as specified in \s-1RFC822.\s0
.SH "BUGS"
.IX Header "BUGS"
\&\fBASN1_TIME_print()\fR, \fBASN1_UTCTIME_print()\fR and \fBASN1_GENERALIZEDTIME_print()\fR do
not print out the timezone: 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
\&\fBASN1_TIME_print()\fR, \fBASN1_TIME_print_ex()\fR, \fBASN1_UTCTIME_print()\fR and
\&\fBASN1_GENERALIZEDTIME_print()\fR do not distinguish if they fail because
of an I/O error or invalid time format.
.PP
Use the \fBASN1_TIME_normalize()\fR function to normalize the time value before
printing to get \s-1GMT\s0 results.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBASN1_TIME_set()\fR, \fBASN1_UTCTIME_set()\fR, \fBASN1_GENERALIZEDTIME_set()\fR,
\&\fBASN1_TIME_adj()\fR, \fBASN1_UTCTIME_adj()\fR and \fBASN1_GENERALIZEDTIME_set()\fR return
a pointer to a time structure or \s-1NULL\s0 if an error occurred.
.PP
\&\fBASN1_TIME_set_string()\fR, \fBASN1_UTCTIME_set_string()\fR,
\&\fBASN1_GENERALIZEDTIME_set_string()\fR and \fBASN1_TIME_set_string_X509()\fR return
1 if the time value is successfully set and 0 otherwise.
.PP
\&\fBASN1_TIME_normalize()\fR returns 1 on success, and 0 on error.
.PP
\&\fBASN1_TIME_check()\fR, ASN1_UTCTIME_check and \fBASN1_GENERALIZEDTIME_check()\fR return 1
if the structure is syntactically correct and 0 otherwise.
.PP
\&\fBASN1_TIME_print()\fR, \fBASN1_UTCTIME_print()\fR and \fBASN1_GENERALIZEDTIME_print()\fR
return 1 if the time is successfully printed out and
0 if an I/O error occurred an error occurred (I/O error or invalid time format).
.PP
\&\fBASN1_TIME_to_tm()\fR returns 1 if the time is successfully parsed and 0 if an
error occurred (invalid time format).
.PP
\&\fBASN1_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
\&\fBASN1_TIME_cmp_time_t()\fR and \fBASN1_UTCTIME_cmp_time_t()\fR return \-1 if \fIs\fR is
before \fIt\fR, 0 if \fIs\fR equals \fIt\fR, or 1 if \fIs\fR is after \fIt\fR. \-2 is returned
on error.
.PP
\&\fBASN1_TIME_compare()\fR returns \-1 if \fIa\fR is before \fIb\fR, 0 if \fIa\fR equals \fIb\fR,
or 1 if \fIa\fR is after \fIb\fR. \-2 is returned on error.
.PP
\&\fBASN1_TIME_to_generalizedtime()\fR returns a pointer to the appropriate time
structure on success or \s-1NULL\s0 if an error occurred.
.PP
\&\fBASN1_TIME_dup()\fR, \fBASN1_UTCTIME_dup()\fR and \fBASN1_GENERALIZEDTIME_dup()\fR return a
pointer to a time structure or \s-1NULL\s0 if an error occurred.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
Set a time structure to one hour after the current time and print it out:
.PP
.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);
\& ASN1_TIME_print(b, tm);
\& ASN1_STRING_free(tm);
\& BIO_free(b);
.Ve
.PP
Determine if one time is later or sooner than the current time:
.PP
.Vb 1
\& int day, sec;
\&
\& if (!ASN1_TIME_diff(&day, &sec, NULL, to))
\& /* Invalid time format */
\&
\& if (day > 0 || sec > 0)
\& printf("Later\en");
\& else if (day < 0 || sec < 0)
\& printf("Sooner\en");
\& else
\& printf("Same\en");
.Ve
.SH "HISTORY"
.IX Header "HISTORY"
The \fBASN1_TIME_to_tm()\fR function was added in OpenSSL 1.1.1.
The \fBASN1_TIME_set_string_X509()\fR function was added in OpenSSL 1.1.1.
The \fBASN1_TIME_normalize()\fR function was added in OpenSSL 1.1.1.
The \fBASN1_TIME_cmp_time_t()\fR function was added in OpenSSL 1.1.1.
The \fBASN1_TIME_compare()\fR function was added in OpenSSL 1.1.1.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2015\-2025 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

233
openssl-3.4.2/doc/man/man3/ASN1_TYPE_get.3
View File

@@ -1,233 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 3ossl"
.TH ASN1_TYPE_GET 3ossl "2025-07-01" "3.4.2" "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 \fB\s-1ASN1_TYPE\s0\fR structure to be manipulated. The
\&\fB\s-1ASN1_TYPE\s0\fR 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
\&\fBASN1_TYPE_get()\fR returns the type of \fIa\fR or 0 if it fails.
.PP
\&\fBASN1_TYPE_set()\fR sets the value of \fIa\fR to \fItype\fR and \fIvalue\fR. This
function uses the pointer \fIvalue\fR internally so it must \fBnot\fR be freed
up after the call.
.PP
\&\fBASN1_TYPE_set1()\fR sets the value of \fIa\fR to \fItype\fR a copy of \fIvalue\fR.
.PP
\&\fBASN1_TYPE_cmp()\fR compares \s-1ASN.1\s0 types \fIa\fR and \fIb\fR and returns 0 if
they are identical and nonzero otherwise.
.PP
\&\fBASN1_TYPE_unpack_sequence()\fR attempts to parse the \s-1SEQUENCE\s0 present in
\&\fIt\fR using the \s-1ASN.1\s0 structure \fIit\fR. If successful it returns a pointer
to the \s-1ASN.1\s0 structure corresponding to \fIit\fR which must be freed by the
caller. If it fails it return \s-1NULL.\s0
.PP
\&\fBASN1_TYPE_pack_sequence()\fR attempts to encode the \s-1ASN.1\s0 structure \fIs\fR
corresponding to \fIit\fR into an \fB\s-1ASN1_TYPE\s0\fR. If successful the encoded
\&\fB\s-1ASN1_TYPE\s0\fR is returned. If \fIt\fR and \fI*t\fR are not \s-1NULL\s0 the encoded type
is written to \fIt\fR overwriting any existing data. If \fIt\fR is not \s-1NULL\s0
but \fI*t\fR is \s-1NULL\s0 the returned \fB\s-1ASN1_TYPE\s0\fR is written to \fI*t\fR.
.SH "NOTES"
.IX Header "NOTES"
The type and meaning of the \fIvalue\fR parameter for \fBASN1_TYPE_set()\fR and
\&\fBASN1_TYPE_set1()\fR is determined by the \fItype\fR parameter.
If \fItype\fR is \fBV_ASN1_NULL\fR \fIvalue\fR is ignored. If \fItype\fR is
\&\fBV_ASN1_BOOLEAN\fR
then the boolean is set to \s-1TRUE\s0 if \fIvalue\fR is not \s-1NULL.\s0 If \fItype\fR is
\&\fBV_ASN1_OBJECT\fR then value is an \fB\s-1ASN1_OBJECT\s0\fR structure. Otherwise \fItype\fR
is and \fB\s-1ASN1_STRING\s0\fR structure. If \fItype\fR corresponds to a primitive type
(or a string type) then the contents of the \fB\s-1ASN1_STRING\s0\fR contain the content
octets of the type. If \fItype\fR corresponds to a constructed type or
a tagged type (\fBV_ASN1_SEQUENCE\fR, \fBV_ASN1_SET\fR or \fBV_ASN1_OTHER\fR) then the
\&\fB\s-1ASN1_STRING\s0\fR contains the entire \s-1ASN.1\s0 encoding verbatim (including tag and
length octets).
.PP
\&\fBASN1_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 nonzero encoding but \fBASN1_TYPE_cmp()\fR will
only return zero if the values are the same.
.PP
If either or both of the parameters passed to \fBASN1_TYPE_cmp()\fR is \s-1NULL\s0 the
return value is nonzero. 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
unparsable 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"
\&\fBASN1_TYPE_get()\fR returns the type of the \fB\s-1ASN1_TYPE\s0\fR argument.
.PP
\&\fBASN1_TYPE_set()\fR does not return a value.
.PP
\&\fBASN1_TYPE_set1()\fR returns 1 for success and 0 for failure.
.PP
\&\fBASN1_TYPE_cmp()\fR returns 0 if the types are identical and nonzero otherwise.
.PP
\&\fBASN1_TYPE_unpack_sequence()\fR returns a pointer to an \s-1ASN.1\s0 structure or
\&\s-1NULL\s0 on failure.
.PP
\&\fBASN1_TYPE_pack_sequence()\fR return an \fB\s-1ASN1_TYPE\s0\fR structure if it succeeds or
\&\s-1NULL\s0 on failure.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2015\-2020 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

368
openssl-3.4.2/doc/man/man3/ASN1_aux_cb.3
View File

@@ -1,368 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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_AUX_CB 3ossl"
.TH ASN1_AUX_CB 3ossl "2025-07-01" "3.4.2" "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_AUX, ASN1_PRINT_ARG, ASN1_STREAM_ARG, ASN1_aux_cb, ASN1_aux_const_cb
\&\- ASN.1 auxiliary data
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/asn1t.h>
\&
\& struct ASN1_AUX_st {
\& void *app_data;
\& int flags;
\& int ref_offset; /* Offset of reference value */
\& int ref_lock; /* Offset to an CRYPTO_RWLOCK */
\& ASN1_aux_cb *asn1_cb;
\& int enc_offset; /* Offset of ASN1_ENCODING structure */
\& ASN1_aux_const_cb *asn1_const_cb; /* for ASN1_OP_I2D_ and ASN1_OP_PRINT_ */
\& };
\& typedef struct ASN1_AUX_st ASN1_AUX;
\&
\& struct ASN1_PRINT_ARG_st {
\& BIO *out;
\& int indent;
\& const ASN1_PCTX *pctx;
\& };
\& typedef struct ASN1_PRINT_ARG_st ASN1_PRINT_ARG;
\&
\& struct ASN1_STREAM_ARG_st {
\& BIO *out;
\& BIO *ndef_bio;
\& unsigned char **boundary;
\& };
\& typedef struct ASN1_STREAM_ARG_st ASN1_STREAM_ARG;
\&
\& typedef int ASN1_aux_cb(int operation, ASN1_VALUE **in, const ASN1_ITEM *it,
\& void *exarg);
\& typedef int ASN1_aux_const_cb(int operation, const ASN1_VALUE **in,
\& const ASN1_ITEM *it, void *exarg);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\s-1ASN.1\s0 data structures can be associated with an \fB\s-1ASN1_AUX\s0\fR object to supply
additional information about the \s-1ASN.1\s0 structure. An \fB\s-1ASN1_AUX\s0\fR structure is
associated with the structure during the definition of the \s-1ASN.1\s0 template. For
example an \fB\s-1ASN1_AUX\s0\fR structure will be associated by using one of the various
\&\s-1ASN.1\s0 template definition macros that supply auxiliary information such as
\&\fBASN1_SEQUENCE_enc()\fR, \fBASN1_SEQUENCE_ref()\fR, \fBASN1_SEQUENCE_cb_const_cb()\fR,
\&\fBASN1_SEQUENCE_const_cb()\fR, \fBASN1_SEQUENCE_cb()\fR or \fBASN1_NDEF_SEQUENCE_cb()\fR.
.PP
An \fB\s-1ASN1_AUX\s0\fR structure contains the following information.
.IP "\fIapp_data\fR" 4
.IX Item "app_data"
Arbitrary application data
.IP "\fIflags\fR" 4
.IX Item "flags"
Flags which indicate the auxiliarly functionality supported.
.Sp
The \fB\s-1ASN1_AFLG_REFCOUNT\s0\fR flag indicates that objects support reference counting.
.Sp
The \fB\s-1ASN1_AFLG_ENCODING\s0\fR flag indicates that the original encoding of the
object will be saved.
.Sp
The \fB\s-1ASN1_AFLG_BROKEN\s0\fR flag is a work around for broken encoders where the
sequence length value may not be correct. This should generally not be used.
.Sp
The \fB\s-1ASN1_AFLG_CONST_CB\s0\fR flag indicates that the \*(L"const\*(R" form of the
\&\fB\s-1ASN1_AUX\s0\fR callback should be used in preference to the non-const form.
.IP "\fIref_offset\fR" 4
.IX Item "ref_offset"
If the \fB\s-1ASN1_AFLG_REFCOUNT\s0\fR flag is set then this value is assumed to be an
offset into the \fB\s-1ASN1_VALUE\s0\fR structure where a \fB\s-1CRYPTO_REF_COUNT\s0\fR may be
found for the purposes of reference counting.
.IP "\fIref_lock\fR" 4
.IX Item "ref_lock"
If the \fB\s-1ASN1_AFLG_REFCOUNT\s0\fR flag is set then this value is assumed to be an
offset into the \fB\s-1ASN1_VALUE\s0\fR structure where a \fB\s-1CRYPTO_RWLOCK\s0\fR may be
found for the purposes of reference counting.
.IP "\fIasn1_cb\fR" 4
.IX Item "asn1_cb"
A callback that will be invoked at various points during the processing of
the \fB\s-1ASN1_VALUE\s0\fR. See below for further details.
.IP "\fIenc_offset\fR" 4
.IX Item "enc_offset"
Offset into the \fB\s-1ASN1_VALUE\s0\fR object where the original encoding of the object
will be saved if the \fB\s-1ASN1_AFLG_ENCODING\s0\fR flag has been set.
.IP "\fIasn1_const_cb\fR" 4
.IX Item "asn1_const_cb"
A callback that will be invoked at various points during the processing of
the \fB\s-1ASN1_VALUE\s0\fR. This is used in preference to the \fIasn1_cb\fR callback if
the \fB\s-1ASN1_AFLG_CONST_CB\s0\fR flag is set. See below for further details.
.PP
During the processing of an \fB\s-1ASN1_VALUE\s0\fR object the callbacks set via
\&\fIasn1_cb\fR or \fIasn1_const_cb\fR will be invoked as a result of various events
indicated via the \fIoperation\fR parameter. The value of \fI*in\fR will be the
\&\fB\s-1ASN1_VALUE\s0\fR object being processed based on the template in \fIit\fR. An
additional operation specific parameter may be passed in \fIexarg\fR. The currently
supported operations are as follows. The callbacks should return a positive
value on success or zero on error, unless otherwise noted below.
.IP "\fB\s-1ASN1_OP_NEW_PRE\s0\fR" 4
.IX Item "ASN1_OP_NEW_PRE"
Invoked when processing a \fB\s-1CHOICE\s0\fR, \fB\s-1SEQUENCE\s0\fR or \fB\s-1NDEF_SEQUENCE\s0\fR structure
prior to an \fB\s-1ASN1_VALUE\s0\fR object being allocated. The callback may allocate the
\&\fB\s-1ASN1_VALUE\s0\fR itself and store it in \fI*pval\fR. If it does so it should return 2
from the callback. On error it should return 0.
.IP "\fB\s-1ASN1_OP_NEW_POST\s0\fR" 4
.IX Item "ASN1_OP_NEW_POST"
Invoked when processing a \fB\s-1CHOICE\s0\fR, \fB\s-1SEQUENCE\s0\fR or \fB\s-1NDEF_SEQUENCE\s0\fR structure
after an \fB\s-1ASN1_VALUE\s0\fR object has been allocated. The allocated object is in
\&\fI*pval\fR.
.IP "\fB\s-1ASN1_OP_FREE_PRE\s0\fR" 4
.IX Item "ASN1_OP_FREE_PRE"
Invoked when processing a \fB\s-1CHOICE\s0\fR, \fB\s-1SEQUENCE\s0\fR or \fB\s-1NDEF_SEQUENCE\s0\fR structure
immediately before an \fB\s-1ASN1_VALUE\s0\fR is freed. If the callback originally
constructed the \fB\s-1ASN1_VALUE\s0\fR via \fB\s-1ASN1_OP_NEW_PRE\s0\fR then it should free it at
this point and return 2 from the callback. Otherwise it should return 1 for
success or 0 on error.
.IP "\fB\s-1ASN1_OP_FREE_POST\s0\fR" 4
.IX Item "ASN1_OP_FREE_POST"
Invoked when processing a \fB\s-1CHOICE\s0\fR, \fB\s-1SEQUENCE\s0\fR or \fB\s-1NDEF_SEQUENCE\s0\fR structure
immediately after \fB\s-1ASN1_VALUE\s0\fR sub-structures are freed.
.IP "\fB\s-1ASN1_OP_D2I_PRE\s0\fR" 4
.IX Item "ASN1_OP_D2I_PRE"
Invoked when processing a \fB\s-1CHOICE\s0\fR, \fB\s-1SEQUENCE\s0\fR or \fB\s-1NDEF_SEQUENCE\s0\fR structure
immediately before a \*(L"d2i\*(R" operation for the \fB\s-1ASN1_VALUE\s0\fR.
.IP "\fB\s-1ASN1_OP_D2I_POST\s0\fR" 4
.IX Item "ASN1_OP_D2I_POST"
Invoked when processing a \fB\s-1CHOICE\s0\fR, \fB\s-1SEQUENCE\s0\fR or \fB\s-1NDEF_SEQUENCE\s0\fR structure
immediately after a \*(L"d2i\*(R" operation for the \fB\s-1ASN1_VALUE\s0\fR.
.IP "\fB\s-1ASN1_OP_I2D_PRE\s0\fR" 4
.IX Item "ASN1_OP_I2D_PRE"
Invoked when processing a \fB\s-1CHOICE\s0\fR, \fB\s-1SEQUENCE\s0\fR or \fB\s-1NDEF_SEQUENCE\s0\fR structure
immediately before a \*(L"i2d\*(R" operation for the \fB\s-1ASN1_VALUE\s0\fR.
.IP "\fB\s-1ASN1_OP_I2D_POST\s0\fR" 4
.IX Item "ASN1_OP_I2D_POST"
Invoked when processing a \fB\s-1CHOICE\s0\fR, \fB\s-1SEQUENCE\s0\fR or \fB\s-1NDEF_SEQUENCE\s0\fR structure
immediately after a \*(L"i2d\*(R" operation for the \fB\s-1ASN1_VALUE\s0\fR.
.IP "\fB\s-1ASN1_OP_PRINT_PRE\s0\fR" 4
.IX Item "ASN1_OP_PRINT_PRE"
Invoked when processing a \fB\s-1SEQUENCE\s0\fR or \fB\s-1NDEF_SEQUENCE\s0\fR structure immediately
before printing the \fB\s-1ASN1_VALUE\s0\fR. The \fIexarg\fR argument will be a pointer to an
\&\fB\s-1ASN1_PRINT_ARG\s0\fR structure (see below).
.IP "\fB\s-1ASN1_OP_PRINT_POST\s0\fR" 4
.IX Item "ASN1_OP_PRINT_POST"
Invoked when processing a \fB\s-1SEQUENCE\s0\fR or \fB\s-1NDEF_SEQUENCE\s0\fR structure immediately
after printing the \fB\s-1ASN1_VALUE\s0\fR. The \fIexarg\fR argument will be a pointer to an
\&\fB\s-1ASN1_PRINT_ARG\s0\fR structure (see below).
.IP "\fB\s-1ASN1_OP_STREAM_PRE\s0\fR" 4
.IX Item "ASN1_OP_STREAM_PRE"
Invoked immediately prior to streaming the \fB\s-1ASN1_VALUE\s0\fR data using indefinite
length encoding. The \fIexarg\fR argument will be a pointer to a \fB\s-1ASN1_STREAM_ARG\s0\fR
structure (see below).
.IP "\fB\s-1ASN1_OP_STREAM_POST\s0\fR" 4
.IX Item "ASN1_OP_STREAM_POST"
Invoked immediately after streaming the \fB\s-1ASN1_VALUE\s0\fR data using indefinite
length encoding. The \fIexarg\fR argument will be a pointer to a \fB\s-1ASN1_STREAM_ARG\s0\fR
structure (see below).
.IP "\fB\s-1ASN1_OP_DETACHED_PRE\s0\fR" 4
.IX Item "ASN1_OP_DETACHED_PRE"
Invoked immediately prior to processing the \fB\s-1ASN1_VALUE\s0\fR data as a \*(L"detached\*(R"
value (as used in \s-1CMS\s0 and \s-1PKCS7\s0). The \fIexarg\fR argument will be a pointer to a
\&\fB\s-1ASN1_STREAM_ARG\s0\fR structure (see below).
.IP "\fB\s-1ASN1_OP_DETACHED_POST\s0\fR" 4
.IX Item "ASN1_OP_DETACHED_POST"
Invoked immediately after processing the \fB\s-1ASN1_VALUE\s0\fR data as a \*(L"detached\*(R"
value (as used in \s-1CMS\s0 and \s-1PKCS7\s0). The \fIexarg\fR argument will be a pointer to a
\&\fB\s-1ASN1_STREAM_ARG\s0\fR structure (see below).
.IP "\fB\s-1ASN1_OP_DUP_PRE\s0\fR" 4
.IX Item "ASN1_OP_DUP_PRE"
Invoked immediate prior to an \s-1ASN1_VALUE\s0 being duplicated via a call to
\&\fBASN1_item_dup()\fR.
.IP "\fB\s-1ASN1_OP_DUP_POST\s0\fR" 4
.IX Item "ASN1_OP_DUP_POST"
Invoked immediate after to an \s-1ASN1_VALUE\s0 has been duplicated via a call to
\&\fBASN1_item_dup()\fR.
.IP "\fB\s-1ASN1_OP_GET0_LIBCTX\s0\fR" 4
.IX Item "ASN1_OP_GET0_LIBCTX"
Invoked in order to obtain the \fB\s-1OSSL_LIB_CTX\s0\fR associated with an \fB\s-1ASN1_VALUE\s0\fR
if any. A pointer to an \fB\s-1OSSL_LIB_CTX\s0\fR should be stored in \fI*exarg\fR if such
a value exists.
.IP "\fB\s-1ASN1_OP_GET0_PROPQ\s0\fR" 4
.IX Item "ASN1_OP_GET0_PROPQ"
Invoked in order to obtain the property query string associated with an
\&\fB\s-1ASN1_VALUE\s0\fR if any. A pointer to the property query string should be stored in
\&\fI*exarg\fR if such a value exists.
.PP
An \fB\s-1ASN1_PRINT_ARG\s0\fR object is used during processing of \fB\s-1ASN1_OP_PRINT_PRE\s0\fR
and \fB\s-1ASN1_OP_PRINT_POST\s0\fR callback operations. It contains the following
information.
.IP "\fIout\fR" 4
.IX Item "out"
The \fB\s-1BIO\s0\fR being used to print the data out.
.IP "\fIndef_bio\fR" 4
.IX Item "ndef_bio"
The current number of indent spaces that should be used for printing this data.
.IP "\fIpctx\fR" 4
.IX Item "pctx"
The context for the \fB\s-1ASN1_PCTX\s0\fR operation.
.PP
An \fB\s-1ASN1_STREAM_ARG\s0\fR object is used during processing of \fB\s-1ASN1_OP_STREAM_PRE\s0\fR,
\&\fB\s-1ASN1_OP_STREAM_POST\s0\fR, \fB\s-1ASN1_OP_DETACHED_PRE\s0\fR and \fB\s-1ASN1_OP_DETACHED_POST\s0\fR
callback operations. It contains the following information.
.IP "\fIout\fR" 4
.IX Item "out"
The \fB\s-1BIO\s0\fR to stream through
.IP "\fIndef_bio\fR" 4
.IX Item "ndef_bio"
The \fB\s-1BIO\s0\fR with filters appended
.IP "\fIboundary\fR" 4
.IX Item "boundary"
The streaming I/O boundary.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
The callbacks return 0 on error and a positive value on success. Some operations
require specific positive success values as noted above.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBASN1_item_new_ex\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
The \fBASN1_aux_const_cb()\fR callback and the \fB\s-1ASN1_OP_GET0_LIBCTX\s0\fR and
\&\fB\s-1ASN1_OP_GET0_PROPQ\s0\fR operation types were added in OpenSSL 3.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2021\-2025 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

382
openssl-3.4.2/doc/man/man3/ASN1_generate_nconf.3
View File

@@ -1,382 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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_GENERATE_NCONF 3ossl"
.TH ASN1_GENERATE_NCONF 3ossl "2025-07-01" "3.4.2" "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_generate_nconf, ASN1_generate_v3 \- ASN1 string generation functions
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/asn1.h>
\&
\& ASN1_TYPE *ASN1_generate_nconf(const char *str, CONF *nconf);
\& ASN1_TYPE *ASN1_generate_v3(const char *str, X509V3_CTX *cnf);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
These functions generate the \s-1ASN1\s0 encoding of a string
in an \fB\s-1ASN1_TYPE\s0\fR structure.
.PP
\&\fIstr\fR contains the string to encode. \fInconf\fR or \fIcnf\fR contains
the optional configuration information where additional strings
will be read from. \fInconf\fR will typically come from a config
file whereas \fIcnf\fR is obtained from an \fBX509V3_CTX\fR structure,
which will typically be used by X509 v3 certificate extension
functions. \fIcnf\fR or \fInconf\fR can be set to \s-1NULL\s0 if no additional
configuration will be used.
.SH "GENERATION STRING FORMAT"
.IX Header "GENERATION STRING FORMAT"
The actual data encoded is determined by the string \fIstr\fR and
the configuration information. The general format of the string
is:
.IP "[\fImodifier\fR,]\fItype\fR[:\fIvalue\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 \fItype\fR,
\&\fIvalue\fR and \fImodifier\fR are explained below.
.SS "Supported Types"
.IX Subsection "Supported Types"
The supported types are listed below.
Case is not significant in the type names.
Unless otherwise specified only the \fB\s-1ASCII\s0\fR format is permissible.
.IP "\fB\s-1BOOLEAN\s0\fR, \fB\s-1BOOL\s0\fR" 4
.IX Item "BOOLEAN, BOOL"
This encodes a boolean type. The \fIvalue\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" 4
.IX Item "NULL"
Encode the \fB\s-1NULL\s0\fR type, the \fIvalue\fR string must not be present.
.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 \fIvalue\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" 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" 4
.IX Item "OBJECT, OID"
Encodes an \s-1ASN1\s0 \fB\s-1OBJECT IDENTIFIER\s0\fR, the \fIvalue\fR string can be
a short name, a long name or numerical format.
.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" 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" 4
.IX Item "OCTETSTRING, OCT"
Encodes an \s-1ASN1\s0 \fB\s-1OCTET STRING\s0\fR. \fIvalue\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 \fIvalue\fR.
.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. \fIvalue\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
can be used to specify the format of \fIvalue\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" 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. \fIvalue\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" 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. \fIvalue\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 \fIvalue\fR is absent then an empty \s-1SEQUENCE\s0
will be encoded.
.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" 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
decimal value.
.Sp
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" 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" 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" 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.
.Sp
If no format specifier is included then \fB\s-1ASCII\s0\fR is used. If \fB\s-1UTF8\s0\fR is
specified then the value string must be a valid \fB\s-1UTF8\s0\fR string. For \fB\s-1HEX\s0\fR the
output must be a set of hex digits. \fB\s-1BITLIST\s0\fR (which is only valid for a \s-1BIT
STRING\s0) is a comma separated list of the indices of the set bits, all other
bits are zero.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBASN1_generate_nconf()\fR and \fBASN1_generate_v3()\fR return the encoded
data as an \fB\s-1ASN1_TYPE\s0\fR structure or \s-1NULL\s0 if an error occurred.
.PP
The error codes that can be obtained by \fBERR_get_error\fR\|(3).
.SH "EXAMPLES"
.IX Header "EXAMPLES"
A simple IA5String:
.PP
.Vb 1
\& IA5STRING:Hello World
.Ve
.PP
An IA5String explicitly tagged:
.PP
.Vb 1
\& EXPLICIT:0,IA5STRING:Hello World
.Ve
.PP
An IA5String explicitly tagged using \s-1APPLICATION\s0 tagging:
.PP
.Vb 1
\& EXPLICIT:0A,IA5STRING:Hello World
.Ve
.PP
A \s-1BITSTRING\s0 with bits 1 and 5 set and all others zero:
.PP
.Vb 1
\& FORMAT:BITLIST,BITSTRING:1,5
.Ve
.PP
A more complex example using a config file to produce a
\&\s-1SEQUENCE\s0 consisting of a \s-1BOOL\s0 an \s-1OID\s0 and a UTF8String:
.PP
.Vb 1
\& asn1 = SEQUENCE:seq_section
\&
\& [seq_section]
\&
\& field1 = BOOLEAN:TRUE
\& field2 = OID:commonName
\& field3 = UTF8:Third field
.Ve
.PP
This example produces an RSAPrivateKey structure, this is the
key contained in the file client.pem in all OpenSSL distributions
(note: the field names such as 'coeff' are ignored and are present just
for clarity):
.PP
.Vb 3
\& asn1=SEQUENCE:private_key
\& [private_key]
\& version=INTEGER:0
\&
\& n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\e
\& D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
\&
\& e=INTEGER:0x010001
\&
\& d=INTEGER:0x6F05EAD2F27FFAEC84BEC360C4B928FD5F3A9865D0FCAAD291E2A52F4A\e
\& F810DC6373278C006A0ABBA27DC8C63BF97F7E666E27C5284D7D3B1FFFE16B7A87B51D
\&
\& p=INTEGER:0xF3929B9435608F8A22C208D86795271D54EBDFB09DDEF539AB083DA912\e
\& D4BD57
\&
\& q=INTEGER:0xC50016F89DFF2561347ED1186A46E150E28BF2D0F539A1594BBD7FE467\e
\& 46EC4F
\&
\& exp1=INTEGER:0x9E7D4326C924AFC1DEA40B45650134966D6F9DFA3A7F9D698CD4ABEA\e
\& 9C0A39B9
\&
\& exp2=INTEGER:0xBA84003BB95355AFB7C50DF140C60513D0BA51D637272E355E397779\e
\& E7B2458F
\&
\& coeff=INTEGER:0x30B9E4F2AFA5AC679F920FC83F1F2DF1BAF1779CF989447FABC2F5\e
\& 628657053A
.Ve
.PP
This example is the corresponding public key in a SubjectPublicKeyInfo
structure:
.PP
.Vb 2
\& # Start with a SEQUENCE
\& asn1=SEQUENCE:pubkeyinfo
\&
\& # pubkeyinfo contains an algorithm identifier and the public key wrapped
\& # in a BIT STRING
\& [pubkeyinfo]
\& algorithm=SEQUENCE:rsa_alg
\& pubkey=BITWRAP,SEQUENCE:rsapubkey
\&
\& # algorithm ID for RSA is just an OID and a NULL
\& [rsa_alg]
\& algorithm=OID:rsaEncryption
\& parameter=NULL
\&
\& # Actual public key: modulus and exponent
\& [rsapubkey]
\& n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\e
\& D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
\&
\& e=INTEGER:0x010001
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBERR_get_error\fR\|(3)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2002\-2021 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

247
openssl-3.4.2/doc/man/man3/ASN1_item_d2i_bio.3
View File

@@ -1,247 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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_D2I_BIO 3ossl"
.TH ASN1_ITEM_D2I_BIO 3ossl "2025-07-01" "3.4.2" "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_d2i_ex, ASN1_item_d2i, ASN1_item_d2i_bio_ex, ASN1_item_d2i_bio,
ASN1_item_d2i_fp_ex, ASN1_item_d2i_fp, ASN1_item_i2d_mem_bio,
ASN1_item_pack, ASN1_item_unpack_ex, ASN1_item_unpack
\&\- decode and encode DER\-encoded ASN.1 structures
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/asn1.h>
\&
\& ASN1_VALUE *ASN1_item_d2i_ex(ASN1_VALUE **pval, const unsigned char **in,
\& long len, const ASN1_ITEM *it,
\& OSSL_LIB_CTX *libctx, const char *propq);
\& ASN1_VALUE *ASN1_item_d2i(ASN1_VALUE **pval, const unsigned char **in,
\& long len, const ASN1_ITEM *it);
\&
\& void *ASN1_item_d2i_bio_ex(const ASN1_ITEM *it, BIO *in, void *x,
\& OSSL_LIB_CTX *libctx, const char *propq);
\& void *ASN1_item_d2i_bio(const ASN1_ITEM *it, BIO *in, void *x);
\&
\& void *ASN1_item_d2i_fp_ex(const ASN1_ITEM *it, FILE *in, void *x,
\& OSSL_LIB_CTX *libctx, const char *propq);
\& void *ASN1_item_d2i_fp(const ASN1_ITEM *it, FILE *in, void *x);
\&
\& BIO *ASN1_item_i2d_mem_bio(const ASN1_ITEM *it, const ASN1_VALUE *val);
\&
\& ASN1_STRING *ASN1_item_pack(void *obj, const ASN1_ITEM *it, ASN1_STRING **oct);
\&
\& void *ASN1_item_unpack(const ASN1_STRING *oct, const ASN1_ITEM *it);
\&
\& void *ASN1_item_unpack_ex(const ASN1_STRING *oct, const ASN1_ITEM *it,
\& OSSL_LIB_CTX *libctx, const char *propq);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBASN1_item_d2i_ex()\fR decodes the contents of the data stored in \fI*in\fR of length
\&\fIlen\fR which must be a DER-encoded \s-1ASN.1\s0 structure, using the \s-1ASN.1\s0 template
\&\fIit\fR. It places the result in \fI*pval\fR unless \fIpval\fR is \s-1NULL.\s0 If \fI*pval\fR is
non-NULL on entry then the \fB\s-1ASN1_VALUE\s0\fR present there will be reused. Otherwise
a new \fB\s-1ASN1_VALUE\s0\fR will be allocated. If any algorithm fetches are required
during the process then they will use the \fB\s-1OSSL_LIB_CTX\s0\fRprovided in the
\&\fIlibctx\fR parameter and the property query string in \fIpropq\fR. See
\&\*(L"\s-1ALGORITHM FETCHING\*(R"\s0 in \fBcrypto\fR\|(7) for more information about algorithm fetching.
On exit \fI*in\fR will be updated to point to the next byte in the buffer after the
decoded structure.
.PP
\&\fBASN1_item_d2i()\fR is the same as \fBASN1_item_d2i_ex()\fR except that the default
\&\s-1OSSL_LIB_CTX\s0 is used (i.e. \s-1NULL\s0) and with a \s-1NULL\s0 property query string.
.PP
\&\fBASN1_item_d2i_bio_ex()\fR decodes the contents of its input \s-1BIO\s0 \fIin\fR,
which must be a DER-encoded \s-1ASN.1\s0 structure, using the \s-1ASN.1\s0 template \fIit\fR
and places the result in \fI*pval\fR unless \fIpval\fR is \s-1NULL.\s0
If \fIin\fR is \s-1NULL\s0 it returns \s-1NULL,\s0 else a pointer to the parsed structure. If any
algorithm fetches are required during the process then they will use the
\&\fB\s-1OSSL_LIB_CTX\s0\fR provided in the \fIlibctx\fR parameter and the property query
string in \fIpropq\fR. See \*(L"\s-1ALGORITHM FETCHING\*(R"\s0 in \fBcrypto\fR\|(7) for more information
about algorithm fetching.
.PP
\&\fBASN1_item_d2i_bio()\fR is the same as \fBASN1_item_d2i_bio_ex()\fR except that the
default \fB\s-1OSSL_LIB_CTX\s0\fR is used (i.e. \s-1NULL\s0) and with a \s-1NULL\s0 property query
string.
.PP
\&\fBASN1_item_d2i_fp_ex()\fR is the same as \fBASN1_item_d2i_bio_ex()\fR except that a \s-1FILE\s0
pointer is provided instead of a \s-1BIO.\s0
.PP
\&\fBASN1_item_d2i_fp()\fR is the same as \fBASN1_item_d2i_fp_ex()\fR except that the
default \fB\s-1OSSL_LIB_CTX\s0\fR is used (i.e. \s-1NULL\s0) and with a \s-1NULL\s0 property query
string.
.PP
\&\fBASN1_item_i2d_mem_bio()\fR encodes the given \s-1ASN.1\s0 value \fIval\fR
using the \s-1ASN.1\s0 template \fIit\fR and returns the result in a memory \s-1BIO.\s0
.PP
\&\fBASN1_item_pack()\fR encodes the given \s-1ASN.1\s0 value in \fIobj\fR using the
\&\s-1ASN.1\s0 template \fIit\fR and returns an \fB\s-1ASN1_STRING\s0\fR object. If the passed in
\&\fI*oct\fR is not \s-1NULL\s0 then this is used to store the returned result, otherwise
a new \fB\s-1ASN1_STRING\s0\fR object is created. If \fIoct\fR is not \s-1NULL\s0 and \fI*oct\fR is \s-1NULL\s0
then the returned return is also set into \fI*oct\fR. If there is an error the optional
passed in \fB\s-1ASN1_STRING\s0\fR will not be freed, but the previous value may be cleared when
ASN1_STRING_set0(*oct, \s-1NULL, 0\s0) is called internally.
.PP
\&\fBASN1_item_unpack()\fR uses \fBASN1_item_d2i()\fR to decode the DER-encoded \fB\s-1ASN1_STRING\s0\fR
\&\fIoct\fR using the \s-1ASN.1\s0 template \fIit\fR.
.PP
\&\fBASN1_item_unpack_ex()\fR is similar to \fBASN1_item_unpack()\fR, but uses \fBASN1_item_d2i_ex()\fR so
that the \fIlibctx\fR and \fIpropq\fR can be used when doing algorithm fetching.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBASN1_item_d2i_bio()\fR, \fBASN1_item_unpack_ex()\fR and \fBASN1_item_unpack()\fR return a pointer to
an \fB\s-1ASN1_VALUE\s0\fR or \s-1NULL\s0 on error.
.PP
\&\fBASN1_item_i2d_mem_bio()\fR returns a pointer to a memory \s-1BIO\s0 or \s-1NULL\s0 on error.
.PP
\&\fBASN1_item_pack()\fR returns a pointer to an \fB\s-1ASN1_STRING\s0\fR or \s-1NULL\s0 on error.
.SH "HISTORY"
.IX Header "HISTORY"
The functions \fBASN1_item_d2i_ex()\fR, \fBASN1_item_d2i_bio_ex()\fR, \fBASN1_item_d2i_fp_ex()\fR
and \fBASN1_item_i2d_mem_bio()\fR were added in OpenSSL 3.0.
.PP
The function \fBASN1_item_unpack_ex()\fR was added in OpenSSL 3.2.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2021\-2023 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

177
openssl-3.4.2/doc/man/man3/ASN1_item_new.3
View File

@@ -1,177 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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_NEW 3ossl"
.TH ASN1_ITEM_NEW 3ossl "2025-07-01" "3.4.2" "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_new_ex, ASN1_item_new
\&\- create new ASN.1 values
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/asn1.h>
\&
\& ASN1_VALUE *ASN1_item_new_ex(const ASN1_ITEM *it, OSSL_LIB_CTX *libctx,
\& const char *propq);
\& ASN1_VALUE *ASN1_item_new(const ASN1_ITEM *it);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBASN1_item_new_ex()\fR creates a new \fB\s-1ASN1_VALUE\s0\fR structure based on the
\&\fB\s-1ASN1_ITEM\s0\fR template given in the \fIit\fR parameter. If any algorithm fetches are
required during the process then they will use the \fB\s-1OSSL_LIB_CTX\s0\fR provided in
the \fIlibctx\fR parameter and the property query string in \fIpropq\fR. See
\&\*(L"\s-1ALGORITHM FETCHING\*(R"\s0 in \fBcrypto\fR\|(7) for more information about algorithm fetching.
.PP
\&\fBASN1_item_new()\fR is the same as \fBASN1_item_new_ex()\fR except that the default
\&\fB\s-1OSSL_LIB_CTX\s0\fR is used (i.e. \s-1NULL\s0) and with a \s-1NULL\s0 property query string.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBASN1_item_new_ex()\fR and \fBASN1_item_new()\fR return a pointer to the newly created
\&\fB\s-1ASN1_VALUE\s0\fR or \s-1NULL\s0 on error.
.SH "HISTORY"
.IX Header "HISTORY"
The function \fBASN1_item_new_ex()\fR was added in OpenSSL 3.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

357
openssl-3.4.2/doc/man/man3/ASN1_item_sign.3
View File

@@ -1,357 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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_SIGN 3ossl"
.TH ASN1_ITEM_SIGN 3ossl "2025-07-01" "3.4.2" "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_sign, ASN1_item_sign_ex, ASN1_item_sign_ctx,
ASN1_item_verify, ASN1_item_verify_ex, ASN1_item_verify_ctx \-
ASN1 sign and verify
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/x509.h>
\&
\& int ASN1_item_sign_ex(const ASN1_ITEM *it, X509_ALGOR *algor1,
\& X509_ALGOR *algor2, ASN1_BIT_STRING *signature,
\& const void *data, const ASN1_OCTET_STRING *id,
\& EVP_PKEY *pkey, const EVP_MD *md, OSSL_LIB_CTX *libctx,
\& const char *propq);
\&
\& int ASN1_item_sign(const ASN1_ITEM *it, X509_ALGOR *algor1, X509_ALGOR *algor2,
\& ASN1_BIT_STRING *signature, const void *data,
\& EVP_PKEY *pkey, const EVP_MD *md);
\&
\& int ASN1_item_sign_ctx(const ASN1_ITEM *it, X509_ALGOR *algor1,
\& X509_ALGOR *algor2, ASN1_BIT_STRING *signature,
\& const void *data, EVP_MD_CTX *ctx);
\&
\& int ASN1_item_verify_ex(const ASN1_ITEM *it, const X509_ALGOR *alg,
\& const ASN1_BIT_STRING *signature, const void *data,
\& const ASN1_OCTET_STRING *id, EVP_PKEY *pkey,
\& OSSL_LIB_CTX *libctx, const char *propq);
\&
\& int ASN1_item_verify(const ASN1_ITEM *it, const X509_ALGOR *alg,
\& const ASN1_BIT_STRING *signature, const void *data,
\& EVP_PKEY *pkey);
\&
\& int ASN1_item_verify_ctx(const ASN1_ITEM *it, const X509_ALGOR *alg,
\& const ASN1_BIT_STRING *signature, const void *data,
\& EVP_MD_CTX *ctx);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBASN1_item_sign_ex()\fR is used to sign arbitrary \s-1ASN1\s0 data using a data object
\&\fIdata\fR, the \s-1ASN.1\s0 structure \fIit\fR, private key \fIpkey\fR and message digest \fImd\fR.
The data that is signed is formed by taking the data object in \fIdata\fR and
converting it to der format using the \s-1ASN.1\s0 structure \fIit\fR.
The \fIdata\fR that will be signed, and a structure containing the signature may
both have a copy of the \fBX509_ALGOR\fR. The \fBASN1_item_sign_ex()\fR function will
write the correct \fBX509_ALGOR\fR to the structs based on the algorithms and
parameters that have been set up. If one of \fIalgor1\fR or \fIalgor2\fR points to the
\&\fBX509_ALGOR\fR of the \fIdata\fR to be signed, then that \fBX509_ALGOR\fR will first be
written before the signature is generated.
Examples of valid values that can be used by the \s-1ASN.1\s0 structure \fIit\fR are
ASN1_ITEM_rptr(X509_CINF), ASN1_ITEM_rptr(X509_REQ_INFO) and
ASN1_ITEM_rptr(X509_CRL_INFO).
The \fB\s-1OSSL_LIB_CTX\s0\fR specified in \fIlibctx\fR and the property query string
specified in \fIprops\fR are used when searching for algorithms in providers.
The generated signature is set into \fIsignature\fR.
The optional parameter \fIid\fR can be \s-1NULL,\s0 but can be set for special key types.
See \fBEVP_PKEY_CTX_set1_id()\fR for further info. The output parameters <algor1> and
\&\fIalgor2\fR are ignored if they are \s-1NULL.\s0
.PP
\&\fBASN1_item_sign()\fR is similar to \fBASN1_item_sign_ex()\fR but uses default values of
\&\s-1NULL\s0 for the \fIid\fR, \fIlibctx\fR and \fIpropq\fR.
.PP
\&\fBASN1_item_sign_ctx()\fR is similar to \fBASN1_item_sign()\fR but uses the parameters
contained in digest context \fIctx\fR.
.PP
\&\fBASN1_item_verify_ex()\fR is used to verify the signature \fIsignature\fR of internal
data \fIdata\fR using the public key \fIpkey\fR and algorithm identifier \fIalg\fR.
The data that is verified is formed by taking the data object in \fIdata\fR and
converting it to der format using the \s-1ASN.1\s0 structure \fIit\fR.
The \fB\s-1OSSL_LIB_CTX\s0\fR specified in \fIlibctx\fR and the property query string
specified in \fIprops\fR are used when searching for algorithms in providers.
The optional parameter \fIid\fR can be \s-1NULL,\s0 but can be set for special key types.
See \fBEVP_PKEY_CTX_set1_id()\fR for further info.
.PP
\&\fBASN1_item_verify()\fR is similar to \fBASN1_item_verify_ex()\fR but uses default values of
\&\s-1NULL\s0 for the \fIid\fR, \fIlibctx\fR and \fIpropq\fR.
.PP
\&\fBASN1_item_verify_ctx()\fR is similar to \fBASN1_item_verify()\fR but uses the parameters
contained in digest context \fIctx\fR.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
All sign functions return the size of the signature in bytes for success and
zero for failure.
.PP
All verify functions return 1 if the signature is valid and 0 if the signature
check fails. If the signature could not be checked at all because it was
ill-formed or some other error occurred then \-1 is returned.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
In the following example a 'MyObject' object is signed using the key contained
in an \s-1EVP_MD_CTX.\s0 The signature is written to MyObject.signature. The object is
then output in \s-1DER\s0 format and then loaded back in and verified.
.PP
.Vb 2
\& #include <openssl/x509.h>
\& #include <openssl/asn1t.h>
\&
\& /* An object used to store the ASN1 data fields that will be signed */
\& typedef struct MySignInfoObject_st
\& {
\& ASN1_INTEGER *version;
\& X509_ALGOR sig_alg;
\& } MySignInfoObject;
\&
\& DECLARE_ASN1_FUNCTIONS(MySignInfoObject)
\& /*
\& * A higher level object containing the ASN1 fields, signature alg and
\& * output signature.
\& */
\& typedef struct MyObject_st
\& {
\& MySignInfoObject info;
\& X509_ALGOR sig_alg;
\& ASN1_BIT_STRING *signature;
\& } MyObject;
\&
\& DECLARE_ASN1_FUNCTIONS(MyObject)
\&
\& /* The ASN1 definition of MySignInfoObject */
\& ASN1_SEQUENCE_cb(MySignInfoObject, NULL) = {
\& ASN1_SIMPLE(MySignInfoObject, version, ASN1_INTEGER)
\& ASN1_EMBED(MySignInfoObject, sig_alg, X509_ALGOR),
\& } ASN1_SEQUENCE_END_cb(MySignInfoObject, MySignInfoObject)
\&
\& /* new, free, d2i & i2d functions for MySignInfoObject */
\& IMPLEMENT_ASN1_FUNCTIONS(MySignInfoObject)
\&
\& /* The ASN1 definition of MyObject */
\& ASN1_SEQUENCE_cb(MyObject, NULL) = {
\& ASN1_EMBED(MyObject, info, MySignInfoObject),
\& ASN1_EMBED(MyObject, sig_alg, X509_ALGOR),
\& ASN1_SIMPLE(MyObject, signature, ASN1_BIT_STRING)
\& } ASN1_SEQUENCE_END_cb(MyObject, MyObject)
\&
\& /* new, free, d2i & i2d functions for MyObject */
\& IMPLEMENT_ASN1_FUNCTIONS(MyObject)
\&
\& int test_asn1_item_sign_verify(const char *mdname, EVP_PKEY *pkey, long version)
\& {
\& int ret = 0;
\& unsigned char *obj_der = NULL;
\& const unsigned char *p = NULL;
\& MyObject *obj = NULL, *loaded_obj = NULL;
\& const ASN1_ITEM *it = ASN1_ITEM_rptr(MySignInfoObject);
\& EVP_MD_CTX *sctx = NULL, *vctx = NULL;
\& int len;
\&
\& /* Create MyObject and set its version */
\& obj = MyObject_new();
\& if (obj == NULL)
\& goto err;
\& if (!ASN1_INTEGER_set(obj\->info.version, version))
\& goto err;
\&
\& /* Set the key and digest used for signing */
\& sctx = EVP_MD_CTX_new();
\& if (sctx == NULL
\& || !EVP_DigestSignInit_ex(sctx, NULL, mdname, NULL, NULL, pkey))
\& goto err;
\&
\& /*
\& * it contains the mapping between ASN.1 data and an object MySignInfoObject
\& * obj\->info is the \*(AqMySignInfoObject\*(Aq object that will be
\& * converted into DER data and then signed.
\& * obj\->signature will contain the output signature.
\& * obj\->sig_alg is filled with the private key\*(Aqs signing algorithm id.
\& * obj\->info.sig_alg is another copy of the signing algorithm id that sits
\& * within MyObject.
\& */
\& len = ASN1_item_sign_ctx(it, &obj\->sig_alg, &obj\->info.sig_alg,
\& obj\->signature, &obj\->info, sctx);
\& if (len <= 0
\& || X509_ALGOR_cmp(&obj\->sig_alg, &obj\->info.sig_alg) != 0)
\& goto err;
\&
\& /* Output MyObject in der form */
\& len = i2d_MyObject(obj, &obj_der);
\& if (len <= 0)
\& goto err;
\&
\& /* Set the key and digest used for verifying */
\& vctx = EVP_MD_CTX_new();
\& if (vctx == NULL
\& || !EVP_DigestVerifyInit_ex(vctx, NULL, mdname, NULL, NULL, pkey))
\& goto err;
\&
\& /* Load the der data back into an object */
\& p = obj_der;
\& loaded_obj = d2i_MyObject(NULL, &p, len);
\& if (loaded_obj == NULL)
\& goto err;
\& /* Verify the loaded object */
\& ret = ASN1_item_verify_ctx(it, &loaded_obj\->sig_alg, loaded_obj\->signature,
\& &loaded_obj\->info, vctx);
\&err:
\& OPENSSL_free(obj_der);
\& MyObject_free(loaded_obj);
\& MyObject_free(obj);
\& EVP_MD_CTX_free(sctx);
\& EVP_MD_CTX_free(vctx);
\& return ret;
\& }
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBX509_sign\fR\|(3),
\&\fBX509_verify\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fBASN1_item_sign_ex()\fR and \fBASN1_item_verify_ex()\fR were added in OpenSSL 3.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2020\-2022 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

349
openssl-3.4.2/doc/man/man3/ASYNC_WAIT_CTX_new.3
View File

@@ -1,349 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 3ossl"
.TH ASYNC_WAIT_CTX_NEW 3ossl "2025-07-01" "3.4.2" "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,
ASYNC_WAIT_CTX_set_callback, ASYNC_WAIT_CTX_get_callback,
ASYNC_WAIT_CTX_set_status, ASYNC_WAIT_CTX_get_status, ASYNC_callback_fn,
ASYNC_STATUS_UNSUPPORTED, ASYNC_STATUS_ERR, ASYNC_STATUS_OK,
ASYNC_STATUS_EAGAIN
\&\- functions to manage waiting for asynchronous jobs to complete
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/async.h>
\&
\& #define ASYNC_STATUS_UNSUPPORTED 0
\& #define ASYNC_STATUS_ERR 1
\& #define ASYNC_STATUS_OK 2
\& #define ASYNC_STATUS_EAGAIN 3
\& typedef int (*ASYNC_callback_fn)(void *arg);
\& 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);
\& int ASYNC_WAIT_CTX_set_callback(ASYNC_WAIT_CTX *ctx,
\& ASYNC_callback_fn callback,
\& void *callback_arg);
\& int ASYNC_WAIT_CTX_get_callback(ASYNC_WAIT_CTX *ctx,
\& ASYNC_callback_fn *callback,
\& void **callback_arg);
\& int ASYNC_WAIT_CTX_set_status(ASYNC_WAIT_CTX *ctx, int status);
\& int ASYNC_WAIT_CTX_get_status(ASYNC_WAIT_CTX *ctx);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
For an overview of how asynchronous operations are implemented in OpenSSL see
\&\fBASYNC_start_job\fR\|(3). An \fB\s-1ASYNC_WAIT_CTX\s0\fR 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 \fB\s-1ASYNC_WAIT_CTX\s0\fR using the \fBASYNC_WAIT_CTX_new()\fR
function prior to calling \fBASYNC_start_job()\fR (see \fBASYNC_start_job\fR\|(3)). When
the job is started it is associated with the \fB\s-1ASYNC_WAIT_CTX\s0\fR for the duration
of that job. An \fB\s-1ASYNC_WAIT_CTX\s0\fR should only be used for one \fB\s-1ASYNC_JOB\s0\fR at
any one time, but can be reused after an \fB\s-1ASYNC_JOB\s0\fR has finished for a
subsequent \fB\s-1ASYNC_JOB\s0\fR. When the session is complete (e.g. the \s-1SSL\s0 connection
is closed), application code cleans up with \fBASYNC_WAIT_CTX_free()\fR.
.PP
\&\fB\s-1ASYNC_WAIT_CTX\s0\fRs can have \*(L"wait\*(R" file descriptors associated with them.
Calling \fBASYNC_WAIT_CTX_get_all_fds()\fR and passing in a pointer to an
\&\fB\s-1ASYNC_WAIT_CTX\s0\fR in the \fIctx\fR parameter will return the wait file descriptors
associated with that job in \fI*fd\fR. The number of file descriptors returned will
be stored in \fI*numfds\fR. It is the caller's responsibility to ensure that
sufficient memory has been allocated in \fI*fd\fR to receive all the file
descriptors. Calling \fBASYNC_WAIT_CTX_get_all_fds()\fR with a \s-1NULL\s0 \fIfd\fR value will
return no file descriptors but will still populate \fI*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 \fBASYNC_WAIT_CTX_get_changed_fds()\fR can be used to detect if any fds
have changed since the last call time \fBASYNC_start_job()\fR returned \fB\s-1ASYNC_PAUSE\s0\fR
(or since the \fB\s-1ASYNC_WAIT_CTX\s0\fR was created if no \fB\s-1ASYNC_PAUSE\s0\fR result has
been received). The \fInumaddfds\fR and \fInumdelfds\fR parameters will be populated
with the number of fds added or deleted respectively. \fI*addfd\fR and \fI*delfd\fR
will be populated with the list of added and deleted fds respectively. Similarly
to \fBASYNC_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
Implementers of async aware code (e.g. engines) are encouraged to return a
stable fd for the lifetime of the \fB\s-1ASYNC_WAIT_CTX\s0\fR 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 \fB\s-1ASYNC_WAIT_CTX\s0\fR from the
job via \fBASYNC_get_wait_ctx\fR\|(3) and provide a file descriptor to use for
waiting on by calling \fBASYNC_WAIT_CTX_set_wait_fd()\fR. Typically this would be done
by an engine immediately prior to calling \fBASYNC_pause_job()\fR and not by end user
code. An existing association with a file descriptor can be obtained using
\&\fBASYNC_WAIT_CTX_get_fd()\fR and cleared using \fBASYNC_WAIT_CTX_clear_fd()\fR. Both of
these functions requires a \fIkey\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 \fIcustom_data\fR parameter can be any value, and
will be returned in a subsequent call to \fBASYNC_WAIT_CTX_get_fd()\fR. The
\&\fBASYNC_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 \fB\s-1ASYNC_WAIT_CTX\s0\fR 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 \fBASYNC_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 \fBASYNC_WAIT_CTX_set_wait_fd()\fR followed by
\&\fBASYNC_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
As well as a file descriptor, user code may also be notified via a callback. The
callback and data pointers are stored within the \fB\s-1ASYNC_WAIT_CTX\s0\fR along with an
additional status field that can be used for the notification of retries from an
engine. This additional method can be used when the user thinks that a file
descriptor is too costly in terms of \s-1CPU\s0 cycles or in some context where a file
descriptor is not appropriate.
.PP
\&\fBASYNC_WAIT_CTX_set_callback()\fR sets the callback and the callback argument. The
callback will be called to notify user code when an engine completes a
cryptography operation. It is a requirement that the callback function is small
and nonblocking as it will be run in the context of a polling mechanism or an
interrupt.
.PP
\&\fBASYNC_WAIT_CTX_get_callback()\fR returns the callback set in the \fB\s-1ASYNC_WAIT_CTX\s0\fR
structure.
.PP
\&\fBASYNC_WAIT_CTX_set_status()\fR allows an engine to set the current engine status.
The possible status values are the following:
.IP "\fB\s-1ASYNC_STATUS_UNSUPPORTED\s0\fR" 4
.IX Item "ASYNC_STATUS_UNSUPPORTED"
The engine does not support the callback mechanism. This is the default value.
The engine must call \fBASYNC_WAIT_CTX_set_status()\fR to set the status to some value
other than \fB\s-1ASYNC_STATUS_UNSUPPORTED\s0\fR if it intends to enable the callback
mechanism.
.IP "\fB\s-1ASYNC_STATUS_ERR\s0\fR" 4
.IX Item "ASYNC_STATUS_ERR"
The engine has a fatal problem with this request. The user code should clean up
this session.
.IP "\fB\s-1ASYNC_STATUS_OK\s0\fR" 4
.IX Item "ASYNC_STATUS_OK"
The request has been successfully submitted.
.IP "\fB\s-1ASYNC_STATUS_EAGAIN\s0\fR" 4
.IX Item "ASYNC_STATUS_EAGAIN"
The engine has some problem which will be recovered soon, such as a buffer is
full, so user code should resume the job.
.PP
\&\fBASYNC_WAIT_CTX_get_status()\fR allows user code to obtain the current status value.
If the status is any value other than \fB\s-1ASYNC_STATUS_OK\s0\fR then the user code
should not expect to receive a callback from the engine even if one has been
set.
.PP
An example of the usage of the callback method might be the following. User
code would initiate cryptographic operations, and the engine code would dispatch
this operation to hardware, and if the dispatch is successful, then the engine
code would call \fBASYNC_pause_job()\fR to return control to the user code. After
that, user code can perform other tasks. When the hardware completes the
operation, normally it is detected by a polling function or an interrupt, as the
user code set a callback by calling \fBASYNC_WAIT_CTX_set_callback()\fR previously,
then the registered callback will be called.
.PP
\&\fBASYNC_WAIT_CTX_free()\fR frees up a single \fB\s-1ASYNC_WAIT_CTX\s0\fR object.
If the argument is \s-1NULL,\s0 nothing is done.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBASYNC_WAIT_CTX_new()\fR returns a pointer to the newly allocated \fB\s-1ASYNC_WAIT_CTX\s0\fR
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, ASYNC_WAIT_CTX_clear_fd,
ASYNC_WAIT_CTX_set_callback, ASYNC_WAIT_CTX_get_callback and
ASYNC_WAIT_CTX_set_status all return 1 on success or 0 on error.
\&\fBASYNC_WAIT_CTX_get_status()\fR returns the engine status.
.SH "NOTES"
.IX Header "NOTES"
On Windows platforms the \fI<openssl/async.h>\fR header is dependent on some
of the types customarily made available by including \fI<windows.h>\fR. 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
\&\fI<windows.h>\fR prior to \fI<openssl/async.h>\fR.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBcrypto\fR\|(7), \fBASYNC_start_job\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fBASYNC_WAIT_CTX_new()\fR, \fBASYNC_WAIT_CTX_free()\fR, \fBASYNC_WAIT_CTX_set_wait_fd()\fR,
\&\fBASYNC_WAIT_CTX_get_fd()\fR, \fBASYNC_WAIT_CTX_get_all_fds()\fR,
\&\fBASYNC_WAIT_CTX_get_changed_fds()\fR and \fBASYNC_WAIT_CTX_clear_fd()\fR
were added in OpenSSL 1.1.0.
.PP
\&\fBASYNC_WAIT_CTX_set_callback()\fR, \fBASYNC_WAIT_CTX_get_callback()\fR,
\&\fBASYNC_WAIT_CTX_set_status()\fR, and \fBASYNC_WAIT_CTX_get_status()\fR
were added in OpenSSL 3.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2016\-2024 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

501
openssl-3.4.2/doc/man/man3/ASYNC_start_job.3
View File

@@ -1,501 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 3ossl"
.TH ASYNC_START_JOB 3ossl "2025-07-01" "3.4.2" "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,
ASYNC_stack_alloc_fn, ASYNC_stack_free_fn, ASYNC_set_mem_functions, ASYNC_get_mem_functions
\&\- 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);
\&
\& typedef void *(*ASYNC_stack_alloc_fn)(size_t *num);
\& typedef void (*ASYNC_stack_free_fn)(void *addr);
\& int ASYNC_set_mem_functions(ASYNC_stack_alloc_fn alloc_fn,
\& ASYNC_stack_free_fn free_fn);
\& void ASYNC_get_mem_functions(ASYNC_stack_alloc_fn *alloc_fn,
\& ASYNC_stack_free_fn *free_fn);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
OpenSSL implements asynchronous capabilities through an \fB\s-1ASYNC_JOB\s0\fR. 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. It's OpenSSL
specific implementation of cooperative multitasking.
.PP
The creation of an \fB\s-1ASYNC_JOB\s0\fR 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 \fBASYNC_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 \fBOPENSSL_init_crypto\fR\|(3)) but may be explicitly
initiated by using \fBASYNC_cleanup_thread()\fR. No asynchronous jobs must be
outstanding for the thread when \fBASYNC_cleanup_thread()\fR is called. Failing to
ensure this will result in memory leaks.
.PP
The \fImax_size\fR argument limits the number of \fB\s-1ASYNC_JOB\s0\fRs that will be held in
the pool. If \fImax_size\fR is set to 0 then no upper limit is set. When an
\&\fB\s-1ASYNC_JOB\s0\fR is needed but there are none available in the pool already then one
will be automatically created, as long as the total of \fB\s-1ASYNC_JOB\s0\fRs managed by
the pool does not exceed \fImax_size\fR. When the pool is first initialised
\&\fIinit_size\fR \fB\s-1ASYNC_JOB\s0\fRs will be created immediately. If \fBASYNC_init_thread()\fR
is not called before the pool is first used then it will be called automatically
with a \fImax_size\fR of 0 (no upper limit) and an \fIinit_size\fR of 0 (no
\&\fB\s-1ASYNC_JOB\s0\fRs created up front).
.PP
An asynchronous job is started by calling the \fBASYNC_start_job()\fR function.
Initially \fI*job\fR should be \s-1NULL.\s0 \fIctx\fR should point to an \fB\s-1ASYNC_WAIT_CTX\s0\fR
object created through the \fBASYNC_WAIT_CTX_new\fR\|(3) function. \fIret\fR should
point to a location where the return value of the asynchronous function should
be stored on completion of the job. \fIfunc\fR represents the function that should
be started asynchronously. The data pointed to by \fIargs\fR and of size \fIsize\fR
will be copied and then passed as an argument to \fIfunc\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 \fBERR_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
\&\fBASYNC_pause_job()\fR below). A handle to the job is placed in \fI*job\fR. Other work
can be performed (if desired) and the job restarted at a later time. To restart
a job call \fBASYNC_start_job()\fR again passing the job handle in \fI*job\fR. The
\&\fIfunc\fR, \fIargs\fR and \fIsize\fR parameters will be ignored when restarting a job.
When restarting a job \fBASYNC_start_job()\fR \fBmust\fR be called from the same thread
that the job was originally started from. \fB\s-1ASYNC_WAIT_CTX\s0\fR is used to
know when a job is ready to be restarted.
.IP "\fB\s-1ASYNC_FINISH\s0\fR" 4
.IX Item "ASYNC_FINISH"
The job completed. \fI*job\fR will be \s-1NULL\s0 and the return value from \fIfunc\fR will
be placed in \fI*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). \fBASYNC_get_current_job()\fR can be used to get
a pointer to the currently executing \fB\s-1ASYNC_JOB\s0\fR. 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 \fBASYNC_start_job()\fR)
then \fBASYNC_pause_job()\fR will immediately return control to the calling
application with \fB\s-1ASYNC_PAUSE\s0\fR returned from the \fBASYNC_start_job()\fR call. A
subsequent call to ASYNC_start_job passing in the relevant \fB\s-1ASYNC_JOB\s0\fR in the
\&\fI*job\fR parameter will resume execution from the \fBASYNC_pause_job()\fR call. If
\&\fBASYNC_pause_job()\fR is called whilst not within the context of a job then no
action is taken and \fBASYNC_pause_job()\fR returns immediately.
.PP
\&\fBASYNC_get_wait_ctx()\fR can be used to get a pointer to the \fB\s-1ASYNC_WAIT_CTX\s0\fR
for the \fIjob\fR (see \fBASYNC_WAIT_CTX_new\fR\|(3)).
\&\fB\s-1ASYNC_WAIT_CTX\s0\fRs contain two different ways to notify
applications that a job is ready to be resumed. One is a \*(L"wait\*(R" file
descriptor, and the other is a \*(L"callback\*(R" mechanism.
.PP
The \*(L"wait\*(R" file descriptor associated with \fB\s-1ASYNC_WAIT_CTX\s0\fR is used for
applications to wait for the file descriptor to be ready for \*(L"read\*(R" using a
system function call such as \fBselect\fR\|(2) or \fBpoll\fR\|(2) (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
\&\fB\s-1ASYNC_WAIT_CTX\s0\fRs also have a \*(L"callback\*(R" mechanism to notify applications. The
callback is set by an application, and it will be automatically called when an
engine completes a cryptography operation, so that the application can resume
the paused work flow without polling. An engine could be written to look whether
the callback has been set. If it has then it would use the callback mechanism
in preference to the file descriptor notifications. If a callback is not set
then the engine may use file descriptor based notifications. Please note that
not all engines may support the callback mechanism, so the callback may not be
used even if it has been set. See \fBASYNC_WAIT_CTX_new()\fR for more details.
.PP
The \fBASYNC_block_pause()\fR function will prevent the currently active job from
pausing. The block will remain in place until a subsequent call to
\&\fBASYNC_unblock_pause()\fR. These functions can be nested, e.g. if you call
\&\fBASYNC_block_pause()\fR twice then you must call \fBASYNC_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 \fB\s-1ASYNC_JOB\s0\fR
an application acquires a lock. It then calls some cryptographic function which
invokes \fBASYNC_pause_job()\fR. This returns control back to the code that created
the \fB\s-1ASYNC_JOB\s0\fR. If that code then attempts to acquire the same lock before
resuming the original job then a deadlock can occur. By calling
\&\fBASYNC_block_pause()\fR immediately after acquiring the lock and
\&\fBASYNC_unblock_pause()\fR immediately before releasing it then this situation cannot
occur.
.PP
Some platforms cannot support async operations. The \fBASYNC_is_capable()\fR function
can be used to detect whether the current platform is async capable or not.
.PP
Custom memory allocation functions are supported for the \s-1POSIX\s0 platform.
Custom memory allocation functions allow alternative methods of allocating
stack memory such as mmap, or using stack memory from the current thread.
Using an ASYNC_stack_alloc_fn callback also allows manipulation of the stack
size, which defaults to 32k.
The stack size can be altered by allocating a stack of a size different to
the requested size, and passing back the new stack size in the callback's \fI*num\fR
parameter.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
ASYNC_init_thread returns 1 on success or 0 otherwise.
.PP
ASYNC_start_job returns one of \fB\s-1ASYNC_ERR\s0\fR, \fB\s-1ASYNC_NO_JOBS\s0\fR, \fB\s-1ASYNC_PAUSE\s0\fR or
\&\fB\s-1ASYNC_FINISH\s0\fR 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 \fB\s-1ASYNC_JOB\s0\fR then this is counted as success so 1
is returned.
.PP
ASYNC_get_current_job returns a pointer to the currently executing \fB\s-1ASYNC_JOB\s0\fR
or \s-1NULL\s0 if not within the context of a job.
.PP
\&\fBASYNC_get_wait_ctx()\fR returns a pointer to the \fB\s-1ASYNC_WAIT_CTX\s0\fR for the job.
.PP
\&\fBASYNC_is_capable()\fR returns 1 if the current platform is async capable or 0
otherwise.
.PP
ASYNC_set_mem_functions returns 1 if custom stack allocators are supported by
the current platform and no allocations have already occurred or 0 otherwise.
.SH "NOTES"
.IX Header "NOTES"
On Windows platforms the \fI<openssl/async.h>\fR header is dependent on some
of the types customarily made available by including \fI<windows.h>\fR. 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
\&\fI<windows.h>\fR prior to \fI<openssl/async.h>\fR.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
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);
\&
\& /*
\& * Create a way to inform the calling thread when this job is ready
\& * to resume, in this example we\*(Aqre using file descriptors.
\& * For offloading the task to an asynchronous ENGINE it\*(Aqs not necessary,
\& * the ENGINE should handle that internally.
\& */
\&
\& 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 (like a network read being ready,
\& * disk access being finished, or some hardware offload operation
\& * completing) 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 just before calling a blocking
\& * method. The main thread will wait until pipefds[0] is ready
\& * for reading before returning control to this thread.
\& */
\& ASYNC_pause_job();
\&
\& /* Perform the blocking call (it won\*(Aqt block with this example code) */
\& 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;
\& }
\&
\& /* Get the file descriptor we can use to wait for the job
\& * to be ready to be woken up
\& */
\& 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);
\&
\& /* Wait for the job to be ready for wakeup */
\& 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"
\&\fBcrypto\fR\|(7), \fBERR_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, \fBASYNC_get_wait_ctx()\fR,
\&\fBASYNC_block_pause()\fR, \fBASYNC_unblock_pause()\fR and \fBASYNC_is_capable()\fR were first
added in OpenSSL 1.1.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2015\-2024 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

263
openssl-3.4.2/doc/man/man3/BF_encrypt.3
View File

@@ -1,263 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 "BF_ENCRYPT 3ossl"
.TH BF_ENCRYPT 3ossl "2025-07-01" "3.4.2" "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"
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
\& #include <openssl/blowfish.h>
.Ve
.PP
The following functions have been deprecated since OpenSSL 3.0, and can be
hidden entirely by defining \fB\s-1OPENSSL_API_COMPAT\s0\fR with a suitable version value,
see \fBopenssl_user_macros\fR\|(7):
.PP
.Vb 1
\& void BF_set_key(BF_KEY *key, int len, const unsigned char *data);
\&
\& void BF_ecb_encrypt(const unsigned char *in, unsigned char *out,
\& BF_KEY *key, int enc);
\& void BF_cbc_encrypt(const unsigned char *in, unsigned char *out,
\& long length, BF_KEY *schedule,
\& unsigned char *ivec, int enc);
\& void BF_cfb64_encrypt(const unsigned char *in, unsigned char *out,
\& long length, BF_KEY *schedule,
\& unsigned char *ivec, int *num, int enc);
\& void BF_ofb64_encrypt(const unsigned char *in, unsigned char *out,
\& long length, BF_KEY *schedule,
\& unsigned char *ivec, int *num);
\& const char *BF_options(void);
\&
\& void BF_encrypt(BF_LONG *data, const BF_KEY *key);
\& void BF_decrypt(BF_LONG *data, const BF_KEY *key);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
All of the functions described on this page are deprecated. Applications should
instead use \fBEVP_EncryptInit_ex\fR\|(3), \fBEVP_EncryptUpdate\fR\|(3) and
\&\fBEVP_EncryptFinal_ex\fR\|(3) or the equivalently named decrypt functions.
.PP
This library implements the Blowfish cipher, which was invented and described
by Counterpane (see http://www.counterpane.com/blowfish.html ).
.PP
Blowfish is a block cipher that operates on 64 bit (8 byte) blocks of data.
It uses a variable size key, but typically, 128 bit (16 byte) keys are
considered good for strong encryption. Blowfish can be used in the same
modes as \s-1DES\s0 (see \fBdes_modes\fR\|(7)). Blowfish is currently one
of the faster block ciphers. It is quite a bit faster than \s-1DES,\s0 and much
faster than \s-1IDEA\s0 or \s-1RC2.\s0
.PP
Blowfish consists of a key setup phase and the actual encryption or decryption
phase.
.PP
\&\fBBF_set_key()\fR sets up the \fB\s-1BF_KEY\s0\fR \fBkey\fR using the \fBlen\fR bytes long key
at \fBdata\fR.
.PP
\&\fBBF_ecb_encrypt()\fR is the basic Blowfish encryption and decryption function.
It encrypts or decrypts the first 64 bits of \fBin\fR using the key \fBkey\fR,
putting the result in \fBout\fR. \fBenc\fR decides if encryption (\fB\s-1BF_ENCRYPT\s0\fR)
or decryption (\fB\s-1BF_DECRYPT\s0\fR) shall be performed. The vector pointed at by
\&\fBin\fR and \fBout\fR must be 64 bits in length, no less. If they are larger,
everything after the first 64 bits is ignored.
.PP
The mode functions \fBBF_cbc_encrypt()\fR, \fBBF_cfb64_encrypt()\fR and \fBBF_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
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
\&\fBivec\fR is simply initialized to zero.
\&\fBBF_cbc_encrypt()\fR operates on data that is a multiple of 8 bytes long, while
\&\fBBF_cfb64_encrypt()\fR and \fBBF_ofb64_encrypt()\fR are used to encrypt a variable
number of bytes (the amount does not have to be an exact multiple of 8). The
purpose of the latter two is to simulate stream ciphers, and therefore, they
need the parameter \fBnum\fR, which is a pointer to an integer where the current
offset in \fBivec\fR is stored between calls. This integer must be initialized
to zero when \fBivec\fR is initialized.
.PP
\&\fBBF_cbc_encrypt()\fR is the Cipher Block Chaining function for Blowfish. It
encrypts or decrypts the 64 bits chunks of \fBin\fR using the key \fBschedule\fR,
putting the result in \fBout\fR. \fBenc\fR decides if encryption (\s-1BF_ENCRYPT\s0) or
decryption (\s-1BF_DECRYPT\s0) shall be performed. \fBivec\fR must point at an 8 byte
long initialization vector.
.PP
\&\fBBF_cfb64_encrypt()\fR is the \s-1CFB\s0 mode for Blowfish with 64 bit feedback.
It encrypts or decrypts the bytes in \fBin\fR using the key \fBschedule\fR,
putting the result in \fBout\fR. \fBenc\fR decides if encryption (\fB\s-1BF_ENCRYPT\s0\fR)
or decryption (\fB\s-1BF_DECRYPT\s0\fR) shall be performed. \fBivec\fR must point at an
8 byte long initialization vector. \fBnum\fR must point at an integer which must
be initially zero.
.PP
\&\fBBF_ofb64_encrypt()\fR is the \s-1OFB\s0 mode for Blowfish with 64 bit feedback.
It uses the same parameters as \fBBF_cfb64_encrypt()\fR, which must be initialized
the same way.
.PP
\&\fBBF_encrypt()\fR and \fBBF_decrypt()\fR are the lowest level functions for Blowfish
encryption. They encrypt/decrypt the first 64 bits of the vector pointed by
\&\fBdata\fR, using the key \fBkey\fR. These functions should not be used unless you
implement 'modes' of Blowfish. The alternative is to use \fBBF_ecb_encrypt()\fR.
If you still want to use these functions, you should be aware that they take
each 32\-bit chunk in host-byte order, which is little-endian on little-endian
platforms and big-endian on big-endian ones.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
None of the functions presented here return any value.
.SH "NOTE"
.IX Header "NOTE"
Applications should use the higher level functions
\&\fBEVP_EncryptInit\fR\|(3) etc. instead of calling these
functions directly.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBEVP_EncryptInit\fR\|(3),
\&\fBdes_modes\fR\|(7)
.SH "HISTORY"
.IX Header "HISTORY"
All of these functions were deprecated in OpenSSL 3.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

271
openssl-3.4.2/doc/man/man3/BIO_ADDR.3
View File

@@ -1,271 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 3ossl"
.TH BIO_ADDR 3ossl "2025-07-01" "3.4.2" "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_copy, BIO_ADDR_dup, 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);
\& int BIO_ADDR_copy(BIO_ADDR *dst, const BIO_ADDR *src);
\& BIO_ADDR *BIO_ADDR_dup(const BIO_ADDR *ap);
\& void BIO_ADDR_free(BIO_ADDR *ap);
\& 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
\&\fBBIO_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
\&\fBBIO_accept_ex()\fR.
.PP
\&\fBBIO_ADDR_copy()\fR copies the contents of \fBsrc\fR into \fBdst\fR. Neither \fBsrc\fR or
\&\fBdst\fR can be \s-1NULL.\s0
.PP
\&\fBBIO_ADDR_dup()\fR creates a new \fB\s-1BIO_ADDR\s0\fR, with a copy of the
address data in \fBap\fR.
.PP
\&\fBBIO_ADDR_free()\fR frees a \fB\s-1BIO_ADDR\s0\fR created with \fBBIO_ADDR_new()\fR
or \fBBIO_ADDR_dup()\fR. If the argument is \s-1NULL,\s0 nothing is done.
.PP
\&\fBBIO_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
\&\fBBIO_ADDR_rawmake()\fR takes a protocol \fBfamily\fR, a 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 \fBstrlen()\fR).
Read on about the addresses in \*(L"\s-1RAW ADDRESSES\*(R"\s0 below.
.PP
\&\fBBIO_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
\&\fBBIO_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 \fBstrlen()\fR).
Read on about the addresses in \*(L"\s-1RAW ADDRESSES\*(R"\s0 below.
.PP
\&\fBBIO_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
\&\fBBIO_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 \fBOPENSSL_free()\fR.
.PP
\&\fBBIO_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 \fBOPENSSL_free()\fR.
.PP
\&\fBBIO_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 \fBOPENSSL_free()\fR.
.SH "RAW ADDRESSES"
.IX Header "RAW ADDRESSES"
Both \fBBIO_ADDR_rawmake()\fR and \fBBIO_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 \fBBIO_ADDR_hostname_string()\fR,
\&\fBBIO_ADDR_service_string()\fR and \fBBIO_ADDR_path_string()\fR will
return \fB\s-1NULL\s0\fR on error and leave an error indication on the
OpenSSL error stack.
.PP
\&\fBBIO_ADDR_copy()\fR returns 1 on success or 0 on error.
.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"
\&\fBBIO_connect\fR\|(3), \fBBIO_s_connect\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fBBIO_ADDR_copy()\fR and \fBBIO_ADDR_dup()\fR were added in OpenSSL 3.2.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2016\-2024 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

244
openssl-3.4.2/doc/man/man3/BIO_ADDRINFO.3
View File

@@ -1,244 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 3ossl"
.TH BIO_ADDRINFO 3ossl "2025-07-01" "3.4.2" "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 *host, 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
\&\fBBIO_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, \fBBIO_lookup_ex()\fR will ignore the \fBservice\fR
parameter and expects the \fBhost\fR parameter to hold the path to the socket file.
.PP
\&\fBBIO_lookup()\fR does the same as \fBBIO_lookup_ex()\fR but does not provide the ability
to select based on the protocol (any protocol may be returned).
.PP
\&\fBBIO_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
\&\fBBIO_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
\&\fBBIO_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
\&\fBBIO_ADDRINFO_address()\fR returns the underlying \fB\s-1BIO_ADDR\s0\fR
of the given \fB\s-1BIO_ADDRINFO\s0\fR.
.PP
\&\fBBIO_ADDRINFO_next()\fR returns the next \fB\s-1BIO_ADDRINFO\s0\fR in the chain
from the given one.
.PP
\&\fBBIO_ADDRINFO_free()\fR frees the chain of \fB\s-1BIO_ADDRINFO\s0\fR starting
with the given one. If the argument is \s-1NULL,\s0 nothing is done.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBBIO_lookup_ex()\fR and \fBBIO_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 \fBBIO_lookup_ex()\fR implementation uses the platform provided \fBgetaddrinfo()\fR
function. On Linux it is known that specifying 0 for the protocol will not
return any \s-1SCTP\s0 based addresses when calling \fBgetaddrinfo()\fR. Therefore, if an \s-1SCTP\s0
address is required then the \fBprotocol\fR parameter to \fBBIO_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 \fBBIO_lookup_ex()\fR function was added in OpenSSL 1.1.1.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2016\-2024 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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
openssl-3.4.2/doc/man/man3/BIO_connect.3
View File

@@ -1,249 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 3ossl"
.TH BIO_CONNECT 3ossl "2025-07-01" "3.4.2" "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"
\&\fBBIO_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
\&\fBBIO_bind()\fR binds the source address and service to a socket and
may be useful before calling \fBBIO_connect()\fR. The options may include
\&\fB\s-1BIO_SOCK_REUSEADDR\s0\fR, which is described in \*(L"\s-1FLAGS\*(R"\s0 below.
.PP
\&\fBBIO_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
\&\fBBIO_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
\&\fBBIO_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
\&\fBBIO_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 nonblocking 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.
.IP "\s-1BIO_SOCK_TFO\s0" 4
.IX Item "BIO_SOCK_TFO"
Enables \s-1TCP\s0 Fast Open on the socket. Uses appropriate APIs on
supported operating systems, including Linux, macOS and FreeBSD. Can
be used with \fBBIO_connect()\fR, \fBBIO_set_conn_mode()\fR, \fBBIO_set_bind_mode()\fR,
and \fBBIO_listen()\fR.
On Linux kernels before 4.14, use \fBBIO_set_conn_address()\fR to specify
the peer address before starting the \s-1TLS\s0 handshake.
.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"
\&\fBBIO_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
\&\fBBIO_bind()\fR, \fBBIO_connect()\fR and \fBBIO_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
\&\fBBIO_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 "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1\fBBIO_ADDR\s0\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fBBIO_gethostname()\fR, \fBBIO_get_port()\fR, \fBBIO_get_host_ip()\fR,
\&\fBBIO_get_accept_socket()\fR and \fBBIO_accept()\fR were deprecated in OpenSSL 1.1.0.
Use the functions described above instead.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2016\-2022 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

321
openssl-3.4.2/doc/man/man3/BIO_ctrl.3
View File

@@ -1,321 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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_CTRL 3ossl"
.TH BIO_CTRL 3ossl "2025-07-01" "3.4.2" "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_info_cb, BIO_get_ktls_send,
BIO_get_ktls_recv, BIO_set_conn_mode, BIO_get_conn_mode, BIO_set_tfo
\&\- BIO control operations
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bio.h>
\&
\& typedef int BIO_info_cb(BIO *b, int state, int res);
\&
\& long BIO_ctrl(BIO *bp, int cmd, long larg, void *parg);
\& long BIO_callback_ctrl(BIO *b, int cmd, BIO_info_cb *cb);
\& void *BIO_ptr_ctrl(BIO *bp, int cmd, long larg);
\& long BIO_int_ctrl(BIO *bp, int cmd, long larg, int iarg);
\&
\& int BIO_reset(BIO *b);
\& int BIO_seek(BIO *b, int ofs);
\& int BIO_tell(BIO *b);
\& int BIO_flush(BIO *b);
\& int BIO_eof(BIO *b);
\& int BIO_set_close(BIO *b, long flag);
\& int BIO_get_close(BIO *b);
\& int BIO_pending(BIO *b);
\& int BIO_wpending(BIO *b);
\& size_t BIO_ctrl_pending(BIO *b);
\& size_t BIO_ctrl_wpending(BIO *b);
\&
\& int BIO_get_info_callback(BIO *b, BIO_info_cb **cbp);
\& int BIO_set_info_callback(BIO *b, BIO_info_cb *cb);
\&
\& int BIO_get_ktls_send(BIO *b);
\& int BIO_get_ktls_recv(BIO *b);
\&
\& int BIO_set_conn_mode(BIO *b, int mode);
\& int BIO_get_conn_mode(BIO *b);
\&
\& int BIO_set_tfo(BIO *b, int onoff);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBBIO_ctrl()\fR, \fBBIO_callback_ctrl()\fR, \fBBIO_ptr_ctrl()\fR and \fBBIO_int_ctrl()\fR
are \s-1BIO\s0 \*(L"control\*(R" operations taking arguments of various types.
These functions are not normally called directly, various macros
are used instead. The standard macros are described below, macros
specific to a particular type of \s-1BIO\s0 are described in the specific
BIOs manual page as well as any special features of the standard
calls.
.PP
\&\fBBIO_reset()\fR typically resets a \s-1BIO\s0 to some initial state, in the case
of file related BIOs for example it rewinds the file pointer to the
start of the file.
.PP
\&\fBBIO_seek()\fR resets a file related \s-1BIO\s0's (that is file descriptor and
\&\s-1FILE\s0 BIOs) file position pointer to \fBofs\fR bytes from start of file.
.PP
\&\fBBIO_tell()\fR returns the current file position of a file related \s-1BIO.\s0
.PP
\&\fBBIO_flush()\fR normally writes out any internally buffered data, in some
cases it is used to signal \s-1EOF\s0 and that no more data will be written.
.PP
\&\fBBIO_eof()\fR returns 1 if the \s-1BIO\s0 has read \s-1EOF,\s0 the precise meaning of
\&\*(L"\s-1EOF\*(R"\s0 varies according to the \s-1BIO\s0 type.
.PP
\&\fBBIO_set_close()\fR sets the \s-1BIO\s0 \fBb\fR close flag to \fBflag\fR. \fBflag\fR can
take the value \s-1BIO_CLOSE\s0 or \s-1BIO_NOCLOSE.\s0 Typically \s-1BIO_CLOSE\s0 is used
in a source/sink \s-1BIO\s0 to indicate that the underlying I/O stream should
be closed when the \s-1BIO\s0 is freed.
.PP
\&\fBBIO_get_close()\fR returns the BIOs close flag.
.PP
\&\fBBIO_pending()\fR, \fBBIO_ctrl_pending()\fR, \fBBIO_wpending()\fR and \fBBIO_ctrl_wpending()\fR
return the number of pending characters in the BIOs read and write buffers.
Not all BIOs support these calls. \fBBIO_ctrl_pending()\fR and \fBBIO_ctrl_wpending()\fR
return a size_t type and are functions, \fBBIO_pending()\fR and \fBBIO_wpending()\fR are
macros which call \fBBIO_ctrl()\fR.
.PP
\&\fBBIO_get_ktls_send()\fR returns 1 if the \s-1BIO\s0 is using the Kernel \s-1TLS\s0 data-path for
sending. Otherwise, it returns zero.
\&\fBBIO_get_ktls_recv()\fR returns 1 if the \s-1BIO\s0 is using the Kernel \s-1TLS\s0 data-path for
receiving. Otherwise, it returns zero.
.PP
\&\fBBIO_get_conn_mode()\fR returns the \s-1BIO\s0 connection mode. \fBBIO_set_conn_mode()\fR sets
the \s-1BIO\s0 connection mode.
.PP
\&\fBBIO_set_tfo()\fR disables \s-1TCP\s0 Fast Open when \fBonoff\fR is 0, and enables \s-1TCP\s0 Fast
Open when \fBonoff\fR is nonzero. Setting the value to 1 is equivalent to setting
\&\fB\s-1BIO_SOCK_TFO\s0\fR in \fBBIO_set_conn_mode()\fR.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBBIO_reset()\fR normally returns 1 for success and <=0 for failure. File
BIOs are an exception, they return 0 for success and \-1 for failure.
.PP
\&\fBBIO_seek()\fR and \fBBIO_tell()\fR both return the current file position on success
and \-1 for failure, except file BIOs which for \fBBIO_seek()\fR always return 0
for success and \-1 for failure.
.PP
\&\fBBIO_flush()\fR returns 1 for success and <=0 for failure.
.PP
\&\fBBIO_eof()\fR returns 1 if \s-1EOF\s0 has been reached, 0 if not, or negative values for failure.
.PP
\&\fBBIO_set_close()\fR returns 1 on success or <=0 for failure.
.PP
\&\fBBIO_get_close()\fR returns the close flag value: \s-1BIO_CLOSE\s0 or \s-1BIO_NOCLOSE.\s0 It also
returns other negative values if an error occurs.
.PP
\&\fBBIO_pending()\fR, \fBBIO_ctrl_pending()\fR, \fBBIO_wpending()\fR and \fBBIO_ctrl_wpending()\fR
return the amount of pending data. \fBBIO_pending()\fR and \fBBIO_wpending()\fR return
negative value or 0 on error. \fBBIO_ctrl_pending()\fR and \fBBIO_ctrl_wpending()\fR return
0 on error.
.PP
\&\fBBIO_get_ktls_send()\fR returns 1 if the \s-1BIO\s0 is using the Kernel \s-1TLS\s0 data-path for
sending. Otherwise, it returns zero.
\&\fBBIO_get_ktls_recv()\fR returns 1 if the \s-1BIO\s0 is using the Kernel \s-1TLS\s0 data-path for
receiving. Otherwise, it returns zero.
.PP
\&\fBBIO_set_conn_mode()\fR returns 1 for success and 0 for failure. \fBBIO_get_conn_mode()\fR
returns the current connection mode. Which may contain the bitwise-or of the
following flags:
.PP
.Vb 6
\& BIO_SOCK_REUSEADDR
\& BIO_SOCK_V6_ONLY
\& BIO_SOCK_KEEPALIVE
\& BIO_SOCK_NONBLOCK
\& BIO_SOCK_NODELAY
\& BIO_SOCK_TFO
.Ve
.PP
\&\fBBIO_set_tfo()\fR returns 1 for success, and 0 for failure.
.SH "NOTES"
.IX Header "NOTES"
\&\fBBIO_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 \fBBIO_write_ex()\fR.
The \fBBIO_should_retry()\fR call should be used and appropriate action taken
is the call fails.
.PP
The return values of \fBBIO_pending()\fR and \fBBIO_wpending()\fR may not reliably
determine the amount of pending data in all cases. For example in the
case of a file \s-1BIO\s0 some data may be available in the \s-1FILE\s0 structures
internal buffers but it is not possible to determine this in a
portably way. For other types of \s-1BIO\s0 they may not be supported.
.PP
Filter BIOs if they do not internally handle a particular \fBBIO_ctrl()\fR
operation usually pass the operation to the next \s-1BIO\s0 in the chain.
This often means there is no need to locate the required \s-1BIO\s0 for
a particular operation, it can be called on a chain and it will
be automatically passed to the relevant \s-1BIO.\s0 However, this can cause
unexpected results: for example no current filter BIOs implement
\&\fBBIO_seek()\fR, but this may still succeed if the chain ends in a \s-1FILE\s0
or file descriptor \s-1BIO.\s0
.PP
Source/sink BIOs return an 0 if they do not recognize the \fBBIO_ctrl()\fR
operation.
.SH "BUGS"
.IX Header "BUGS"
Some of the return values are ambiguous and care should be taken. In
particular a return value of 0 can be returned if an operation is not
supported, if an error occurred, if \s-1EOF\s0 has not been reached and in
the case of \fBBIO_seek()\fR on a file \s-1BIO\s0 for a successful operation.
.PP
In older versions of OpenSSL the \fBBIO_ctrl_pending()\fR and
\&\fBBIO_ctrl_wpending()\fR could return values greater than \s-1INT_MAX\s0 on error.
.SH "HISTORY"
.IX Header "HISTORY"
The \fBBIO_get_ktls_send()\fR and \fBBIO_get_ktls_recv()\fR macros were added in
OpenSSL 3.0. They were modified to never return \-1 in OpenSSL 3.0.4.
.PP
The \fBBIO_get_conn_mode()\fR, \fBBIO_set_conn_mode()\fR and \fBBIO_set_tfo()\fR functions
were added in OpenSSL 3.2.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2022 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

267
openssl-3.4.2/doc/man/man3/BIO_f_base64.3
View File

@@ -1,267 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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_F_BASE64 3ossl"
.TH BIO_F_BASE64 3ossl "2025-07-01" "3.4.2" "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_base64 \- base64 BIO filter
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& #include <openssl/bio.h>
\& #include <openssl/evp.h>
\&
\& const BIO_METHOD *BIO_f_base64(void);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBBIO_f_base64()\fR returns the base64 \s-1BIO\s0 method. This is a filter
\&\s-1BIO\s0 that base64 encodes any data written through it and decodes
any data read through it.
.PP
Base64 BIOs do not support \fBBIO_gets()\fR or \fBBIO_puts()\fR.
.PP
For writing, by default output is divided to lines of length 64
characters and there is a newline at the end of output.
This behavior can be changed with \fB\s-1BIO_FLAGS_BASE64_NO_NL\s0\fR flag.
.PP
For reading, the first line of base64 content should be at most 1024 bytes long
including newline unless the flag \fB\s-1BIO_FLAGS_BASE64_NO_NL\s0\fR is set.
Subsequent input lines can be of any length (i.e., newlines may appear anywhere
in the input) and a newline at the end of input is not needed.
.PP
Also when reading, unless the flag \fB\s-1BIO_FLAGS_BASE64_NO_NL\s0\fR is set, initial
lines that contain non\-base64 content (whitespace is tolerated and ignored) are
skipped, as are lines longer than 1024 bytes.
Decoding starts with the first line that is shorter than 1024 bytes (including
the newline) and consists of only (at least one) valid base64 characters plus
optional whitespace.
Decoding stops when base64 padding is encountered, a soft end-of-input
character (\fB\-\fR, see \fBEVP_DecodeUpdate\fR\|(3)) occurs as the first byte after a
complete group of 4 valid base64 characters is decoded, or when an error occurs
(e.g. due to input characters other than valid base64 or whitespace).
.PP
If decoding stops as a result of an error, the first \fBBIO_read\fR\|(3) that
returns no decoded data will typically return a negative result, rather
than 0 (which indicates normal end of input).
However, a negative return value can also occur if the underlying \s-1BIO\s0
supports retries, see \fBBIO_should_read\fR\|(3) and \fBBIO_set_mem_eof_return\fR\|(3).
.PP
\&\fBBIO_flush()\fR on a base64 \s-1BIO\s0 that is being written through is
used to signal that no more data is to be encoded: this is used
to flush the final block through the \s-1BIO.\s0
.PP
The flag \fB\s-1BIO_FLAGS_BASE64_NO_NL\s0\fR can be set with \fBBIO_set_flags()\fR.
For writing, it causes all data to be written on one line without
newline at the end.
For reading, it removes all expectations on newlines in the input data.
.SH "NOTES"
.IX Header "NOTES"
Because of the format of base64 encoding the end of the encoded
block cannot always be reliably determined.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBBIO_f_base64()\fR returns the base64 \s-1BIO\s0 method.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
Base64 encode the string \*(L"Hello World\en\*(R" and write the result
to standard output:
.PP
.Vb 2
\& BIO *bio, *b64;
\& char message[] = "Hello World \en";
\&
\& b64 = BIO_new(BIO_f_base64());
\& bio = BIO_new_fp(stdout, BIO_NOCLOSE);
\& BIO_push(b64, bio);
\& BIO_write(b64, message, strlen(message));
\& BIO_flush(b64);
\&
\& BIO_free_all(b64);
.Ve
.PP
Read base64 encoded data from standard input and write the decoded
data to standard output:
.PP
.Vb 3
\& BIO *bio, *b64, *bio_out;
\& char inbuf[512];
\& int inlen;
\&
\& b64 = BIO_new(BIO_f_base64());
\& bio = BIO_new_fp(stdin, BIO_NOCLOSE);
\& bio_out = BIO_new_fp(stdout, BIO_NOCLOSE);
\& BIO_push(b64, bio);
\& while ((inlen = BIO_read(b64, inbuf, 512)) > 0)
\& BIO_write(bio_out, inbuf, inlen);
\&
\& BIO_flush(bio_out);
\& BIO_free_all(b64);
.Ve
.SH "BUGS"
.IX Header "BUGS"
The hyphen character (\fB\-\fR) is treated as an ad hoc soft end-of-input
character when it occurs at the start of a base64 group of 4 encoded
characters.
.PP
This heuristic works to detect the ends of base64 blocks in \s-1PEM\s0 or
multi-part \s-1MIME,\s0 provided there are no stray hyphens in the middle
input.
But it is just a heuristic, and sufficiently unusual input could produce
unexpected results.
.PP
There should perhaps 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).
.PP
It may be possible for \fBBIO_read\fR\|(3) to return zero, rather than \-1, even if
an error has been detected, more tests are needed to cover all the potential
error paths.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBBIO_read\fR\|(3),
\&\fBBIO_should_read\fR\|(3),
\&\fBBIO_set_mem_eof_return\fR\|(3),
\&\fBEVP_DecodeUpdate\fR\|(3).
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2024 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

234
openssl-3.4.2/doc/man/man3/BIO_f_buffer.3
View File

@@ -1,234 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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_F_BUFFER 3ossl"
.TH BIO_F_BUFFER 3ossl "2025-07-01" "3.4.2" "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_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>
\&
\& const BIO_METHOD *BIO_f_buffer(void);
\&
\& long BIO_get_buffer_num_lines(BIO *b);
\& long BIO_set_read_buffer_size(BIO *b, long size);
\& long BIO_set_write_buffer_size(BIO *b, long size);
\& long BIO_set_buffer_size(BIO *b, long size);
\& long BIO_set_buffer_read_data(BIO *b, void *buf, long num);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBBIO_f_buffer()\fR returns the buffering \s-1BIO\s0 method.
.PP
Data written to a buffering \s-1BIO\s0 is buffered and periodically written
to the next \s-1BIO\s0 in the chain. Data read from a buffering \s-1BIO\s0 comes from
an internal buffer which is filled from the next \s-1BIO\s0 in the chain.
Both \fBBIO_gets()\fR and \fBBIO_puts()\fR are supported.
.PP
Calling \fBBIO_reset()\fR on a buffering \s-1BIO\s0 clears any buffered data.
.PP
\&\fBBIO_get_buffer_num_lines()\fR returns the number of lines currently buffered.
.PP
\&\fBBIO_set_read_buffer_size()\fR, \fBBIO_set_write_buffer_size()\fR and \fBBIO_set_buffer_size()\fR
set the read, write or both read and write buffer sizes to \fBsize\fR. The initial
buffer size is \s-1DEFAULT_BUFFER_SIZE,\s0 currently 4096. Any attempt to reduce the
buffer size below \s-1DEFAULT_BUFFER_SIZE\s0 is ignored. Any buffered data is cleared
when the buffer is resized.
.PP
\&\fBBIO_set_buffer_read_data()\fR clears the read buffer and fills it with \fBnum\fR
bytes of \fBbuf\fR. If \fBnum\fR is larger than the current buffer size the buffer
is expanded.
.SH "NOTES"
.IX Header "NOTES"
These functions, other than \fBBIO_f_buffer()\fR, are implemented as macros.
.PP
Buffering BIOs implement \fBBIO_read_ex()\fR and \fBBIO_gets()\fR by using
\&\fBBIO_read_ex()\fR operations on the next \s-1BIO\s0 in the chain and storing the
result in an internal buffer, from which bytes are given back to the
caller as appropriate for the call; a \fBBIO_gets()\fR is guaranteed to give
the caller a whole line, and \fBBIO_read_ex()\fR is guaranteed to give the
caller the number of bytes it asks for, unless there's an error or end
of communication is reached in the next \s-1BIO.\s0 By prepending a
buffering \s-1BIO\s0 to a chain it is therefore possible to provide
\&\fBBIO_gets()\fR or exact size \fBBIO_read_ex()\fR functionality if the following
BIOs do not support it.
.PP
Do not add more than one \fBBIO_f_buffer()\fR to a \s-1BIO\s0 chain. The result of
doing so will force a full read of the size of the internal buffer of
the top \fBBIO_f_buffer()\fR, which is 4 KiB at a minimum.
.PP
Data is only written to the next \s-1BIO\s0 in the chain when the write buffer fills
or when \fBBIO_flush()\fR is called. It is therefore important to call \fBBIO_flush()\fR
whenever any pending data should be written such as when removing a buffering
\&\s-1BIO\s0 using \fBBIO_pop()\fR. \fBBIO_flush()\fR may need to be retried if the ultimate
source/sink \s-1BIO\s0 is non blocking.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBBIO_f_buffer()\fR returns the buffering \s-1BIO\s0 method.
.PP
\&\fBBIO_get_buffer_num_lines()\fR returns the number of lines buffered (may be 0) or
a negative value in case of errors.
.PP
\&\fBBIO_set_read_buffer_size()\fR, \fBBIO_set_write_buffer_size()\fR and \fBBIO_set_buffer_size()\fR
return 1 if the buffer was successfully resized or <=0 for failure.
.PP
\&\fBBIO_set_buffer_read_data()\fR returns 1 if the data was set correctly or <=0 if
there was an error.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBbio\fR\|(7),
\&\fBBIO_reset\fR\|(3),
\&\fBBIO_flush\fR\|(3),
\&\fBBIO_pop\fR\|(3),
\&\fBBIO_ctrl\fR\|(3).
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

211
openssl-3.4.2/doc/man/man3/BIO_f_cipher.3
View File

@@ -1,211 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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_F_CIPHER 3ossl"
.TH BIO_F_CIPHER 3ossl "2025-07-01" "3.4.2" "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_cipher, BIO_set_cipher, BIO_get_cipher_status, BIO_get_cipher_ctx \- cipher BIO filter
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& #include <openssl/bio.h>
\& #include <openssl/evp.h>
\&
\& const BIO_METHOD *BIO_f_cipher(void);
\& int BIO_set_cipher(BIO *b, const EVP_CIPHER *cipher,
\& const unsigned char *key, const unsigned char *iv, int enc);
\& int BIO_get_cipher_status(BIO *b);
\& int BIO_get_cipher_ctx(BIO *b, EVP_CIPHER_CTX **pctx);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBBIO_f_cipher()\fR returns the cipher \s-1BIO\s0 method. This is a filter
\&\s-1BIO\s0 that encrypts any data written through it, and decrypts any data
read from it. It is a \s-1BIO\s0 wrapper for the cipher routines
\&\fBEVP_CipherInit()\fR, \fBEVP_CipherUpdate()\fR and \fBEVP_CipherFinal()\fR.
.PP
Cipher BIOs do not support \fBBIO_gets()\fR or \fBBIO_puts()\fR.
.PP
\&\fBBIO_flush()\fR on an encryption \s-1BIO\s0 that is being written through is
used to signal that no more data is to be encrypted: this is used
to flush and possibly pad the final block through the \s-1BIO.\s0
.PP
\&\fBBIO_set_cipher()\fR sets the cipher of \s-1BIO\s0 \fBb\fR to \fBcipher\fR using key \fBkey\fR
and \s-1IV\s0 \fBiv\fR. \fBenc\fR should be set to 1 for encryption and zero for
decryption.
.PP
When reading from an encryption \s-1BIO\s0 the final block is automatically
decrypted and checked when \s-1EOF\s0 is detected. \fBBIO_get_cipher_status()\fR
is a \fBBIO_ctrl()\fR macro which can be called to determine whether the
decryption operation was successful.
.PP
\&\fBBIO_get_cipher_ctx()\fR is a \fBBIO_ctrl()\fR macro which retrieves the internal
\&\s-1BIO\s0 cipher context. The retrieved context can be used in conjunction
with the standard cipher routines to set it up. This is useful when
\&\fBBIO_set_cipher()\fR is not flexible enough for the applications needs.
.SH "NOTES"
.IX Header "NOTES"
When encrypting \fBBIO_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 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. \fBBIO_get_cipher_status()\fR
should be called to determine if the decrypt was successful.
.PP
As always, if \fBBIO_gets()\fR or \fBBIO_puts()\fR support is needed then it can
be achieved by preceding the cipher \s-1BIO\s0 with a buffering \s-1BIO.\s0
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBBIO_f_cipher()\fR returns the cipher \s-1BIO\s0 method.
.PP
\&\fBBIO_set_cipher()\fR returns 1 for success and 0 for failure.
.PP
\&\fBBIO_get_cipher_status()\fR returns 1 for a successful decrypt and <=0
for failure.
.PP
\&\fBBIO_get_cipher_ctx()\fR returns 1 for success and <=0 for failure.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

295
openssl-3.4.2/doc/man/man3/BIO_f_md.3
View File

@@ -1,295 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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_F_MD 3ossl"
.TH BIO_F_MD 3ossl "2025-07-01" "3.4.2" "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_md, BIO_set_md, BIO_get_md, BIO_get_md_ctx \- message digest BIO filter
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& #include <openssl/bio.h>
\& #include <openssl/evp.h>
\&
\& const BIO_METHOD *BIO_f_md(void);
\& int BIO_set_md(BIO *b, EVP_MD *md);
\& int BIO_get_md(BIO *b, EVP_MD **mdp);
\& int BIO_get_md_ctx(BIO *b, EVP_MD_CTX **mdcp);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBBIO_f_md()\fR returns the message digest \s-1BIO\s0 method. This is a filter
\&\s-1BIO\s0 that digests any data passed through it. It is a \s-1BIO\s0 wrapper
for the digest routines \fBEVP_DigestInit()\fR, \fBEVP_DigestUpdate()\fR
and \fBEVP_DigestFinal()\fR.
.PP
Any data written or read through a digest \s-1BIO\s0 using \fBBIO_read_ex()\fR and
\&\fBBIO_write_ex()\fR is digested.
.PP
\&\fBBIO_gets()\fR, if its \fBsize\fR parameter is large enough finishes the
digest calculation and returns the digest value. \fBBIO_puts()\fR is
not supported.
.PP
\&\fBBIO_reset()\fR reinitialises a digest \s-1BIO.\s0
.PP
\&\fBBIO_set_md()\fR sets the message digest of \s-1BIO\s0 \fBb\fR to \fBmd\fR: this
must be called to initialize a digest \s-1BIO\s0 before any data is
passed through it. It is a \fBBIO_ctrl()\fR macro.
.PP
\&\fBBIO_get_md()\fR places a pointer to the digest BIOs digest method
in \fBmdp\fR. It is a \fBBIO_ctrl()\fR macro.
.PP
\&\fBBIO_get_md_ctx()\fR returns the digest BIOs context into \fBmdcp\fR.
.SH "NOTES"
.IX Header "NOTES"
The context returned by \fBBIO_get_md_ctx()\fR can be used in calls
to \fBEVP_DigestFinal()\fR and also the signature routines \fBEVP_SignFinal()\fR
and \fBEVP_VerifyFinal()\fR.
.PP
The context returned by \fBBIO_get_md_ctx()\fR is an internal context
structure. Changes made to this context will affect the digest
\&\s-1BIO\s0 itself and the context pointer will become invalid when the digest
\&\s-1BIO\s0 is freed.
.PP
After the digest has been retrieved from a digest \s-1BIO\s0 it must be
reinitialized by calling \fBBIO_reset()\fR, or \fBBIO_set_md()\fR before any more
data is passed through it.
.PP
If an application needs to call \fBBIO_gets()\fR or \fBBIO_puts()\fR through
a chain containing digest BIOs then this can be done by prepending
a buffering \s-1BIO.\s0
.PP
Calling \fBBIO_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 \fBBIO_set_md()\fR are not sufficiently flexible.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBBIO_f_md()\fR returns the digest \s-1BIO\s0 method.
.PP
\&\fBBIO_set_md()\fR, \fBBIO_get_md()\fR and \fBBIO_md_ctx()\fR return 1 for success and
<=0 for failure.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
The following example creates a \s-1BIO\s0 chain containing an \s-1SHA1\s0 and \s-1MD5\s0
digest \s-1BIO\s0 and passes the string \*(L"Hello World\*(R" through it. Error
checking has been omitted for clarity.
.PP
.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
\& * the start of the chain.
\& */
\& bio = BIO_push(mdtmp, bio);
\& mdtmp = BIO_new(BIO_f_md());
\& BIO_set_md(mdtmp, EVP_md5());
\& bio = BIO_push(mdtmp, bio);
\& /* Note: mdtmp can now be discarded */
\& BIO_write(bio, message, strlen(message));
.Ve
.PP
The next example digests data by reading through a chain instead:
.PP
.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());
\& bio = BIO_push(mdtmp, bio);
\& mdtmp = BIO_new(BIO_f_md());
\& BIO_set_md(mdtmp, EVP_md5());
\& bio = BIO_push(mdtmp, bio);
\& do {
\& rdlen = BIO_read(bio, buf, sizeof(buf));
\& /* Might want to do something with the data here */
\& } while (rdlen > 0);
.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 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_get_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
.SH "BUGS"
.IX Header "BUGS"
The lack of support for \fBBIO_puts()\fR and the non standard behaviour of
\&\fBBIO_gets()\fR could be regarded as anomalous. It could be argued that \fBBIO_gets()\fR
and \fBBIO_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 \fBBIO_ctrl()\fR call.
.SH "HISTORY"
.IX Header "HISTORY"
Before OpenSSL 1.0.0., the call to \fBBIO_get_md_ctx()\fR would only work if the
\&\s-1BIO\s0 was initialized first.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2021 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

171
openssl-3.4.2/doc/man/man3/BIO_f_null.3
View File

@@ -1,171 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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_F_NULL 3ossl"
.TH BIO_F_NULL 3ossl "2025-07-01" "3.4.2" "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_null \- null filter
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bio.h>
\&
\& const BIO_METHOD *BIO_f_null(void);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBBIO_f_null()\fR returns the null filter \s-1BIO\s0 method. This is a filter \s-1BIO\s0
that does nothing.
.PP
All requests to a null filter \s-1BIO\s0 are passed through to the next \s-1BIO\s0 in
the chain: this means that a \s-1BIO\s0 chain containing a null filter \s-1BIO\s0
behaves just as though the \s-1BIO\s0 was not there.
.SH "NOTES"
.IX Header "NOTES"
As may be apparent a null filter \s-1BIO\s0 is not particularly useful.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBBIO_f_null()\fR returns the null filter \s-1BIO\s0 method.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

201
openssl-3.4.2/doc/man/man3/BIO_f_prefix.3
View File

@@ -1,201 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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_F_PREFIX 3ossl"
.TH BIO_F_PREFIX 3ossl "2025-07-01" "3.4.2" "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_prefix, BIO_set_prefix, BIO_set_indent, BIO_get_indent
\&\- prefix BIO filter
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bio.h>
\&
\& const BIO_METHOD *BIO_f_prefix(void);
\& long BIO_set_prefix(BIO *b, const char *prefix);
\& long BIO_set_indent(BIO *b, long indent);
\& long BIO_get_indent(BIO *b);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBBIO_f_cipher()\fR returns the prefix \s-1BIO\s0 method. This is a filter for
text output, where each line gets automatically prefixed and indented
according to user input.
.PP
The prefix and the indentation are combined. For each line of output
going through this filter, the prefix is output first, then the amount
of additional spaces indicated by the indentation, and then the line
itself.
.PP
By default, there is no prefix, and indentation is set to 0.
.PP
\&\fBBIO_set_prefix()\fR sets the prefix to be used for future lines of
text, using \fIprefix\fR. \fIprefix\fR may be \s-1NULL,\s0 signifying that there
should be no prefix. If \fIprefix\fR isn't \s-1NULL,\s0 this function makes a
copy of it.
.PP
\&\fBBIO_set_indent()\fR sets the indentation to be used for future lines of
text, using \fIindent\fR. Negative values are not allowed.
.PP
\&\fBBIO_get_indent()\fR gets the current indentation.
.SH "NOTES"
.IX Header "NOTES"
\&\fBBIO_set_prefix()\fR, \fBBIO_set_indent()\fR and \fBBIO_get_indent()\fR are
implemented as macros.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBBIO_f_prefix()\fR returns the prefix \s-1BIO\s0 method.
.PP
\&\fBBIO_set_prefix()\fR returns 1 if the prefix was correctly set, or <=0 on
failure.
.PP
\&\fBBIO_set_indent()\fR returns 1 if the prefix was correctly set, or <=0 on
failure.
.PP
\&\fBBIO_get_indent()\fR returns the current indentation, or a negative value for failure.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBbio\fR\|(7)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

192
openssl-3.4.2/doc/man/man3/BIO_f_readbuffer.3
View File

@@ -1,192 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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_F_READBUFFER 3ossl"
.TH BIO_F_READBUFFER 3ossl "2025-07-01" "3.4.2" "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_readbuffer
\&\- read only buffering BIO that supports BIO_tell() and BIO_seek()
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bio.h>
\&
\& const BIO_METHOD *BIO_f_readbuffer(void);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBBIO_f_readbuffer()\fR returns the read buffering \s-1BIO\s0 method.
.PP
This \s-1BIO\s0 filter can be inserted on top of \s-1BIO\s0's that do not support \fBBIO_tell()\fR
or \fBBIO_seek()\fR (e.g. A file \s-1BIO\s0 that uses stdin).
.PP
Data read from a read buffering \s-1BIO\s0 comes from an internal buffer which is
filled from the next \s-1BIO\s0 in the chain.
.PP
\&\fBBIO_gets()\fR is supported for read buffering BIOs.
Writing data to a read buffering \s-1BIO\s0 is not supported.
.PP
Calling \fBBIO_reset()\fR on a read buffering \s-1BIO\s0 does not clear any buffered data.
.SH "NOTES"
.IX Header "NOTES"
Read buffering BIOs implement \fBBIO_read_ex()\fR by using \fBBIO_read_ex()\fR operations
on the next \s-1BIO\s0 (e.g. a file \s-1BIO\s0) in the chain and storing the result in an
internal buffer, from which bytes are given back to the caller as appropriate
for the call. \fBBIO_read_ex()\fR is guaranteed to give the caller the number of bytes
it asks for, unless there's an error or end of communication is reached in the
next \s-1BIO.\s0 The internal buffer can grow to cache the entire contents of the next
\&\s-1BIO\s0 in the chain. \fBBIO_seek()\fR uses the internal buffer, so that it can only seek
into data that is already read.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBBIO_f_readbuffer()\fR returns the read buffering \s-1BIO\s0 method.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBbio\fR\|(7),
\&\fBBIO_read\fR\|(3),
\&\fBBIO_gets\fR\|(3),
\&\fBBIO_reset\fR\|(3),
\&\fBBIO_ctrl\fR\|(3).
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

446
openssl-3.4.2/doc/man/man3/BIO_f_ssl.3
View File

@@ -1,446 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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_F_SSL 3ossl"
.TH BIO_F_SSL 3ossl "2025-07-01" "3.4.2" "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_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>
\&
\& const BIO_METHOD *BIO_f_ssl(void);
\&
\& long BIO_set_ssl(BIO *b, SSL *ssl, long c);
\& long BIO_get_ssl(BIO *b, SSL **sslp);
\& long BIO_set_ssl_mode(BIO *b, long client);
\& long BIO_set_ssl_renegotiate_bytes(BIO *b, long num);
\& long BIO_set_ssl_renegotiate_timeout(BIO *b, long seconds);
\& long BIO_get_num_renegotiates(BIO *b);
\&
\& BIO *BIO_new_ssl(SSL_CTX *ctx, int client);
\& BIO *BIO_new_ssl_connect(SSL_CTX *ctx);
\& BIO *BIO_new_buffer_ssl_connect(SSL_CTX *ctx);
\& int BIO_ssl_copy_session_id(BIO *to, BIO *from);
\& void BIO_ssl_shutdown(BIO *bio);
\&
\& long BIO_do_handshake(BIO *b);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBBIO_f_ssl()\fR returns the \s-1SSL BIO\s0 method. This is a filter \s-1BIO\s0 which
is a wrapper round the OpenSSL \s-1SSL\s0 routines adding a \s-1BIO\s0 \*(L"flavour\*(R" to
\&\s-1SSL I/O.\s0
.PP
I/O performed on an \s-1SSL BIO\s0 communicates using the \s-1SSL\s0 protocol with
the SSLs read and write BIOs. If an \s-1SSL\s0 connection is not established
then an attempt is made to establish one on the first I/O call.
.PP
If a \s-1BIO\s0 is appended to an \s-1SSL BIO\s0 using \fBBIO_push()\fR it is automatically
used as the \s-1SSL\s0 BIOs read and write BIOs.
.PP
Calling \fBBIO_reset()\fR on an \s-1SSL BIO\s0 closes down any current \s-1SSL\s0 connection
by calling \fBSSL_shutdown()\fR. \fBBIO_reset()\fR is then sent to the next \s-1BIO\s0 in
the chain: this will typically disconnect the underlying transport.
The \s-1SSL BIO\s0 is then reset to the initial accept or connect state.
.PP
If the close flag is set when an \s-1SSL BIO\s0 is freed then the internal
\&\s-1SSL\s0 structure is also freed using \fBSSL_free()\fR.
.PP
\&\fBBIO_set_ssl()\fR sets the internal \s-1SSL\s0 pointer of \s-1SSL BIO\s0 \fBb\fR to \fBssl\fR using
the close flag \fBc\fR.
.PP
\&\fBBIO_get_ssl()\fR retrieves the \s-1SSL\s0 pointer of \s-1SSL BIO\s0 \fBb\fR, it can then be
manipulated using the standard \s-1SSL\s0 library functions.
.PP
\&\fBBIO_set_ssl_mode()\fR sets the \s-1SSL BIO\s0 mode to \fBclient\fR. If \fBclient\fR
is 1 client mode is set. If \fBclient\fR is 0 server mode is set.
.PP
\&\fBBIO_set_ssl_renegotiate_bytes()\fR sets the renegotiate byte count of \s-1SSL BIO\s0 \fBb\fR
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
\&\fBBIO_set_ssl_renegotiate_timeout()\fR sets the renegotiate timeout of \s-1SSL BIO\s0 \fBb\fR
to \fBseconds\fR.
When the renegotiate timeout elapses the session is automatically renegotiated.
.PP
\&\fBBIO_get_num_renegotiates()\fR returns the total number of session
renegotiations due to I/O or timeout of \s-1SSL BIO\s0 \fBb\fR.
.PP
\&\fBBIO_new_ssl()\fR allocates an \s-1SSL BIO\s0 using \s-1SSL_CTX\s0 \fBctx\fR and using
client mode if \fBclient\fR is non zero.
.PP
\&\fBBIO_new_ssl_connect()\fR creates a new \s-1BIO\s0 chain consisting of an
\&\s-1SSL BIO\s0 (using \fBctx\fR) followed by a connect \s-1BIO.\s0
.PP
\&\fBBIO_new_buffer_ssl_connect()\fR creates a new \s-1BIO\s0 chain consisting
of a buffering \s-1BIO,\s0 an \s-1SSL BIO\s0 (using \fBctx\fR), and a connect \s-1BIO.\s0
.PP
\&\fBBIO_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 \fBSSL_copy_session_id()\fR on
the internal \s-1SSL\s0 pointer.
.PP
\&\fBBIO_ssl_shutdown()\fR closes down an \s-1SSL\s0 connection on \s-1BIO\s0
chain \fBbio\fR. It does this by locating the \s-1SSL BIO\s0 in the
chain and calling \fBSSL_shutdown()\fR on its internal \s-1SSL\s0
pointer.
.PP
\&\fBBIO_do_handshake()\fR attempts to complete an \s-1SSL\s0 handshake on the
supplied \s-1BIO\s0 and establish the \s-1SSL\s0 connection.
For non-SSL BIOs the connection is done typically at \s-1TCP\s0 level.
If domain name resolution yields multiple \s-1IP\s0 addresses all of them are tried
after \fBconnect()\fR failures.
The function returns 1 if the connection was established successfully.
A zero or negative value is returned if the connection could not be established.
The call \fBBIO_should_retry()\fR should be used for nonblocking connect BIOs
to determine if the call should be retried.
If a connection has already been established this call has no effect.
.SH "NOTES"
.IX Header "NOTES"
\&\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 \fBBIO_read_ex()\fR operation, one
case where this happens is when step up occurs.
.PP
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.
.PP
Since unknown \fBBIO_ctrl()\fR operations are sent through filter
BIOs the servers name and port can be set using \fBBIO_set_host()\fR
on the \s-1BIO\s0 returned by \fBBIO_new_ssl_connect()\fR without having
to locate the connect \s-1BIO\s0 first.
.PP
Applications do not have to call \fBBIO_do_handshake()\fR but may wish
to do so to separate the handshake process from other I/O
processing.
.PP
\&\fBBIO_set_ssl()\fR, \fBBIO_get_ssl()\fR, \fBBIO_set_ssl_mode()\fR,
\&\fBBIO_set_ssl_renegotiate_bytes()\fR, \fBBIO_set_ssl_renegotiate_timeout()\fR,
\&\fBBIO_get_num_renegotiates()\fR, and \fBBIO_do_handshake()\fR are implemented as macros.
.PP
\&\fBBIO_ssl_copy_session_id()\fR is not currently supported on \s-1QUIC SSL\s0 objects and
fails if called on such an object.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBBIO_f_ssl()\fR returns the \s-1SSL\s0 \fB\s-1BIO_METHOD\s0\fR structure.
.PP
\&\fBBIO_set_ssl()\fR, \fBBIO_get_ssl()\fR, \fBBIO_set_ssl_mode()\fR, \fBBIO_set_ssl_renegotiate_bytes()\fR,
\&\fBBIO_set_ssl_renegotiate_timeout()\fR and \fBBIO_get_num_renegotiates()\fR return 1 on
success or a value which is less than or equal to 0 if an error occurred.
.PP
\&\fBBIO_new_ssl()\fR, \fBBIO_new_ssl_connect()\fR and \fBBIO_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
\&\fBBIO_ssl_copy_session_id()\fR returns 1 on success or 0 on error, or if called
on a \s-1QUIC SSL\s0 object.
.PP
\&\fBBIO_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 "EXAMPLES"
.IX Header "EXAMPLES"
This \s-1SSL/TLS\s0 client example attempts to retrieve a page from an
\&\s-1SSL/TLS\s0 web server. The I/O routines are identical to those of the
unencrypted example in \fBBIO_s_connect\fR\|(3).
.PP
.Vb 5
\& BIO *sbio, *out;
\& int len;
\& char tmpbuf[1024];
\& SSL_CTX *ctx;
\& SSL *ssl;
\&
\& /* XXX Seed the PRNG if needed. */
\&
\& ctx = SSL_CTX_new(TLS_client_method());
\&
\& /* XXX Set verify paths and mode here. */
\&
\& sbio = BIO_new_ssl_connect(ctx);
\& BIO_get_ssl(sbio, &ssl);
\& if (ssl == NULL) {
\& fprintf(stderr, "Can\*(Aqt locate SSL pointer\en");
\& ERR_print_errors_fp(stderr);
\& exit(1);
\& }
\&
\& /* XXX We might want to do other things with ssl here */
\&
\& /* An empty host part means the loopback address */
\& BIO_set_conn_hostname(sbio, ":https");
\&
\& out = BIO_new_fp(stdout, BIO_NOCLOSE);
\& if (BIO_do_connect(sbio) <= 0) {
\& fprintf(stderr, "Error connecting to server\en");
\& ERR_print_errors_fp(stderr);
\& exit(1);
\& }
\&
\& /* 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);
\& }
\& BIO_free_all(sbio);
\& BIO_free(out);
.Ve
.PP
Here is a simple server example. It makes use of a buffering
\&\s-1BIO\s0 to allow lines to be read from the \s-1SSL BIO\s0 using BIO_gets.
It creates a pseudo web page containing the actual request from
a client and also echoes the request to standard output.
.PP
.Vb 5
\& BIO *sbio, *bbio, *acpt, *out;
\& int len;
\& char tmpbuf[1024];
\& SSL_CTX *ctx;
\& SSL *ssl;
\&
\& /* XXX Seed the PRNG if needed. */
\&
\& ctx = SSL_CTX_new(TLS_server_method());
\& if (!SSL_CTX_use_certificate_file(ctx, "server.pem", SSL_FILETYPE_PEM)
\& || !SSL_CTX_use_PrivateKey_file(ctx, "server.pem", SSL_FILETYPE_PEM)
\& || !SSL_CTX_check_private_key(ctx)) {
\& fprintf(stderr, "Error setting up SSL_CTX\en");
\& ERR_print_errors_fp(stderr);
\& exit(1);
\& }
\&
\& /* XXX Other things like set verify locations, EDH temp callbacks. */
\&
\& /* New SSL BIO setup as server */
\& sbio = BIO_new_ssl(ctx, 0);
\& BIO_get_ssl(sbio, &ssl);
\& if (ssl == NULL) {
\& fprintf(stderr, "Can\*(Aqt locate SSL pointer\en");
\& ERR_print_errors_fp(stderr);
\& exit(1);
\& }
\&
\& bbio = BIO_new(BIO_f_buffer());
\& sbio = BIO_push(bbio, sbio);
\& acpt = BIO_new_accept("4433");
\&
\& /*
\& * By doing this when a new connection is established
\& * we automatically have sbio inserted into it. The
\& * BIO chain is now \*(Aqswallowed\*(Aq by the accept BIO and
\& * will be freed when the accept BIO is freed.
\& */
\& BIO_set_accept_bios(acpt, sbio);
\& out = BIO_new_fp(stdout, BIO_NOCLOSE);
\&
\& /* First call to BIO_do_accept() sets up accept BIO */
\& if (BIO_do_accept(acpt) <= 0) {
\& fprintf(stderr, "Error setting up accept BIO\en");
\& ERR_print_errors_fp(stderr);
\& exit(1);
\& }
.Ve
.PP
/* Second call to \fBBIO_do_accept()\fR waits for incoming connection */
if (BIO_do_accept(acpt) <= 0) {
fprintf(stderr, \*(L"Error accepting connection\en\*(R");
ERR_print_errors_fp(stderr);
\fBexit\fR\|(1);
}
.PP
.Vb 3
\& /* 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);
\& 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;
\& }
\&
\& BIO_puts(sbio, "\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\er\en");
\& BIO_puts(sbio, "\er\en");
\& BIO_flush(sbio);
\& BIO_free_all(sbio);
.Ve
.SH "HISTORY"
.IX Header "HISTORY"
In OpenSSL before 1.0.0 the \fBBIO_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 "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

203
openssl-3.4.2/doc/man/man3/BIO_find_type.3
View File

@@ -1,203 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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_FIND_TYPE 3ossl"
.TH BIO_FIND_TYPE 3ossl "2025-07-01" "3.4.2" "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_find_type, BIO_next, BIO_method_type \- BIO chain traversal
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bio.h>
\&
\& BIO *BIO_find_type(BIO *b, int bio_type);
\& BIO *BIO_next(BIO *b);
\& int BIO_method_type(const BIO *b);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \fBBIO_find_type()\fR searches for a \fB\s-1BIO\s0\fR of a given type in a chain, starting
at \fB\s-1BIO\s0\fR \fIb\fR. If \fItype\fR is a specific type (such as \fB\s-1BIO_TYPE_MEM\s0\fR) then a
search is made for a \fB\s-1BIO\s0\fR of that type. If \fItype\fR is a general type (such as
\&\fB\s-1BIO_TYPE_SOURCE_SINK\s0\fR) then the next matching \fB\s-1BIO\s0\fR of the given general type is
searched for. \fBBIO_find_type()\fR returns the next matching \fB\s-1BIO\s0\fR or \s-1NULL\s0 if none is
found. If \fItype\fR is \fB\s-1BIO_TYPE_NONE\s0\fR it will not find a match.
.PP
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 \fI<openssl/bio.h>\fR header file.
.PP
\&\fBBIO_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 \fBBIO_find_type()\fR to find all BIOs of a
certain type.
.PP
\&\fBBIO_method_type()\fR returns the type of a \s-1BIO.\s0
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBBIO_find_type()\fR returns a matching \s-1BIO\s0 or \s-1NULL\s0 for no match.
.PP
\&\fBBIO_next()\fR returns the next \s-1BIO\s0 in a chain.
.PP
\&\fBBIO_method_type()\fR returns the type of the \s-1BIO\s0 \fIb\fR.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
Traverse a chain looking for digest BIOs:
.PP
.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_next(btmp);
\& } while (btmp);
.Ve
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2024 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

196
openssl-3.4.2/doc/man/man3/BIO_get_data.3
View File

@@ -1,196 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 3ossl"
.TH BIO_GET_DATA 3ossl "2025-07-01" "3.4.2" "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 \fBBIO_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 \fBBIO_get_data()\fR.
This can be used by custom BIOs for storing implementation specific information.
.PP
The \fBBIO_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 nonzero 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 \fBBIO_get_init()\fR
function returns the value of the \*(L"init\*(R" flag.
.PP
The \fBBIO_set_shutdown()\fR and \fBBIO_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"
\&\fBBIO_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
\&\fBBIO_get_init()\fR returns the state of the \s-1BIO\s0's init flag.
.PP
\&\fBBIO_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"
\&\fBbio\fR\|(7), \fBBIO_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 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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
openssl-3.4.2/doc/man/man3/BIO_get_ex_new_index.3
View File

@@ -1,266 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 3ossl"
.TH BIO_GET_EX_NEW_INDEX 3ossl "2025-07-01" "3.4.2" "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,
BIO_set_app_data, BIO_get_app_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,
EC_KEY_get_ex_new_index, EC_KEY_set_ex_data, EC_KEY_get_ex_data,
ENGINE_get_ex_new_index, ENGINE_set_ex_data, ENGINE_get_ex_data,
EVP_PKEY_get_ex_new_index, EVP_PKEY_set_ex_data, EVP_PKEY_get_ex_data,
RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data,
RSA_set_app_data, RSA_get_app_data,
SSL_get_ex_new_index, SSL_set_ex_data, SSL_get_ex_data,
SSL_set_app_data, SSL_get_app_data,
SSL_CTX_get_ex_new_index, SSL_CTX_set_ex_data, SSL_CTX_get_ex_data,
SSL_CTX_set_app_data, SSL_CTX_get_app_data,
SSL_SESSION_get_ex_new_index, SSL_SESSION_set_ex_data, SSL_SESSION_get_ex_data,
SSL_SESSION_set_app_data, SSL_SESSION_get_app_data,
UI_get_ex_new_index, UI_set_ex_data, UI_get_ex_data,
UI_set_app_data, UI_get_app_data,
X509_STORE_CTX_get_ex_new_index, X509_STORE_CTX_set_ex_data, X509_STORE_CTX_get_ex_data,
X509_STORE_CTX_set_app_data, X509_STORE_CTX_get_app_data,
X509_STORE_get_ex_new_index, X509_STORE_set_ex_data, X509_STORE_get_ex_data,
X509_get_ex_new_index, X509_set_ex_data, X509_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(const TYPE *d, int idx);
\&
\& #define TYPE_set_app_data(TYPE *d, void *arg)
\& #define TYPE_get_app_data(TYPE *d)
.Ve
.PP
The following functions have been deprecated since OpenSSL 3.0, and can be
hidden entirely by defining \fB\s-1OPENSSL_API_COMPAT\s0\fR with a suitable version value,
see \fBopenssl_user_macros\fR\|(7):
.PP
.Vb 10
\& int DH_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func,
\& CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func);
\& int DH_set_ex_data(DH *type, int idx, void *arg);
\& void *DH_get_ex_data(DH *type, int idx);
\& int DSA_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func,
\& CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func);
\& int DSA_set_ex_data(DSA *type, int idx, void *arg);
\& void *DSA_get_ex_data(DSA *type, int idx);
\& int EC_KEY_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func,
\& CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func);
\& int EC_KEY_set_ex_data(EC_KEY *type, int idx, void *arg);
\& void *EC_KEY_get_ex_data(EC_KEY *type, int idx);
\& int RSA_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func,
\& CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func);
\& int RSA_set_ex_data(RSA *type, int idx, void *arg);
\& void *RSA_get_ex_data(RSA *type, int idx);
\& int RSA_set_app_data(RSA *type, void *arg);
\& void *RSA_get_app_data(RSA *type);
\& int ENGINE_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func,
\& CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func);
\& int ENGINE_set_ex_data(ENGINE *type, int idx, void *arg);
\& void *ENGINE_get_ex_data(ENGINE *type, 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 \fBCRYPTO_get_ex_new_index\fR\|(3).
.PP
All functions with a \fI\s-1TYPE\s0\fR of \fB\s-1DH\s0\fR, \fB\s-1DSA\s0\fR, \fB\s-1RSA\s0\fR and \fB\s-1EC_KEY\s0\fR are deprecated.
Applications should instead use \fBEVP_PKEY_set_ex_data()\fR,
\&\fBEVP_PKEY_get_ex_data()\fR and \fBEVP_PKEY_get_ex_new_index()\fR.
.PP
All functions with a \fI\s-1TYPE\s0\fR of \fB\s-1ENGINE\s0\fR are deprecated.
Applications using engines should be replaced by providers.
.PP
These functions handle application-specific data for OpenSSL data
structures.
.PP
\&\fBTYPE_get_ex_new_index()\fR is a macro that calls \fBCRYPTO_get_ex_new_index()\fR
with the correct \fBindex\fR value.
.PP
\&\fBTYPE_set_ex_data()\fR is a function that calls \fBCRYPTO_set_ex_data()\fR with
an offset into the opaque exdata part of the \s-1TYPE\s0 object.
.PP
\&\fBTYPE_get_ex_data()\fR is a function that calls \fBCRYPTO_get_ex_data()\fR with
an offset into the opaque exdata part of the \s-1TYPE\s0 object.
.PP
For compatibility with previous releases, the exdata index of zero is
reserved for \*(L"application data.\*(R" There are two convenience functions for
this.
\&\fBTYPE_set_app_data()\fR is a macro that invokes \fBTYPE_set_ex_data()\fR with
\&\fBidx\fR set to zero.
\&\fBTYPE_get_app_data()\fR is a macro that invokes \fBTYPE_get_ex_data()\fR with
\&\fBidx\fR set to zero.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBTYPE_get_ex_new_index()\fR returns a new index on success or \-1 on error.
.PP
\&\fBTYPE_set_ex_data()\fR returns 1 on success or 0 on error.
.PP
\&\fBTYPE_get_ex_data()\fR returns the application data or \s-1NULL\s0 if an error occurred.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBCRYPTO_get_ex_new_index\fR\|(3).
.SH "HISTORY"
.IX Header "HISTORY"
The functions \fBDH_get_ex_new_index()\fR, \fBDH_set_ex_data()\fR, \fBDH_get_ex_data()\fR,
\&\fBDSA_get_ex_new_index()\fR, \fBDSA_set_ex_data()\fR, \fBDSA_get_ex_data()\fR,
\&\fBEC_KEY_get_ex_new_index()\fR, \fBEC_KEY_set_ex_data()\fR, \fBEC_KEY_get_ex_data()\fR,
\&\fBENGINE_get_ex_new_index()\fR, \fBENGINE_set_ex_data()\fR, \fBENGINE_get_ex_data()\fR,
\&\fBRSA_get_ex_new_index()\fR, \fBRSA_set_ex_data()\fR, \fBRSA_get_ex_data()\fR,
\&\fBRSA_set_app_data()\fR and \fBRSA_get_app_data()\fR were deprecated in OpenSSL 3.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2015\-2021 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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
openssl-3.4.2/doc/man/man3/BIO_get_rpoll_descriptor.3
View File

@@ -1,236 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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_RPOLL_DESCRIPTOR 3ossl"
.TH BIO_GET_RPOLL_DESCRIPTOR 3ossl "2025-07-01" "3.4.2" "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_rpoll_descriptor, BIO_get_wpoll_descriptor \- obtain a structure which
can be used to determine when a BIO object can next be read or written
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bio.h>
\&
\& typedef struct bio_poll_descriptor_st {
\& uint32_t type;
\& union {
\& int fd;
\& void *custom;
\& uintptr_t custom_ui;
\& } value;
\& } BIO_POLL_DESCRIPTOR;
\&
\& int BIO_get_rpoll_descriptor(BIO *b, BIO_POLL_DESCRIPTOR *desc);
\& int BIO_get_wpoll_descriptor(BIO *b, BIO_POLL_DESCRIPTOR *desc);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBBIO_get_rpoll_descriptor()\fR and \fBBIO_get_wpoll_descriptor()\fR, on success, fill
\&\fI*desc\fR with a poll descriptor. A poll descriptor is a tagged union structure
which represents some kind of \s-1OS\s0 or non-OS resource which can be used to
synchronise on I/O availability events.
.PP
\&\fBBIO_get_rpoll_descriptor()\fR outputs a descriptor which can be used to determine
when the \s-1BIO\s0 can (potentially) next be read, and \fBBIO_get_wpoll_descriptor()\fR
outputs a descriptor which can be used to determine when the \s-1BIO\s0 can
(potentially) next be written.
.PP
It is permissible for \fBBIO_get_rpoll_descriptor()\fR and \fBBIO_get_wpoll_descriptor()\fR
to output the same descriptor.
.PP
Poll descriptors can represent different kinds of information. A typical kind of
resource which might be represented by a poll descriptor is an \s-1OS\s0 file
descriptor which can be used with APIs such as \fBselect()\fR.
.PP
The kinds of poll descriptor defined by OpenSSL are:
.IP "\s-1BIO_POLL_DESCRIPTOR_TYPE_NONE\s0" 4
.IX Item "BIO_POLL_DESCRIPTOR_TYPE_NONE"
Represents the absence of a valid poll descriptor. It may be used by
\&\fBBIO_get_rpoll_descriptor()\fR or \fBBIO_get_wpoll_descriptor()\fR to indicate that the
\&\s-1BIO\s0 is not pollable for readability or writeability respectively.
.Sp
For this type, no field within the \fIvalue\fR field of the \fB\s-1BIO_POLL_DESCRIPTOR\s0\fR
is valid.
.IP "\s-1BIO_POLL_DESCRIPTOR_TYPE_SOCK_FD\s0" 4
.IX Item "BIO_POLL_DESCRIPTOR_TYPE_SOCK_FD"
The poll descriptor represents an \s-1OS\s0 socket resource. The field \fIvalue.fd\fR
in the \fB\s-1BIO_POLL_DESCRIPTOR\s0\fR is valid if it is not set to \-1.
.Sp
The resource is whatever kind of handle is used by a given \s-1OS\s0 to represent
sockets, which may vary by \s-1OS.\s0 For example, on Windows, the value is a \fB\s-1SOCKET\s0\fR
for use with the Winsock \s-1API.\s0 On POSIX-like platforms, it is a file descriptor.
.Sp
Where a poll descriptor of this type is output by \fBBIO_get_rpoll_descriptor()\fR, it
should be polled for readability to determine when the \s-1BIO\s0 might next be able to
successfully complete a \fBBIO_read()\fR operation; likewise, where a poll descriptor
of this type is output by \fBBIO_get_wpoll_descriptor()\fR, it should be polled for
writeability to determine when the \s-1BIO\s0 might next be able to successfully
complete a \fBBIO_write()\fR operation.
.IP "\s-1BIO_POLL_DESCRIPTOR_CUSTOM_START\s0" 4
.IX Item "BIO_POLL_DESCRIPTOR_CUSTOM_START"
Type values beginning with this value (inclusive) are reserved for application
allocation for custom poll descriptor types. Any of the definitions in the union
field \fIvalue\fR can be used by the application arbitrarily as opaque values.
.PP
Because poll descriptors are a tagged union structure, they can represent
different kinds of information. New types of poll descriptor may be defined,
including by applications, according to their needs.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
The functions \fBBIO_get_rpoll_descriptor()\fR and \fBBIO_get_wpoll_descriptor()\fR return 1
on success and 0 on failure.
.PP
These functions are permitted to succeed and initialise \fI*desc\fR with a poll
descriptor of type \fB\s-1BIO_POLL_DESCRIPTOR_TYPE_NONE\s0\fR to indicate that the \s-1BIO\s0 is
not pollable for readability or writeability respectively.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBSSL_handle_events\fR\|(3), \fBSSL_get_event_timeout\fR\|(3), \fBSSL_get_rpoll_descriptor\fR\|(3),
\&\fBSSL_get_wpoll_descriptor\fR\|(3), \fBbio\fR\|(7)
.SH "HISTORY"
.IX Header "HISTORY"
The \fBSSL_get_rpoll_descriptor()\fR and \fBSSL_get_wpoll_descriptor()\fR functions were
added in OpenSSL 3.2.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2022\-2023 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

326
openssl-3.4.2/doc/man/man3/BIO_meth_new.3
View File

@@ -1,326 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 3ossl"
.TH BIO_METH_NEW 3ossl "2025-07-01" "3.4.2" "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, BIO_meth_set_sendmmsg, BIO_meth_get_sendmmsg,
BIO_meth_set_recvmmsg, BIO_meth_get_recvmmsg \- 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 *));
\&
\& ossl_ssize_t (*BIO_meth_get_sendmmsg(const BIO_METHOD *biom))(BIO *,
\& BIO_MSG *,
\& size_t,
\& size_t,
\& uint64_t);
\& int BIO_meth_set_sendmmsg(BIO_METHOD *biom,
\& ossl_ssize_t (*f) (BIO *, BIO_MSG *, size_t,
\& size_t, uint64_t));
\&
\& ossl_ssize_t (*BIO_meth_get_recvmmsg(const BIO_METHOD *biom))(BIO *,
\& BIO_MSG *,
\& size_t,
\& size_t,
\& uint64_t);
\& int BIO_meth_set_recvmmsg(BIO_METHOD *biom,
\& ossl_ssize_t (*f) (BIO *, BIO_MSG *, size_t,
\& size_t, uint64_t));
.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 \fBbio\fR\|(7) page for more information.
.PP
\&\fBBIO_meth_new()\fR creates a new \fB\s-1BIO_METHOD\s0\fR structure that contains a type
identifier \fItype\fR and a string that represents its \fBname\fR.
\&\fBtype\fR can be set to either \fB\s-1BIO_TYPE_NONE\s0\fR or via \fBBIO_get_new_index()\fR if
a unique type is required for searching (See \fBBIO_find_type\fR\|(3))
.PP
Note that \fBBIO_get_new_index()\fR can only be used 127 times before it returns an
error.
.PP
The set of
standard OpenSSL provided \s-1BIO\s0 types is provided in \fI<openssl/bio.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
\&\fBBIO_find_type\fR\|(3) page for more information.
.PP
\&\fBBIO_meth_free()\fR destroys a \fB\s-1BIO_METHOD\s0\fR structure and frees up any memory
associated with it. If the argument is \s-1NULL,\s0 nothing is done.
.PP
\&\fBBIO_meth_get_write_ex()\fR and \fBBIO_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 \fBBIO_write_ex()\fR or
\&\fBBIO_write()\fR. The parameters for the function have the same meaning as for
\&\fBBIO_write_ex()\fR. Older code may call \fBBIO_meth_get_write()\fR and
\&\fBBIO_meth_set_write()\fR instead. Applications should not call both
\&\fBBIO_meth_set_write_ex()\fR and \fBBIO_meth_set_write()\fR or call \fBBIO_meth_get_write()\fR
when the function was set with \fBBIO_meth_set_write_ex()\fR.
.PP
\&\fBBIO_meth_get_read_ex()\fR and \fBBIO_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 \fBBIO_read_ex()\fR or \fBBIO_read()\fR.
The parameters for the function have the same meaning as for \fBBIO_read_ex()\fR.
Older code may call \fBBIO_meth_get_read()\fR and \fBBIO_meth_set_read()\fR instead.
Applications should not call both \fBBIO_meth_set_read_ex()\fR and \fBBIO_meth_set_read()\fR
or call \fBBIO_meth_get_read()\fR when the function was set with
\&\fBBIO_meth_set_read_ex()\fR.
.PP
\&\fBBIO_meth_get_puts()\fR and \fBBIO_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 \fBBIO_puts()\fR. The parameters for
the function have the same meaning as for \fBBIO_puts()\fR.
.PP
\&\fBBIO_meth_get_gets()\fR and \fBBIO_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 \fBBIO_gets\fR\|(3)
page for more information). This function will be called in response to the
application calling \fBBIO_gets()\fR. The parameters for the function have the same
meaning as for \fBBIO_gets()\fR.
.PP
\&\fBBIO_meth_get_ctrl()\fR and \fBBIO_meth_set_ctrl()\fR get and set the function used for
processing ctrl messages in the \s-1BIO\s0 respectively. See the \fBBIO_ctrl\fR\|(3) page for
more information. This function will be called in response to the application
calling \fBBIO_ctrl()\fR. The parameters for the function have the same meaning as for
\&\fBBIO_ctrl()\fR.
.PP
\&\fBBIO_meth_get_create()\fR and \fBBIO_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 \fBBIO_new()\fR and passing
in a pointer to the current \s-1BIO_METHOD.\s0 The \fBBIO_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. If a create function is set,
\&\fBBIO_new()\fR will not mark the \s-1BIO\s0 as initialised on allocation.
\&\fBBIO_set_init\fR\|(3) must then be called either by the create function, or later,
by a \s-1BIO\s0 ctrl function, once \s-1BIO\s0 initialisation is complete.
.PP
\&\fBBIO_meth_get_destroy()\fR and \fBBIO_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 \fBBIO_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
\&\fBBIO_meth_get_callback_ctrl()\fR and \fBBIO_meth_set_callback_ctrl()\fR get and set the
function used for processing callback ctrl messages in the \s-1BIO\s0 respectively. See
the \fBBIO_callback_ctrl\fR\|(3) page for more information. This function will be called
in response to the application calling \fBBIO_callback_ctrl()\fR. The parameters for
the function have the same meaning as for \fBBIO_callback_ctrl()\fR.
.PP
\&\fBBIO_meth_get_sendmmsg()\fR, \fBBIO_meth_set_sendmmsg()\fR, \fBBIO_meth_get_recvmmsg()\fR and
\&\fBBIO_meth_set_recvmmsg()\fR get and set the functions used for handling
\&\fBBIO_sendmmsg()\fR and \fBBIO_recvmmsg()\fR calls respectively. See \fBBIO_sendmmsg\fR\|(3) for
more information.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBBIO_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"
\&\fBbio\fR\|(7), \fBBIO_find_type\fR\|(3), \fBBIO_ctrl\fR\|(3), \fBBIO_read_ex\fR\|(3), \fBBIO_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\-2024 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

211
openssl-3.4.2/doc/man/man3/BIO_new.3
View File

@@ -1,211 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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_NEW 3ossl"
.TH BIO_NEW 3ossl "2025-07-01" "3.4.2" "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_ex, 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_ex(OSSL_LIB_CTX *libctx, const 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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \fBBIO_new_ex()\fR function returns a new \s-1BIO\s0 using method \fBtype\fR associated with
the library context \fIlibctx\fR (see \s-1\fBOSSL_LIB_CTX\s0\fR\|(3)). The library context may be
\&\s-1NULL\s0 to indicate the default library context.
.PP
The \fBBIO_new()\fR is the same as \fBBIO_new_ex()\fR except the default library context is
always used.
.PP
\&\fBBIO_up_ref()\fR increments the reference count associated with the \s-1BIO\s0 object.
.PP
\&\fBBIO_free()\fR frees up a single \s-1BIO,\s0 \fBBIO_vfree()\fR also frees up a single \s-1BIO\s0
but it does not return a value.
If \fBa\fR is \s-1NULL\s0 nothing is done.
Calling \fBBIO_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
\&\fBBIO_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"
\&\fBBIO_new_ex()\fR and \fBBIO_new()\fR return a newly created \s-1BIO\s0 or \s-1NULL\s0 if the call fails.
.PP
\&\fBBIO_up_ref()\fR and \fBBIO_free()\fR return 1 for success and 0 for failure.
.PP
\&\fBBIO_free_all()\fR and \fBBIO_vfree()\fR do not return values.
.SH "NOTES"
.IX Header "NOTES"
If \fBBIO_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 \fBBIO_free_all()\fR on a single \s-1BIO\s0 has the same effect as calling \fBBIO_free()\fR
on it other than the discarded return value.
.SH "HISTORY"
.IX Header "HISTORY"
\&\fBBIO_set()\fR was removed in OpenSSL 1.1.0 as \s-1BIO\s0 type is now opaque.
.PP
\&\fBBIO_new_ex()\fR was added in OpenSSL 3.0.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
Create a memory \s-1BIO:\s0
.PP
.Vb 1
\& BIO *mem = BIO_new(BIO_s_mem());
.Ve
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2021 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

204
openssl-3.4.2/doc/man/man3/BIO_new_CMS.3
View File

@@ -1,204 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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_NEW_CMS 3ossl"
.TH BIO_NEW_CMS 3ossl "2025-07-01" "3.4.2" "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_CMS \- CMS streaming filter BIO
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/cms.h>
\&
\& BIO *BIO_new_CMS(BIO *out, CMS_ContentInfo *cms);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBBIO_new_CMS()\fR returns a streaming filter \s-1BIO\s0 chain based on \fBcms\fR. The output
of the filter is written to \fBout\fR. Any data written to the chain is
automatically translated to a \s-1BER\s0 format \s-1CMS\s0 structure of the appropriate type.
.SH "NOTES"
.IX Header "NOTES"
The chain returned by this function behaves like a standard filter \s-1BIO.\s0 It
supports non blocking I/O. Content is processed and streamed on the fly and not
all held in memory at once: so it is possible to encode very large structures.
After all content has been written through the chain \fBBIO_flush()\fR must be called
to finalise the structure.
.PP
The \fB\s-1CMS_STREAM\s0\fR flag must be included in the corresponding \fBflags\fR
parameter of the \fBcms\fR creation function.
.PP
If an application wishes to write additional data to \fBout\fR BIOs should be
removed from the chain using \fBBIO_pop()\fR and freed with \fBBIO_free()\fR until \fBout\fR
is reached. If no additional data needs to be written \fBBIO_free_all()\fR can be
called to free up the whole chain.
.PP
Any content written through the filter is used verbatim: no canonical
translation is performed.
.PP
It is possible to chain multiple BIOs to, for example, create a triple wrapped
signed, enveloped, signed structure. In this case it is the applications
responsibility to set the inner content type of any outer CMS_ContentInfo
structures.
.PP
Large numbers of small writes through the chain should be avoided as this will
produce an output consisting of lots of \s-1OCTET STRING\s0 structures. Prepending
a \fBBIO_f_buffer()\fR buffering \s-1BIO\s0 will prevent this.
.SH "BUGS"
.IX Header "BUGS"
There is currently no corresponding inverse \s-1BIO:\s0 i.e. one which can decode
a \s-1CMS\s0 structure on the fly.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBBIO_new_CMS()\fR returns a \s-1BIO\s0 chain when successful or \s-1NULL\s0 if an error
occurred. The error can be obtained from \fBERR_get_error\fR\|(3).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBERR_get_error\fR\|(3), \fBCMS_sign\fR\|(3),
\&\fBCMS_encrypt\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
The \fBBIO_new_CMS()\fR function 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 Apache License 2.0 (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>.

215
openssl-3.4.2/doc/man/man3/BIO_parse_hostserv.3
View File

@@ -1,215 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 3ossl"
.TH BIO_PARSE_HOSTSERV 3ossl "2025-07-01" "3.4.2" "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"
\&\fBBIO_parse_hostserv()\fR will parse the information given in \fBhostserv\fR,
create strings with the hostname 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 hostname or a service name in ambiguous
cases.
.PP
The syntax the \fBBIO_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. A service name
will be mapped to a port number using the system function \fBgetservbyname()\fR.
.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"
\&\fBBIO_parse_hostserv()\fR returns 1 on success or 0 on error.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1\fBBIO_ADDRINFO\s0\fR\|(3)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2016\-2021 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

189
openssl-3.4.2/doc/man/man3/BIO_printf.3
View File

@@ -1,189 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 3ossl"
.TH BIO_PRINTF 3ossl "2025-07-01" "3.4.2" "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"
\&\fBBIO_printf()\fR is similar to the standard C \fBprintf()\fR function, except that
the output is sent to the specified \s-1BIO,\s0 \fIbio\fR, rather than standard
output. All common format specifiers are supported.
.PP
\&\fBBIO_vprintf()\fR is similar to the \fBvprintf()\fR function found on many platforms,
the output is sent to the specified \s-1BIO,\s0 \fIbio\fR, rather than standard
output. All common format specifiers are supported. The argument
list \fIargs\fR is a stdarg argument list.
.PP
\&\fBBIO_snprintf()\fR is for platforms that do not have the common \fBsnprintf()\fR
function. It is like \fBsprintf()\fR except that the size parameter, \fIn\fR,
specifies the size of the output buffer.
.PP
\&\fBBIO_vsnprintf()\fR is to \fBBIO_snprintf()\fR as \fBBIO_vprintf()\fR is to \fBBIO_printf()\fR.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
All functions return the number of bytes written, or \-1 on error.
For \fBBIO_snprintf()\fR and \fBBIO_vsnprintf()\fR this includes when the output
buffer is too small.
.SH "NOTES"
.IX Header "NOTES"
Except when \fIn\fR is 0, both \fBBIO_snprintf()\fR and \fBBIO_vsnprintf()\fR always
terminate their output with \f(CW\*(Aq\e0\*(Aq\fR. This includes cases where \-1 is
returned, such as when there is insufficient space to output the whole
string.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2017\-2021 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

233
openssl-3.4.2/doc/man/man3/BIO_push.3
View File

@@ -1,233 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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_PUSH 3ossl"
.TH BIO_PUSH 3ossl "2025-07-01" "3.4.2" "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, 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 *next);
\& BIO *BIO_pop(BIO *b);
\& void BIO_set_next(BIO *b, BIO *next);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBBIO_push()\fR pushes \fIb\fR on \fInext\fR.
If \fIb\fR is \s-1NULL\s0 the function does nothing and returns \fInext\fR.
Otherwise it prepends \fIb\fR, which may be a single \s-1BIO\s0 or a chain of BIOs,
to \fInext\fR (unless \fInext\fR is \s-1NULL\s0).
It then makes a control call on \fIb\fR and returns \fIb\fR.
.PP
\&\fBBIO_pop()\fR removes the \s-1BIO\s0 \fIb\fR from any chain is is part of.
If \fIb\fR is \s-1NULL\s0 the function does nothing and returns \s-1NULL.\s0
Otherwise it makes a control call on \fIb\fR and
returns the next \s-1BIO\s0 in the chain, or \s-1NULL\s0 if there is no next \s-1BIO.\s0
The removed \s-1BIO\s0 becomes a single \s-1BIO\s0 with no association with
the original chain, it can thus be freed or be made part of a different chain.
.PP
\&\fBBIO_set_next()\fR replaces the existing next \s-1BIO\s0 in a chain with the \s-1BIO\s0 pointed to
by \fInext\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. \fBBIO_push()\fR
joins two \s-1BIO\s0 chains whereas \fBBIO_pop()\fR deletes a single \s-1BIO\s0 from a chain,
the deleted \s-1BIO\s0 does not need to be at the end of a chain.
.PP
The process of calling \fBBIO_push()\fR and \fBBIO_pop()\fR on a \s-1BIO\s0 may have additional
consequences (a control call is made to the affected BIOs).
Any effects will be noted in the descriptions of individual BIOs.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBBIO_push()\fR returns the head of the chain,
which usually is \fIb\fR, or \fInext\fR if \fIb\fR is \s-1NULL.\s0
.PP
\&\fBBIO_pop()\fR returns the next \s-1BIO\s0 in the chain,
or \s-1NULL\s0 if there is no next \s-1BIO.\s0
.SH "EXAMPLES"
.IX Header "EXAMPLES"
For these examples suppose \fImd1\fR and \fImd2\fR are digest BIOs,
\&\fIb64\fR is a base64 \s-1BIO\s0 and \fIf\fR is a file \s-1BIO.\s0
.PP
If the call:
.PP
.Vb 1
\& BIO_push(b64, f);
.Ve
.PP
is made then the new chain will be \fIb64\-f\fR. After making the calls
.PP
.Vb 2
\& BIO_push(md2, b64);
\& BIO_push(md1, md2);
.Ve
.PP
the new chain is \fImd1\-md2\-b64\-f\fR. Data written to \fImd1\fR will be digested
by \fImd1\fR and \fImd2\fR, base64 encoded, and finally written to \fIf\fR.
.PP
It should be noted that reading causes data to pass in the reverse
direction, that is data is read from \fIf\fR, base64 decoded,
and digested by \fImd2\fR and then \fImd1\fR.
.PP
The call:
.PP
.Vb 1
\& BIO_pop(md2);
.Ve
.PP
will return \fIb64\fR and the new chain will be \fImd1\-b64\-f\fR.
Data can be written to and read from \fImd1\fR as before,
except that \fImd2\fR will no more be applied.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBbio\fR\|(7)
.SH "HISTORY"
.IX Header "HISTORY"
The \fBBIO_set_next()\fR function was added in OpenSSL 1.1.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2021 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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
openssl-3.4.2/doc/man/man3/BIO_read.3
View File

@@ -1,259 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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_READ 3ossl"
.TH BIO_READ 3ossl "2025-07-01" "3.4.2" "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_ex, BIO_write_ex, BIO_read, BIO_write,
BIO_gets, BIO_get_line, BIO_puts
\&\- BIO I/O functions
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bio.h>
\&
\& int BIO_read_ex(BIO *b, void *data, size_t dlen, size_t *readbytes);
\& int BIO_write_ex(BIO *b, const void *data, size_t dlen, size_t *written);
\&
\& int BIO_read(BIO *b, void *data, int dlen);
\& int BIO_gets(BIO *b, char *buf, int size);
\& int BIO_get_line(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"
\&\fBBIO_read_ex()\fR attempts to read \fIdlen\fR bytes from \s-1BIO\s0 \fIb\fR and places the data
in \fIdata\fR. If any bytes were successfully read then the number of bytes read is
stored in \fI*readbytes\fR.
.PP
\&\fBBIO_write_ex()\fR attempts to write \fIdlen\fR bytes from \fIdata\fR to \s-1BIO\s0 \fIb\fR.
If successful then the number of bytes written is stored in \fI*written\fR
unless \fIwritten\fR is \s-1NULL.\s0
.PP
\&\fBBIO_read()\fR attempts to read \fIlen\fR bytes from \s-1BIO\s0 \fIb\fR and places
the data in \fIbuf\fR.
.PP
\&\fBBIO_gets()\fR performs the BIOs \*(L"gets\*(R" operation and places the data
in \fIbuf\fR. Usually this operation will attempt to read a line of data
from the \s-1BIO\s0 of maximum length \fIsize\-1\fR. There are exceptions to this,
however; for example, \fBBIO_gets()\fR on a digest \s-1BIO\s0 will calculate and
return the digest and other BIOs may not support \fBBIO_gets()\fR at all.
The returned string is always NUL-terminated and the '\en' is preserved
if present in the input data.
On binary input there may be \s-1NUL\s0 characters within the string;
in this case the return value (if nonnegative) may give an incorrect length.
.PP
\&\fBBIO_get_line()\fR attempts to read from \s-1BIO\s0 \fIb\fR a line of data up to the next '\en'
or the maximum length \fIsize\-1\fR is reached and places the data in \fIbuf\fR.
The returned string is always NUL-terminated and the '\en' is preserved
if present in the input data.
On binary input there may be \s-1NUL\s0 characters within the string;
in this case the return value (if nonnegative) gives the actual length read.
For implementing this, unfortunately the data needs to be read byte-by-byte.
.PP
\&\fBBIO_write()\fR attempts to write \fIlen\fR bytes from \fIbuf\fR to \s-1BIO\s0 \fIb\fR.
.PP
\&\fBBIO_puts()\fR attempts to write a NUL-terminated string \fIbuf\fR to \s-1BIO\s0 \fIb\fR.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBBIO_read_ex()\fR returns 1 if data was successfully read, and 0 otherwise.
.PP
\&\fBBIO_write_ex()\fR returns 1 if no error was encountered writing data, 0 otherwise.
Requesting to write 0 bytes is not considered an error.
.PP
\&\fBBIO_write()\fR returns \-2 if the \*(L"write\*(R" operation is not implemented by the \s-1BIO\s0
or \-1 on other errors.
Otherwise it returns the number of bytes written.
This may be 0 if the \s-1BIO\s0 \fIb\fR is \s-1NULL\s0 or \fIdlen <= 0\fR.
.PP
\&\fBBIO_gets()\fR returns \-2 if the \*(L"gets\*(R" operation is not implemented by the \s-1BIO\s0
or \-1 on other errors.
Otherwise it typically returns the amount of data read,
but depending on the implementation it may return only the length up to
the first \s-1NUL\s0 character contained in the data read.
In any case the trailing \s-1NUL\s0 that is added after the data read
is not included in the length returned.
.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.
.SH "NOTES"
.IX Header "NOTES"
A 0 or \-1 return is not necessarily an indication of an error. In
particular when the source/sink is nonblocking or of a certain type
it may merely be an indication that no data is currently available and that
the application should retry the operation later.
.PP
One technique sometimes used with blocking sockets is to use a system call
(such as \fBselect()\fR, \fBpoll()\fR or equivalent) to determine when data is available
and then call \fBread()\fR to read the data. The equivalent with BIOs (that is call
\&\fBselect()\fR on the underlying I/O structure and then call \fBBIO_read()\fR to
read the data) should \fBnot\fR be used because a single call to \fBBIO_read()\fR
can cause several reads (and writes in the case of \s-1SSL\s0 BIOs) on the underlying
I/O structure and may block as a result. Instead \fBselect()\fR (or equivalent)
should be combined with non blocking I/O so successive reads will request
a retry instead of blocking.
.PP
See \fBBIO_should_retry\fR\|(3) for details of how to
determine the cause of a retry and other I/O issues.
.PP
If the \*(L"gets\*(R" method is not supported by a \s-1BIO\s0 then \fBBIO_get_line()\fR can be used.
It is also possible to make \fBBIO_gets()\fR usable even if the \*(L"gets\*(R" method is not
supported by adding a buffering \s-1BIO\s0 \fBBIO_f_buffer\fR\|(3) to the chain.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBBIO_should_retry\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fBBIO_gets()\fR on 1.1.0 and older when called on \fBBIO_fd()\fR based \s-1BIO\s0 did not
keep the '\en' at the end of the line in the buffer.
.PP
\&\fBBIO_get_line()\fR was added in OpenSSL 3.0.
.PP
\&\fBBIO_write_ex()\fR returns 1 if the size of the data to write is 0 and the
\&\fIwritten\fR parameter of the function can be \s-1NULL\s0 since OpenSSL 3.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

388
openssl-3.4.2/doc/man/man3/BIO_s_accept.3
View File

@@ -1,388 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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_S_ACCEPT 3ossl"
.TH BIO_S_ACCEPT 3ossl "2025-07-01" "3.4.2" "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_name, BIO_set_accept_port, BIO_get_accept_name,
BIO_get_accept_port, BIO_new_accept, BIO_set_nbio_accept, BIO_set_tfo_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>
\&
\& const BIO_METHOD *BIO_s_accept(void);
\&
\& long BIO_set_accept_name(BIO *b, char *name);
\& char *BIO_get_accept_name(BIO *b);
\&
\& long BIO_set_accept_port(BIO *b, char *port);
\& char *BIO_get_accept_port(BIO *b);
\&
\& BIO *BIO_new_accept(char *host_port);
\&
\& long BIO_set_nbio_accept(BIO *b, int n);
\& long BIO_set_tfo_accept(BIO *b, int n);
\& long BIO_set_accept_bios(BIO *b, char *bio);
\&
\& char *BIO_get_peer_name(BIO *b);
\& char *BIO_get_peer_port(BIO *b);
\& long BIO_get_accept_ip_family(BIO *b);
\& long BIO_set_accept_ip_family(BIO *b, long family);
\&
\& long BIO_set_bind_mode(BIO *b, long mode);
\& long BIO_get_bind_mode(BIO *b);
\&
\& int BIO_do_accept(BIO *b);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBBIO_s_accept()\fR returns the accept \s-1BIO\s0 method. This is a wrapper
round the platform's \s-1TCP/IP\s0 socket accept routines.
.PP
Using accept BIOs, \s-1TCP/IP\s0 connections can be accepted and data
transferred using only \s-1BIO\s0 routines. In this way any platform
specific operations are hidden by the \s-1BIO\s0 abstraction.
.PP
Read and write operations on an accept \s-1BIO\s0 will perform I/O
on the underlying connection. If no connection is established
and the port (see below) is set up properly then the \s-1BIO\s0
waits for an incoming connection.
.PP
Accept BIOs support \fBBIO_puts()\fR but not \fBBIO_gets()\fR.
.PP
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 \fBBIO_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
\&\fBBIO_get_fd()\fR and \fBBIO_set_fd()\fR can be called to retrieve or set
the accept socket. See \fBBIO_s_fd\fR\|(3)
.PP
\&\fBBIO_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 \*(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 \fBBIO_set_conn_port()\fR for
connect BIOs, that is it can be a numerical port string or a
string to lookup using \fBgetservbyname()\fR and a string table.
.PP
\&\fBBIO_set_accept_port()\fR uses the string \fBport\fR to set the accept
port of \s-1BIO\s0 \fIb\fR. \*(L"port\*(R" has the same syntax as the port specified in
\&\fBBIO_set_conn_port()\fR for connect BIOs, that is it can be a numerical
port string or a string to lookup using \fBgetservbyname()\fR and a string
table.
If the given port is \f(CW0\fR then a random available port is chosen.
It may be queried using \fBBIO_sock_info()\fR and \fBBIO_ADDR_service_string\fR\|(3).
.PP
\&\fBBIO_new_accept()\fR combines \fBBIO_new()\fR and \fBBIO_set_accept_name()\fR into
a single call: that is it creates a new accept \s-1BIO\s0 with port
\&\fBhost_port\fR.
.PP
\&\fBBIO_set_nbio_accept()\fR sets the accept socket to blocking mode
(the default) if \fBn\fR is 0 or non blocking mode if \fBn\fR is 1.
.PP
\&\fBBIO_set_tfo_accept()\fR enables \s-1TCP\s0 Fast Open on the accept socket
if \fBn\fR is 1 or disables \s-1TCP\s0 Fast Open if \fBn\fR is 0 (the default).
Setting the value to 1 is equivalent to setting \fB\s-1BIO_SOCK_TFO\s0\fR
in \fBBIO_set_bind_mode()\fR.
.PP
\&\fBBIO_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
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
\&\fBBIO_get_accept_ip_family()\fR returns the \s-1IP\s0 family accepted by the \s-1BIO\s0 \fIb\fR,
which may be \fB\s-1BIO_FAMILY_IPV4\s0\fR, \fB\s-1BIO_FAMILY_IPV6\s0\fR, or \fB\s-1BIO_FAMILY_IPANY\s0\fR.
.PP
\&\fBBIO_set_accept_ip_family()\fR sets the \s-1IP\s0 family \fIfamily\fR accepted by \s-1BIO\s0 \fIb\fR.
The default is \fB\s-1BIO_FAMILY_IPANY\s0\fR.
.PP
\&\fBBIO_set_bind_mode()\fR and \fBBIO_get_bind_mode()\fR set and retrieve
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
\&\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 \fB\s-1BIO_BIND_REUSEADDR\s0\fR. If \fB\s-1BIO_SOCK_TFO\s0\fR is set, then
the socket will be configured to accept \s-1TCP\s0 Fast Open
connections.
.PP
\&\fBBIO_do_accept()\fR serves two functions. When it is first
called, after the accept \s-1BIO\s0 has been setup, it will attempt
to create the accept socket and bind an address to it. Second
and subsequent calls to \fBBIO_do_accept()\fR will await an incoming
connection, or request a retry in non blocking mode.
.SH "NOTES"
.IX Header "NOTES"
When an accept \s-1BIO\s0 is at the end of a chain it will await an
incoming connection before processing I/O calls. When an accept
\&\s-1BIO\s0 is not at then end of a chain it passes I/O calls to the next
\&\s-1BIO\s0 in the chain.
.PP
When a connection is established a new socket \s-1BIO\s0 is created for
the connection and appended to the chain. That is the chain is now
accept\->socket. This effectively means that attempting I/O on
an initial accept socket will await an incoming connection then
perform I/O on it.
.PP
If any additional BIOs have been set using \fBBIO_set_accept_bios()\fR
then they are placed between the socket and the accept \s-1BIO,\s0
that is the chain will be accept\->otherbios\->socket.
.PP
If a server wishes to process multiple connections (as is normally
the case) then the accept \s-1BIO\s0 must be made available for further
incoming connections. This can be done by waiting for a connection and
then calling:
.PP
.Vb 1
\& connection = BIO_pop(accept);
.Ve
.PP
After this call \fBconnection\fR will contain a \s-1BIO\s0 for the recently
established connection and \fBaccept\fR will now be a single \s-1BIO\s0
again which can be used to await further incoming connections.
If no further connections will be accepted the \fBaccept\fR can
be freed using \fBBIO_free()\fR.
.PP
If only a single connection will be processed it is possible to
perform I/O using the accept \s-1BIO\s0 itself. This is often undesirable
however because the accept \s-1BIO\s0 will still accept additional incoming
connections. This can be resolved by using \fBBIO_pop()\fR (see above)
and freeing up the accept \s-1BIO\s0 after the initial connection.
.PP
If the underlying accept socket is nonblocking and \fBBIO_do_accept()\fR is
called to await an incoming connection it is possible for
\&\fBBIO_should_io_special()\fR with the reason \s-1BIO_RR_ACCEPT.\s0 If this happens
then it is an indication that an accept attempt would block: the application
should take appropriate action to wait until the underlying socket has
accepted a connection and retry the call.
.PP
\&\fBBIO_set_accept_name()\fR, \fBBIO_get_accept_name()\fR, \fBBIO_set_accept_port()\fR,
\&\fBBIO_get_accept_port()\fR, \fBBIO_set_nbio_accept()\fR, \fBBIO_set_accept_bios()\fR,
\&\fBBIO_get_peer_name()\fR, \fBBIO_get_peer_port()\fR,
\&\fBBIO_get_accept_ip_family()\fR, \fBBIO_set_accept_ip_family()\fR,
\&\fBBIO_set_bind_mode()\fR, \fBBIO_get_bind_mode()\fR and \fBBIO_do_accept()\fR are macros.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBBIO_do_accept()\fR,
\&\fBBIO_set_accept_name()\fR, \fBBIO_set_accept_port()\fR, \fBBIO_set_nbio_accept()\fR,
\&\fBBIO_set_accept_bios()\fR, \fBBIO_set_accept_ip_family()\fR, and \fBBIO_set_bind_mode()\fR
return 1 for success and <= 0 for failure.
.PP
\&\fBBIO_get_accept_name()\fR returns the accept name or \s-1NULL\s0 on error.
\&\fBBIO_get_peer_name()\fR returns the peer name or \s-1NULL\s0 on error.
.PP
\&\fBBIO_get_accept_port()\fR returns the accept port as a string or \s-1NULL\s0 on error.
\&\fBBIO_get_peer_port()\fR returns the peer port as a string or \s-1NULL\s0 on error.
\&\fBBIO_get_accept_ip_family()\fR returns the \s-1IP\s0 family or <= 0 on error.
.PP
\&\fBBIO_get_bind_mode()\fR returns the set of \fB\s-1BIO_BIND\s0\fR flags, or <= 0 on failure.
.PP
\&\fBBIO_new_accept()\fR returns a \s-1BIO\s0 or \s-1NULL\s0 on error.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
This example accepts two connections on port 4444, sends messages
down each and finally closes both down.
.PP
.Vb 1
\& BIO *abio, *cbio, *cbio2;
\&
\& /* First call to BIO_do_accept() sets up accept BIO */
\& 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(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(1);
\& }
\& fprintf(stderr, "Connection 2 established\en");
\&
\& /* Close accept BIO to refuse further connections */
\& cbio2 = BIO_pop(abio);
\& BIO_free(abio);
\& BIO_puts(cbio2, "Connection 2: Sending out Data on second\en");
\& 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 "HISTORY"
.IX Header "HISTORY"
\&\fBBIO_set_tfo_accept()\fR was added in OpenSSL 3.2.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2024 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

332
openssl-3.4.2/doc/man/man3/BIO_s_bio.3
View File

@@ -1,332 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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_S_BIO 3ossl"
.TH BIO_S_BIO 3ossl "2025-07-01" "3.4.2" "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
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bio.h>
\&
\& const BIO_METHOD *BIO_s_bio(void);
\&
\& int BIO_make_bio_pair(BIO *b1, BIO *b2);
\& int BIO_destroy_bio_pair(BIO *b);
\& int BIO_shutdown_wr(BIO *b);
\&
\& int BIO_set_write_buf_size(BIO *b, long size);
\& size_t BIO_get_write_buf_size(BIO *b, long size);
\&
\& int BIO_new_bio_pair(BIO **bio1, size_t writebuf1, BIO **bio2, size_t writebuf2);
\&
\& int BIO_get_write_guarantee(BIO *b);
\& size_t BIO_ctrl_get_write_guarantee(BIO *b);
\& int BIO_get_read_request(BIO *b);
\& size_t BIO_ctrl_get_read_request(BIO *b);
\& int BIO_ctrl_reset_read_request(BIO *b);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBBIO_s_bio()\fR returns the method for a \s-1BIO\s0 pair. A \s-1BIO\s0 pair is a pair of source/sink
BIOs where data written to either half of the pair is buffered and can be read from
the other half. Both halves must usually by handled by the same application thread
since no locking is done on the internal data structures.
.PP
Since \s-1BIO\s0 chains typically end in a source/sink \s-1BIO\s0 it is possible to make this
one half of a \s-1BIO\s0 pair and have all the data processed by the chain under application
control.
.PP
One typical use of \s-1BIO\s0 pairs is to place \s-1TLS/SSL I/O\s0 under application control, this
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 \fBBIO_read_ex()\fR will read data from the buffer or request a retry if no
data is available.
.PP
Calls to \fBBIO_write_ex()\fR will place data in the buffer or request a retry if the
buffer is full.
.PP
The standard calls \fBBIO_ctrl_pending()\fR and \fBBIO_ctrl_wpending()\fR can be used to
determine the amount of pending data in the read or write buffer.
.PP
\&\fBBIO_reset()\fR clears any data in the write buffer.
.PP
\&\fBBIO_make_bio_pair()\fR joins two separate BIOs into a connected pair.
.PP
\&\fBBIO_destroy_pair()\fR destroys the association between two connected BIOs. Freeing
up any half of the pair will automatically destroy the association.
.PP
\&\fBBIO_shutdown_wr()\fR is used to close down a \s-1BIO\s0 \fBb\fR. After this call no further
writes on \s-1BIO\s0 \fBb\fR are allowed (they will return an error). Reads on the other
half of the pair will return any pending data or \s-1EOF\s0 when all pending data has
been read.
.PP
\&\fBBIO_set_write_buf_size()\fR sets the write buffer size of \s-1BIO\s0 \fBb\fR to \fBsize\fR.
If the size is not initialized a default value is used. This is currently
17K, sufficient for a maximum size \s-1TLS\s0 record.
.PP
\&\fBBIO_get_write_buf_size()\fR returns the size of the write buffer.
.PP
\&\fBBIO_new_bio_pair()\fR combines the calls to \fBBIO_new()\fR, \fBBIO_make_bio_pair()\fR and
\&\fBBIO_set_write_buf_size()\fR to create a connected pair of BIOs \fBbio1\fR, \fBbio2\fR
with write buffer sizes \fBwritebuf1\fR and \fBwritebuf2\fR. If either size is
zero then the default size is used. \fBBIO_new_bio_pair()\fR does not check whether
\&\fBbio1\fR or \fBbio2\fR do point to some other \s-1BIO,\s0 the values are overwritten,
\&\fBBIO_free()\fR is not called.
.PP
\&\fBBIO_get_write_guarantee()\fR and \fBBIO_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 \fBBIO_write_ex()\fR less than the amount requested or
if the buffer is full request a retry. \fBBIO_ctrl_get_write_guarantee()\fR is a
function whereas \fBBIO_get_write_guarantee()\fR is a macro.
.PP
\&\fBBIO_get_read_request()\fR and \fBBIO_ctrl_get_read_request()\fR return the
amount of data requested, or the buffer size if it is less, if the
last read attempt at the other half of the \s-1BIO\s0 pair failed due to an
empty buffer. This can be used to determine how much data should be
written to the \s-1BIO\s0 so the next read will succeed: this is most useful
in \s-1TLS/SSL\s0 applications where the amount of data read is usually
meaningful rather than just a buffer size. After a successful read
this call will return zero. It also will return zero once new data
has been written satisfying the read request or part of it.
Note that \fBBIO_get_read_request()\fR never returns an amount larger
than that returned by \fBBIO_get_write_guarantee()\fR.
.PP
\&\fBBIO_ctrl_reset_read_request()\fR can also be used to reset the value returned by
\&\fBBIO_get_read_request()\fR to zero.
.SH "NOTES"
.IX Header "NOTES"
Both halves of a \s-1BIO\s0 pair should be freed. That is even if one half is implicit
freed due to a \fBBIO_free_all()\fR or \fBSSL_free()\fR call the other half needs to be freed.
.PP
When used in bidirectional applications (such as \s-1TLS/SSL\s0) care should be taken to
flush any data in the write buffer. This can be done by calling \fBBIO_pending()\fR
on the other half of the pair and, if any data is pending, reading it and sending
it to the underlying transport. This must be done before any normal processing
(such as calling \fBselect()\fR ) due to a request and \fBBIO_should_read()\fR being true.
.PP
To see why this is important consider a case where a request is sent using
\&\fBBIO_write_ex()\fR and a response read with \fBBIO_read_ex()\fR, this can occur during an
\&\s-1TLS/SSL\s0 handshake for example. \fBBIO_write_ex()\fR will succeed and place data in the
write buffer. \fBBIO_read_ex()\fR will initially fail and \fBBIO_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
\&\fBBIO_eof()\fR is true if no data is in the peer \s-1BIO\s0 and the peer \s-1BIO\s0 has been
shutdown.
.PP
\&\fBBIO_make_bio_pair()\fR, \fBBIO_destroy_bio_pair()\fR, \fBBIO_shutdown_wr()\fR,
\&\fBBIO_set_write_buf_size()\fR, \fBBIO_get_write_buf_size()\fR,
\&\fBBIO_get_write_guarantee()\fR, and \fBBIO_get_read_request()\fR are implemented
as macros.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBBIO_new_bio_pair()\fR returns 1 on success, with the new BIOs available in
\&\fBbio1\fR and \fBbio2\fR, or 0 on failure, with \s-1NULL\s0 pointers stored into the
locations for \fBbio1\fR and \fBbio2\fR. Check the error stack for more information.
.PP
[\s-1XXXXX:\s0 More return values need to be added here]
.SH "EXAMPLES"
.IX Header "EXAMPLES"
The \s-1BIO\s0 pair can be used to have full control over the network access of an
application. The application can call \fBselect()\fR on the socket as required
without having to go through the SSL-interface.
.PP
.Vb 1
\& BIO *internal_bio, *network_bio;
\&
\& ...
\& BIO_new_bio_pair(&internal_bio, 0, &network_bio, 0);
\& SSL_set_bio(ssl, internal_bio, internal_bio);
\& SSL_operations(); /* e.g. SSL_read and SSL_write */
\& ...
\&
\& application | TLS\-engine
\& | |
\& +\-\-\-\-\-\-\-\-\-\-> SSL_operations()
\& | /\e ||
\& | || \e/
\& | BIO\-pair (internal_bio)
\& | BIO\-pair (network_bio)
\& | || /\e
\& | \e/ ||
\& +\-\-\-\-\-\-\-\-\-\-\-< BIO_operations()
\& | |
\& | |
\& socket
\&
\& ...
\& SSL_free(ssl); /* implicitly frees internal_bio */
\& BIO_free(network_bio);
\& ...
.Ve
.PP
As the \s-1BIO\s0 pair will only buffer the data and never directly access the
connection, it behaves nonblocking and will return as soon as the write
buffer is full or the read buffer is drained. Then the application has to
flush the write buffer and/or fill the read buffer.
.PP
Use the \fBBIO_ctrl_pending()\fR, to find out whether data is buffered in the \s-1BIO\s0
and must be transferred to the network. Use \fBBIO_ctrl_get_read_request()\fR to
find out, how many bytes must be written into the buffer before the
\&\fBSSL_operation()\fR can successfully be continued.
.SH "WARNINGS"
.IX Header "WARNINGS"
As the data is buffered, \fBSSL_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 \fBSSL_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"
\&\fBSSL_set_bio\fR\|(3), \fBssl\fR\|(7), \fBbio\fR\|(7),
\&\fBBIO_should_retry\fR\|(3), \fBBIO_read_ex\fR\|(3)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

366
openssl-3.4.2/doc/man/man3/BIO_s_connect.3
View File

@@ -1,366 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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_S_CONNECT 3ossl"
.TH BIO_S_CONNECT 3ossl "2025-07-01" "3.4.2" "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_address, BIO_set_conn_ip_family,
BIO_get_conn_hostname, BIO_get_conn_port,
BIO_get_conn_address, BIO_get_conn_ip_family,
BIO_set_nbio, BIO_set_sock_type, BIO_get_sock_type, BIO_get0_dgram_bio,
BIO_do_connect \- connect BIO
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bio.h>
\&
\& const BIO_METHOD *BIO_s_connect(void);
\&
\& BIO *BIO_new_connect(const char *name);
\&
\& long BIO_set_conn_hostname(BIO *b, char *name);
\& long BIO_set_conn_port(BIO *b, char *port);
\& long BIO_set_conn_address(BIO *b, BIO_ADDR *addr);
\& long BIO_set_conn_ip_family(BIO *b, long family);
\& const char *BIO_get_conn_hostname(BIO *b);
\& const char *BIO_get_conn_port(BIO *b);
\& const BIO_ADDR *BIO_get_conn_address(BIO *b);
\& const long BIO_get_conn_ip_family(BIO *b);
\&
\& long BIO_set_nbio(BIO *b, long n);
\&
\& int BIO_set_sock_type(BIO *b, int sock_type);
\& int BIO_get_sock_type(BIO *b);
\& int BIO_get0_dgram_bio(BIO *B, BIO **dgram_bio);
\&
\& long BIO_do_connect(BIO *b);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBBIO_s_connect()\fR returns the connect \s-1BIO\s0 method. This is a wrapper
round the platform's \s-1TCP/IP\s0 socket connection routines.
.PP
Using connect BIOs, \s-1TCP/IP\s0 connections can be made and data
transferred using only \s-1BIO\s0 routines. In this way any platform
specific operations are hidden by the \s-1BIO\s0 abstraction.
.PP
Read and write operations on a connect \s-1BIO\s0 will perform I/O
on the underlying connection. If no connection is established
and the port and hostname (see below) is set up properly then
a connection is established first.
.PP
Connect BIOs support \fBBIO_puts()\fR and \fBBIO_gets()\fR.
.PP
If the close flag is set on a connect \s-1BIO\s0 then any active
connection is shutdown and the socket closed when the \s-1BIO\s0
is freed.
.PP
Calling \fBBIO_reset()\fR on a connect \s-1BIO\s0 will close any active
connection and reset the \s-1BIO\s0 into a state where it can connect
to the same host again.
.PP
\&\fBBIO_new_connect()\fR combines \fBBIO_new()\fR and \fBBIO_set_conn_hostname()\fR into
a single call: that is it creates a new connect \s-1BIO\s0 with hostname \fBname\fR.
.PP
\&\fBBIO_set_conn_hostname()\fR uses the string \fBname\fR to set the hostname.
The hostname can be an \s-1IP\s0 address; if the address is an IPv6 one, it
must be enclosed in brackets \f(CW\*(C`[\*(C'\fR and \f(CW\*(C`]\*(C'\fR.
The hostname can also include the port in the form hostname:port;
see \fBBIO_parse_hostserv\fR\|(3) and \fBBIO_set_conn_port()\fR for details.
.PP
\&\fBBIO_set_conn_port()\fR sets the port to \fBport\fR. \fBport\fR can be the
numerical form or a service string such as \*(L"http\*(R", which
will be mapped to a port number using the system function \fBgetservbyname()\fR.
.PP
\&\fBBIO_set_conn_address()\fR sets the address and port information using
a \s-1\fBBIO_ADDR\s0\fR\|(3ssl).
.PP
\&\fBBIO_set_conn_ip_family()\fR sets the \s-1IP\s0 family.
.PP
\&\fBBIO_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
\&\fBBIO_get_conn_port()\fR returns the port as a string.
This return value is an internal pointer which should not be modified.
.PP
\&\fBBIO_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
\&\fBBIO_get_conn_ip_family()\fR returns the \s-1IP\s0 family of the connect \s-1BIO.\s0
.PP
\&\fBBIO_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 \fBBIO_set_nbio()\fR
should be made before the connection is established because
non blocking I/O is set during the connect process.
.PP
\&\fBBIO_do_connect()\fR attempts to connect the supplied \s-1BIO.\s0
This performs an \s-1SSL/TLS\s0 handshake as far as supported by the \s-1BIO.\s0
For non-SSL BIOs the connection is done typically at \s-1TCP\s0 level.
If domain name resolution yields multiple \s-1IP\s0 addresses all of them are tried
after \fBconnect()\fR failures.
The function returns 1 if the connection was established successfully.
A zero or negative value is returned if the connection could not be established.
The call \fBBIO_should_retry()\fR should be used for non blocking connect BIOs
to determine if the call should be retried.
If a connection has already been established this call has no effect.
.PP
\&\fBBIO_set_sock_type()\fR can be used to set a socket type value as would be passed in
a call to \fBsocket\fR\|(2). The only currently supported values are \fB\s-1SOCK_STREAM\s0\fR (the
default) and \fB\s-1SOCK_DGRAM\s0\fR. If \fB\s-1SOCK_DGRAM\s0\fR is configured, the connection
created is a \s-1UDP\s0 datagram socket handled via \fBBIO_s_datagram\fR\|(3).
I/O calls such as \fBBIO_read\fR\|(3) and \fBBIO_write\fR\|(3) are forwarded transparently
to an internal \fBBIO_s_datagram\fR\|(3) instance. The created \fBBIO_s_datagram\fR\|(3)
instance can be retrieved using \fBBIO_get0_dgram_bio()\fR if desired, which writes
a pointer to the \fBBIO_s_datagram\fR\|(3) instance to \fI*dgram_bio\fR. The lifetime
of the internal \fBBIO_s_datagram\fR\|(3) is managed by \fBBIO_s_connect()\fR and does not
need to be freed by the caller.
.PP
\&\fBBIO_get_sock_type()\fR retrieves the value set using \fBBIO_set_sock_type()\fR.
.SH "NOTES"
.IX Header "NOTES"
If blocking I/O is set then a non positive return value from any
I/O call is caused by an error condition, although a zero return
will normally mean that the connection was closed.
.PP
If the port name is supplied as part of the hostname then this will
override any value set with \fBBIO_set_conn_port()\fR. This may be undesirable
if the application does not wish to allow connection to arbitrary
ports. This can be avoided by checking for the presence of the ':'
character in the passed hostname and either indicating an error or
truncating the string at that point.
.PP
The values returned by \fBBIO_get_conn_hostname()\fR, \fBBIO_get_conn_address()\fR,
and \fBBIO_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 \fBBIO_do_connect()\fR but may wish to do
so to separate the connection process from other I/O processing.
.PP
If non blocking I/O is set then retries will be requested as appropriate.
.PP
It addition to \fBBIO_should_read()\fR and \fBBIO_should_write()\fR it is also
possible for \fBBIO_should_io_special()\fR to be true during the initial
connection process with the reason \s-1BIO_RR_CONNECT.\s0 If this is returned
then this is an indication that a connection attempt would block,
the application should then take appropriate action to wait until
the underlying socket has connected and retry the call.
.PP
\&\fBBIO_set_conn_hostname()\fR, \fBBIO_set_conn_port()\fR, \fBBIO_get_conn_hostname()\fR,
\&\fBBIO_set_conn_address()\fR, \fBBIO_get_conn_port()\fR, \fBBIO_get_conn_address()\fR,
\&\fBBIO_set_conn_ip_family()\fR, \fBBIO_get_conn_ip_family()\fR,
\&\fBBIO_set_nbio()\fR, and \fBBIO_do_connect()\fR are macros.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBBIO_s_connect()\fR returns the connect \s-1BIO\s0 method.
.PP
\&\fBBIO_set_conn_address()\fR, \fBBIO_set_conn_port()\fR, and \fBBIO_set_conn_ip_family()\fR
return 1 or <=0 if an error occurs.
.PP
\&\fBBIO_set_conn_hostname()\fR returns 1 on success and <=0 on failure.
.PP
\&\fBBIO_get_conn_address()\fR returns the address information or \s-1NULL\s0 if none
was set.
.PP
\&\fBBIO_get_conn_hostname()\fR returns the connected hostname or \s-1NULL\s0 if
none was set.
.PP
\&\fBBIO_get_conn_ip_family()\fR returns the address family or \-1 if none was set.
.PP
\&\fBBIO_get_conn_port()\fR returns a string representing the connected
port or \s-1NULL\s0 if not set.
.PP
\&\fBBIO_set_nbio()\fR returns 1 or <=0 if an error occurs.
.PP
\&\fBBIO_do_connect()\fR returns 1 if the connection was successfully
established and <=0 if the connection failed.
.PP
\&\fBBIO_set_sock_type()\fR returns 1 on success or 0 on failure.
.PP
\&\fBBIO_get_sock_type()\fR returns a socket type or 0 if the call is not supported.
.PP
\&\fBBIO_get0_dgram_bio()\fR returns 1 on success or 0 on failure.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
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 3
\& BIO *cbio, *out;
\& int len;
\& char tmpbuf[1024];
\&
\& cbio = BIO_new_connect("localhost:http");
\& out = BIO_new_fp(stdout, BIO_NOCLOSE);
\& if (BIO_do_connect(cbio) <= 0) {
\& fprintf(stderr, "Error connecting to server\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);
\& }
\& BIO_free(cbio);
\& BIO_free(out);
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1\fBBIO_ADDR\s0\fR\|(3), \fBBIO_parse_hostserv\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fBBIO_set_conn_int_port()\fR, \fBBIO_get_conn_int_port()\fR, \fBBIO_set_conn_ip()\fR, and \fBBIO_get_conn_ip()\fR
were removed in OpenSSL 1.1.0.
Use \fBBIO_set_conn_address()\fR and \fBBIO_get_conn_address()\fR instead.
.PP
Connect BIOs support \fBBIO_gets()\fR since OpenSSL 3.2.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2024 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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
openssl-3.4.2/doc/man/man3/BIO_s_core.3
View File

@@ -1,205 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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_S_CORE 3ossl"
.TH BIO_S_CORE 3ossl "2025-07-01" "3.4.2" "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_core, BIO_new_from_core_bio \- OSSL_CORE_BIO functions
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bio.h>
\&
\& const BIO_METHOD *BIO_s_core(void);
\&
\& BIO *BIO_new_from_core_bio(OSSL_LIB_CTX *libctx, OSSL_CORE_BIO *corebio);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBBIO_s_core()\fR returns the core \s-1BIO\s0 method function.
.PP
A core \s-1BIO\s0 is treated as source/sink \s-1BIO\s0 which communicates to some external
\&\s-1BIO.\s0 This is primarily useful to provider authors. A number of calls from
libcrypto into a provider supply an \s-1OSSL_CORE_BIO\s0 parameter. This represents
a \s-1BIO\s0 within libcrypto, but cannot be used directly by a provider. Instead it
should be wrapped using a \fBBIO_s_core()\fR.
.PP
Once a \s-1BIO\s0 is constructed based on \fBBIO_s_core()\fR, the associated \s-1OSSL_CORE_BIO\s0
object should be set on it using \fBBIO_set_data\fR\|(3). Note that the \s-1BIO\s0 will only
operate correctly if it is associated with a library context constructed using
\&\fBOSSL_LIB_CTX_new_from_dispatch\fR\|(3). To associate the \s-1BIO\s0 with a library context
construct it using \fBBIO_new_ex\fR\|(3).
.PP
\&\fBBIO_new_from_core_bio()\fR is a convenience function that constructs a new \s-1BIO\s0
based on \fBBIO_s_core()\fR and that is associated with the given library context. It
then also sets the \s-1OSSL_CORE_BIO\s0 object on the \s-1BIO\s0 using \fBBIO_set_data\fR\|(3).
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBBIO_s_core()\fR return a core \s-1BIO\s0 \fB\s-1BIO_METHOD\s0\fR structure.
.PP
\&\fBBIO_new_from_core_bio()\fR returns a \s-1BIO\s0 structure on success or \s-1NULL\s0 on failure.
A failure will most commonly be because the library context was not constructed
using \fBOSSL_LIB_CTX_new_from_dispatch\fR\|(3).
.SH "HISTORY"
.IX Header "HISTORY"
\&\fBBIO_s_core()\fR and \fBBIO_new_from_core_bio()\fR were added in OpenSSL 3.0.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
Create a core \s-1BIO\s0 and write some data to it:
.PP
.Vb 2
\& int some_function(OSSL_LIB_CTX *libctx, OSSL_CORE_BIO *corebio) {
\& BIO *cbio = BIO_new_from_core_bio(libctx, corebio);
\&
\& if (cbio == NULL)
\& return 0;
\&
\& BIO_puts(cbio, "Hello World\en");
\&
\& BIO_free(cbio);
\& return 1;
\& }
.Ve
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2021\-2022 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

367
openssl-3.4.2/doc/man/man3/BIO_s_datagram.3
View File

@@ -1,367 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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_S_DATAGRAM 3ossl"
.TH BIO_S_DATAGRAM 3ossl "2025-07-01" "3.4.2" "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_datagram, BIO_new_dgram,
BIO_ctrl_dgram_connect,
BIO_ctrl_set_connected,
BIO_dgram_recv_timedout,
BIO_dgram_send_timedout,
BIO_dgram_get_peer,
BIO_dgram_set_peer,
BIO_dgram_detect_peer_addr,
BIO_dgram_get_mtu_overhead \- Network BIO with datagram semantics
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bio.h>
\&
\& BIO_METHOD *BIO_s_datagram(void);
\& BIO *BIO_new_dgram(int fd, int close_flag);
\&
\& int BIO_ctrl_dgram_connect(BIO *bio, const BIO_ADDR *peer);
\& int BIO_ctrl_set_connected(BIO *bio, const BIO_ADDR *peer);
\& int BIO_dgram_recv_timedout(BIO *bio);
\& int BIO_dgram_send_timedout(BIO *bio);
\& int BIO_dgram_get_peer(BIO *bio, BIO_ADDR *peer);
\& int BIO_dgram_set_peer(BIO *bio, const BIO_ADDR *peer);
\& int BIO_dgram_get_mtu_overhead(BIO *bio);
\& int BIO_dgram_detect_peer_addr(BIO *bio, BIO_ADDR *peer);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBBIO_s_datagram()\fR is a \s-1BIO\s0 implementation designed for use with network sockets
which provide datagram semantics, such as \s-1UDP\s0 sockets. It is suitable for use
with DTLSv1 or \s-1QUIC.\s0
.PP
Because \fBBIO_s_datagram()\fR has datagram semantics, a single \fBBIO_write()\fR call sends
a single datagram and a single \fBBIO_read()\fR call receives a single datagram. If
the size of the buffer passed to \fBBIO_read()\fR is inadequate, the datagram is
silently truncated.
.PP
For a memory-based \s-1BIO\s0 which provides datagram semantics identical to those of
\&\fBBIO_s_datagram()\fR, see \fBBIO_s_dgram_pair\fR\|(3).
.PP
This \s-1BIO\s0 supports the \fBBIO_sendmmsg\fR\|(3) and \fBBIO_recvmmsg\fR\|(3) functions.
.PP
When using \fBBIO_s_datagram()\fR, it is important to note that:
.IP "\(bu" 4
This \s-1BIO\s0 can be used with either a connected or unconnected network socket. A
connected socket is a network socket which has had \fBBIO_connect\fR\|(3) or a
similar OS-specific function called on it. Such a socket can only receive
datagrams from the specified peer. Any other socket is an unconnected socket and
can receive datagrams from any host.
.IP "\(bu" 4
Despite their naming,
neither \fBBIO_ctrl_dgram_connect()\fR nor \fBBIO_ctrl_set_connected()\fR cause a socket
to become connected. These controls are provided to indicate to the \s-1BIO\s0 how
the underlying socket is configured and how it is to be used; see below.
.IP "\(bu" 4
Use of \fBBIO_s_datagram()\fR with an unconnected network socket is hazardous hecause
any successful call to \fBBIO_read()\fR results in the peer address used for any
subsequent call to \fBBIO_write()\fR being set to the source address of the datagram
received by that call to \fBBIO_read()\fR. Thus, unless the caller calls
\&\fBBIO_dgram_set_peer()\fR immediately prior to every call to \fBBIO_write()\fR, or never
calls \fBBIO_read()\fR, any host on the network may cause future datagrams written to
be redirected to that host. Therefore, it is recommended that users either use
\&\fBBIO_s_dgram()\fR only with a connected socket, or, if using \fBBIO_s_dgram()\fR with an
unconnected socket, to use the \fBBIO_sendmmsg\fR\|(3) and \fBBIO_recvmmsg\fR\|(3) methods
only and forego use of \fBBIO_read\fR\|(3) and \fBBIO_write\fR\|(3). An exception is where
\&\fBDTLSv1_listen\fR\|(3) must be used; see \fBDTLSv1_listen\fR\|(3) for further
discussion.
.IP "\(bu" 4
Unlike \fBBIO_read\fR\|(3) and \fBBIO_write\fR\|(3), the \fBBIO_sendmmsg\fR\|(3) and
\&\fBBIO_recvmmsg\fR\|(3) methods are stateless and do not cause the internal state of
the \fBBIO_s_datagram()\fR to change.
.PP
Various controls are available for configuring the \fBBIO_s_datagram()\fR using
\&\fBBIO_ctrl\fR\|(3):
.IP "BIO_ctrl_dgram_connect (\s-1BIO_CTRL_DGRAM_CONNECT\s0)" 4
.IX Item "BIO_ctrl_dgram_connect (BIO_CTRL_DGRAM_CONNECT)"
This is equivalent to calling \fBBIO_dgram_set_peer\fR\|(3).
.Sp
Despite its name, this function does not cause the underlying socket to become
connected.
.IP "BIO_ctrl_set_connected (\s-1BIO_CTRL_SET_CONNECTED\s0)" 4
.IX Item "BIO_ctrl_set_connected (BIO_CTRL_SET_CONNECTED)"
This informs the \fBBIO_s_datagram()\fR whether the underlying socket has been
connected, and therefore how the \fBBIO_s_datagram()\fR should attempt to use the
socket.
.Sp
If the \fIpeer\fR argument is non-NULL, \fBBIO_s_datagram()\fR assumes that the
underlying socket has been connected and will attempt to use the socket using \s-1OS\s0
APIs which do not specify peer addresses (for example, \fBsend\fR\|(3) and \fBrecv\fR\|(3) or
similar). The \fIpeer\fR argument should specify the peer address to which the socket
is connected.
.Sp
If the \fIpeer\fR argument is \s-1NULL,\s0 \fBBIO_s_datagram()\fR assumes that the underlying
socket is not connected and will attempt to use the socket using an \s-1OS\s0 APIs
which specify peer addresses (for example, \fBsendto\fR\|(3) and \fBrecvfrom\fR\|(3)).
.Sp
This control does not affect the operation of \fBBIO_sendmmsg\fR\|(3) or
\&\fBBIO_recvmmsg\fR\|(3).
.IP "BIO_dgram_get_peer (\s-1BIO_CTRL_DGRAM_GET_PEER\s0)" 4
.IX Item "BIO_dgram_get_peer (BIO_CTRL_DGRAM_GET_PEER)"
This outputs a \fB\s-1BIO_ADDR\s0\fR which specifies one of the following values,
whichever happened most recently:
.RS 4
.IP "\(bu" 4
The peer address last passed to \fBBIO_dgram_set_peer()\fR, \fBBIO_ctrl_dgram_connect()\fR
or \fBBIO_ctrl_set_connected()\fR.
.IP "\(bu" 4
The peer address of the datagram last received by a call to \fBBIO_read()\fR.
.RE
.RS 4
.RE
.IP "BIO_dgram_set_peer (\s-1BIO_CTRL_DGRAM_SET_PEER\s0)" 4
.IX Item "BIO_dgram_set_peer (BIO_CTRL_DGRAM_SET_PEER)"
Sets the peer address to be used for subsequent writes to this \s-1BIO.\s0
.Sp
Warning: When used with an unconnected network socket, the value set may be
modified by future calls to \fBBIO_read\fR\|(3), making use of \fBBIO_s_datagram()\fR
hazardous when used with unconnected network sockets; see above.
.Sp
This does not affect the operation of \fBBIO_sendmmsg\fR\|(3).
\&\fBBIO_recvmmsg\fR\|(3) does not affect the value set by \fBBIO_dgram_set_peer()\fR.
.IP "BIO_dgram_detect_peer_addr (\s-1BIO_CTRL_DGRAM_DETECT_PEER_ADDR\s0)" 4
.IX Item "BIO_dgram_detect_peer_addr (BIO_CTRL_DGRAM_DETECT_PEER_ADDR)"
This is similar to \fBBIO_dgram_get_peer()\fR except that if the peer address has not
been set on the \s-1BIO\s0 object, an \s-1OS\s0 call such as \fBgetpeername\fR\|(2) will be attempted
to try and autodetect the peer address to which the underlying socket is
connected. Other BIOs may also implement this control if they are capable of
sensing a peer address, without necessarily also implementing
\&\fBBIO_dgram_set_peer()\fR and \fBBIO_dgram_get_peer()\fR.
.IP "BIO_dgram_recv_timeout (\s-1BIO_CTRL_DGRAM_GET_RECV_TIMER_EXP\s0)" 4
.IX Item "BIO_dgram_recv_timeout (BIO_CTRL_DGRAM_GET_RECV_TIMER_EXP)"
Returns 1 if the last I/O operation performed on the \s-1BIO\s0 (for example, via a
call to \fBBIO_read\fR\|(3)) may have been caused by a receive timeout.
.IP "BIO_dgram_send_timedout (\s-1BIO_CTRL_DGRAM_GET_SEND_TIMER_EXP\s0)" 4
.IX Item "BIO_dgram_send_timedout (BIO_CTRL_DGRAM_GET_SEND_TIMER_EXP)"
Returns 1 if the last I/O operation performed on the \s-1BIO\s0 (for example, via a
call to \fBBIO_write\fR\|(3)) may have been caused by a send timeout.
.IP "BIO_dgram_get_mtu_overhead (\s-1BIO_CTRL_DGRAM_GET_MTU_OVERHEAD\s0)" 4
.IX Item "BIO_dgram_get_mtu_overhead (BIO_CTRL_DGRAM_GET_MTU_OVERHEAD)"
Returns a quantity in bytes which is a rough estimate of the number of bytes of
overhead which should typically be added to a datagram payload size in order to
estimate the final size of the Layer 3 (e.g. \s-1IP\s0) packet which will contain the
datagram. In most cases, the maximum datagram payload size which can be
transmitted can be determined by determining the link \s-1MTU\s0 in bytes and
subtracting the value returned by this call.
.Sp
The value returned by this call depends on the network layer protocol being
used.
.Sp
The value returned is not fully reliable because datagram overheads can be
higher in atypical network configurations, for example where IPv6 extension
headers or IPv4 options are used.
.IP "\s-1BIO_CTRL_DGRAM_SET_DONT_FRAG\s0" 4
.IX Item "BIO_CTRL_DGRAM_SET_DONT_FRAG"
If \fInum\fR is nonzero, configures the underlying network socket to enable Don't
Fragment mode, in which datagrams will be set with the \s-1IP\s0 Don't Fragment (\s-1DF\s0)
bit set. If \fInum\fR is zero, Don't Fragment mode is disabled.
.IP "\s-1BIO_CTRL_DGRAM_QUERY_MTU\s0" 4
.IX Item "BIO_CTRL_DGRAM_QUERY_MTU"
Queries the \s-1OS\s0 for its assessment of the Path \s-1MTU\s0 for the destination to which
the underlying network socket, and returns that Path \s-1MTU\s0 in bytes. This control
can only be used with a connected socket.
.Sp
This is not supported on all platforms and depends on \s-1OS\s0 support being
available. Returns 0 on failure.
.IP "\s-1BIO_CTRL_DGRAM_MTU_DISCOVER\s0" 4
.IX Item "BIO_CTRL_DGRAM_MTU_DISCOVER"
This control requests that Path \s-1MTU\s0 discovery be enabled on the underlying
network socket.
.IP "\s-1BIO_CTRL_DGRAM_GET_FALLBACK_MTU\s0" 4
.IX Item "BIO_CTRL_DGRAM_GET_FALLBACK_MTU"
Returns the estimated minimum size of datagram payload which should always be
supported on the \s-1BIO.\s0 This size is determined by the minimum \s-1MTU\s0 required to be
supported by the applicable underlying network layer. Use of datagrams of this
size may lead to suboptimal performance, but should be routable in all
circumstances. The value returned is the datagram payload size in bytes and does
not include the size of layer 3 or layer 4 protocol headers.
.IP "\s-1BIO_CTRL_DGRAM_MTU_EXCEEDED\s0" 4
.IX Item "BIO_CTRL_DGRAM_MTU_EXCEEDED"
Returns 1 if the last attempted write to the \s-1BIO\s0 failed due to the size of the
attempted write exceeding the applicable \s-1MTU.\s0
.IP "\s-1BIO_CTRL_DGRAM_SET_NEXT_TIMEOUT\s0" 4
.IX Item "BIO_CTRL_DGRAM_SET_NEXT_TIMEOUT"
Accepts a pointer to a \fBstruct timeval\fR. If the time specified is zero,
disables receive timeouts. Otherwise, configures the specified time interval as
the receive timeout for the socket for the purposes of future \fBBIO_read\fR\|(3)
calls.
.IP "\s-1BIO_CTRL_DGRAM_SET_PEEK_MODE\s0" 4
.IX Item "BIO_CTRL_DGRAM_SET_PEEK_MODE"
If \fBnum\fR is nonzero, enables peek mode; otherwise, disables peek mode. Where
peek mode is enabled, calls to \fBBIO_read\fR\|(3) read datagrams from the underlying
network socket in peek mode, meaning that a future call to \fBBIO_read\fR\|(3) will
yield the same datagram until peek mode is disabled.
.Sp
\&\fBBIO_recvmmsg\fR\|(3) is not affected by this control.
.PP
\&\fBBIO_new_dgram()\fR is a helper function which instantiates a \fBBIO_s_datagram()\fR and
sets the \s-1BIO\s0 to use the socket given in \fIfd\fR by calling \fBBIO_set_fd()\fR.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBBIO_s_datagram()\fR returns a \s-1BIO\s0 method.
.PP
\&\fBBIO_new_dgram()\fR returns a \s-1BIO\s0 on success and \s-1NULL\s0 on failure.
.PP
\&\fBBIO_ctrl_dgram_connect()\fR, \fBBIO_ctrl_set_connected()\fR and \fBBIO_dgram_set_peer()\fR
return 1 on success and 0 on failure.
.PP
\&\fBBIO_dgram_get_peer()\fR and \fBBIO_dgram_detect_peer_addr()\fR return 0 on failure and
the number of bytes for the outputted address representation (a positive value)
on success.
.PP
\&\fBBIO_dgram_recv_timedout()\fR and \fBBIO_dgram_send_timedout()\fR return 0 or 1 depending
on the circumstance; see discussion above.
.PP
\&\fBBIO_dgram_get_mtu_overhead()\fR returns a value in bytes.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBBIO_sendmmsg\fR\|(3), \fBBIO_s_dgram_pair\fR\|(3), \fBDTLSv1_listen\fR\|(3), \fBbio\fR\|(7)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2022\-2023 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

343
openssl-3.4.2/doc/man/man3/BIO_s_dgram_pair.3
View File

@@ -1,343 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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_S_DGRAM_PAIR 3ossl"
.TH BIO_S_DGRAM_PAIR 3ossl "2025-07-01" "3.4.2" "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_dgram_pair, BIO_new_bio_dgram_pair, BIO_dgram_set_no_trunc,
BIO_dgram_get_no_trunc, BIO_dgram_get_effective_caps, BIO_dgram_get_caps,
BIO_dgram_set_caps, BIO_dgram_set_mtu, BIO_dgram_get_mtu \- datagram pair BIO
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bio.h>
\&
\& const BIO_METHOD *BIO_s_dgram_pair(void);
\&
\& int BIO_new_bio_dgram_pair(BIO **bio1, size_t writebuf1,
\& BIO **bio2, size_t writebuf2);
\& int BIO_dgram_set_no_trunc(BIO *bio, int enable);
\& int BIO_dgram_get_no_trunc(BIO *bio);
\& uint32_t BIO_dgram_get_effective_caps(BIO *bio);
\& uint32_t BIO_dgram_get_caps(BIO *bio);
\& int BIO_dgram_set_caps(BIO *bio, uint32_t caps);
\& int BIO_dgram_set_mtu(BIO *bio, unsigned int mtu);
\& unsigned int BIO_dgram_get_mtu(BIO *bio);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBBIO_s_dgram_pair()\fR returns the method for a \s-1BIO\s0 datagram pair. A \s-1BIO\s0 datagram
pair is similar to a \s-1BIO\s0 pair (see \fBBIO_s_bio\fR\|(3)) but has datagram semantics.
Broadly, this means that the length of the buffer passed to a write call will
match that retrieved by a read call. If the buffer passed to a read call is too
short, the datagram is truncated or the read fails, depending on how the \s-1BIO\s0 is
configured.
.PP
The \s-1BIO\s0 datagram pair attaches certain metadata to each write, such as source
and destination addresses. This information may be retrieved on read.
.PP
A typical application of a \s-1BIO\s0 datagram pair is to allow an application to keep
all datagram network I/O requested by libssl under application control.
.PP
The \s-1BIO\s0 datagram pair is designed to support multithreaded use where certain
restrictions are observed; see \s-1THREADING.\s0
.PP
The \s-1BIO\s0 datagram pair allows each half of a pair to signal to the other half
whether they support certain capabilities; see \s-1CAPABILITY INDICATION.\s0
.PP
\&\fBBIO_new_bio_dgram_pair()\fR combines the calls to \fBBIO_new\fR\|(3),
\&\fBBIO_make_bio_pair\fR\|(3) and \fBBIO_set_write_buf_size\fR\|(3) to create a connected
pair of BIOs \fBbio1\fR, \fBbio2\fR with write buffer sizes \fBwritebuf1\fR and
\&\fBwritebuf2\fR. If either size is zero then the default size is used.
.PP
\&\fBBIO_make_bio_pair\fR\|(3) may be used to join two datagram pair BIOs into a pair.
The two BIOs must both use the method returned by \fBBIO_s_dgram_pair()\fR and neither
of the BIOs may currently be associated in a pair.
.PP
\&\fBBIO_destroy_bio_pair\fR\|(3) destroys the association between two connected BIOs.
Freeing either half of the pair will automatically destroy the association.
.PP
\&\fBBIO_reset\fR\|(3) clears any data in the write buffer of the given \s-1BIO.\s0 This means
that the opposite \s-1BIO\s0 in the pair will no longer have any data waiting to be
read.
.PP
The \s-1BIO\s0 maintains a fixed size internal write buffer. When the buffer is full,
further writes will fail until the buffer is drained via calls to
\&\fBBIO_read\fR\|(3). The size of the buffer can be changed using
\&\fBBIO_set_write_buf_size\fR\|(3) and queried using \fBBIO_get_write_buf_size\fR\|(3).
.PP
Note that the write buffer is partially consumed by metadata stored internally
which is attached to each datagram, such as source and destination addresses.
The size of this overhead is undefined and may change between releases.
.PP
The standard \fBBIO_ctrl_pending\fR\|(3) call has modified behaviour and returns the
size of the next datagram waiting to be read in bytes. An application can use
this function to ensure it provides an adequate buffer to a subsequent read
call. If no datagram is waiting to be read, zero is returned.
.PP
This \s-1BIO\s0 does not support sending or receiving zero-length datagrams. Passing a
zero-length buffer to BIO_write is treated as a no-op.
.PP
\&\fBBIO_eof\fR\|(3) returns 1 only if the given \s-1BIO\s0 datagram pair \s-1BIO\s0 is not currently
connected to a peer \s-1BIO.\s0
.PP
\&\fBBIO_get_write_guarantee\fR\|(3) and \fBBIO_ctrl_get_write_guarantee\fR\|(3) return how
large a datagram the next call to \fBBIO_write\fR\|(3) can accept. If there is not
enough space in the write buffer to accept another datagram equal in size to the
configured \s-1MTU,\s0 zero is returned (see below). This is intended to avoid a
situation where an application attempts to read a datagram from a network
intending to write it to a \s-1BIO\s0 datagram pair, but where the received datagram
ends up being too large to write to the \s-1BIO\s0 datagram pair.
.PP
\&\fBBIO_dgram_set_no_trunc()\fR and \fBBIO_ctrl_get_no_trunc()\fR set and retrieve the
truncation mode for the given half of a \s-1BIO\s0 datagram pair. When no-truncate mode
is enabled, \fBBIO_read()\fR will fail if the buffer provided is inadequate to hold
the next datagram to be read. If no-truncate mode is disabled (the default), the
datagram will be silently truncated. This default behaviour maintains
compatibility with the semantics of the Berkeley sockets \s-1API.\s0
.PP
\&\fBBIO_dgram_set_mtu()\fR and \fBBIO_dgram_get_mtu()\fR may be used to set an informational
\&\s-1MTU\s0 value on the \s-1BIO\s0 datagram pair. If \fBBIO_dgram_set_mtu()\fR is used on a \s-1BIO\s0
which is currently part of a \s-1BIO\s0 datagram pair, the \s-1MTU\s0 value is set on both
halves of the pair. The value does not affect the operation of the \s-1BIO\s0 datagram
pair (except for \fBBIO_get_write_guarantee()\fR; see above) but may be used by other
code to determine a requested \s-1MTU.\s0 When a \s-1BIO\s0 datagram pair \s-1BIO\s0 is created, the
\&\s-1MTU\s0 is set to an unspecified but valid value.
.PP
\&\fBBIO_flush\fR\|(3) is a no-op.
.SH "NOTES"
.IX Header "NOTES"
The halves of a \s-1BIO\s0 datagram pair have independent lifetimes and must be
separately freed.
.SH "THREADING"
.IX Header "THREADING"
\&\fBBIO_recvmmsg\fR\|(3), \fBBIO_sendmmsg\fR\|(3), \fBBIO_read\fR\|(3), \fBBIO_write\fR\|(3),
\&\fBBIO_pending\fR\|(3), \fBBIO_get_write_guarantee\fR\|(3) and \fBBIO_flush\fR\|(3) may be used
by multiple threads simultaneously on the same \s-1BIO\s0 datagram pair. Specific
\&\fBBIO_ctrl\fR\|(3) operations (namely \s-1BIO_CTRL_PENDING, BIO_CTRL_FLUSH\s0 and
\&\s-1BIO_C_GET_WRITE_GUARANTEE\s0) may also be used. Invoking any other \s-1BIO\s0 call, or any
other \fBBIO_ctrl\fR\|(3) operation, on either half of a \s-1BIO\s0 datagram pair while any
other \s-1BIO\s0 call is also in progress to either half of the same \s-1BIO\s0 datagram pair
results in undefined behaviour.
.SH "CAPABILITY INDICATION"
.IX Header "CAPABILITY INDICATION"
The \s-1BIO\s0 datagram pair can be used to enqueue datagrams which have source and
destination addresses attached. It is important that the component consuming one
side of a \s-1BIO\s0 datagram pair understand whether the other side of the pair will
honour any source and destination addresses it attaches to each datagram. For
example, if datagrams are queued with destination addresses set but simply read
by simple calls to \fBBIO_read\fR\|(3), the destination addresses will be discarded.
.PP
Each half of a \s-1BIO\s0 datagram pair can have capability flags set on it which
indicate whether source and destination addresses will be honoured by the reader
and whether they will be provided by the writer. These capability flags should
be set via a call to \fBBIO_dgram_set_caps()\fR, and these capabilities will be
reflected in the value returned by \fBBIO_dgram_get_effective_caps()\fR on the
opposite \s-1BIO.\s0 If necessary, the capability value previously set can be retrieved
using \fBBIO_dgram_get_caps()\fR. Note that \fBBIO_dgram_set_caps()\fR on a given \s-1BIO\s0
controls the capabilities advertised to the peer, and
\&\fBBIO_dgram_get_effective_caps()\fR on a given \s-1BIO\s0 determines the capabilities
advertised by the peer of that \s-1BIO.\s0
.PP
The following capabilities are available:
.IP "\fB\s-1BIO_DGRAM_CAP_HANDLES_SRC_ADDR\s0\fR" 4
.IX Item "BIO_DGRAM_CAP_HANDLES_SRC_ADDR"
The user of the datagram pair \s-1BIO\s0 promises to honour source addresses provided
with datagrams written to the \s-1BIO\s0 pair.
.IP "\fB\s-1BIO_DGRAM_CAP_HANDLES_DST_ADDR\s0\fR" 4
.IX Item "BIO_DGRAM_CAP_HANDLES_DST_ADDR"
The user of the datagram pair \s-1BIO\s0 promises to honour destination addresses provided
with datagrams written to the \s-1BIO\s0 pair.
.IP "\fB\s-1BIO_DGRAM_CAP_PROVIDES_SRC_ADDR\s0\fR" 4
.IX Item "BIO_DGRAM_CAP_PROVIDES_SRC_ADDR"
The user of the datagram pair \s-1BIO\s0 advertises the fact that it will provide source
addressing information with future writes to the \s-1BIO\s0 pair, where available.
.IP "\fB\s-1BIO_DGRAM_CAP_PROVIDES_DST_ADDR\s0\fR" 4
.IX Item "BIO_DGRAM_CAP_PROVIDES_DST_ADDR"
The user of the datagram pair \s-1BIO\s0 advertises the fact that it will provide
destination addressing information with future writes to the \s-1BIO\s0 pair, where
available.
.PP
If a caller attempts to specify a destination address (for example, using
\&\fBBIO_sendmmsg\fR\|(3)) and the peer has not advertised the
\&\fB\s-1BIO_DGRAM_CAP_HANDLES_DST_ADDR\s0\fR capability, the operation fails. Thus,
capability negotiation is mandatory.
.PP
If a caller attempts to specify a source address when writing, or requests a
destination address when receiving, and local address support has not been
enabled, the operation fails; see \fBBIO_dgram_set_local_addr_enable\fR\|(3).
.PP
If a caller attempts to enable local address support using
\&\fBBIO_dgram_set_local_addr_enable\fR\|(3) and \fBBIO_dgram_get_local_addr_cap\fR\|(3)
does not return 1 (meaning that the peer has not advertised both the
\&\fB\s-1BIO_DGRAM_CAP_HANDLES_SRC_ADDR\s0\fR and the \fB\s-1BIO_DGRAM_CAP_PROVIDES_DST_ADDR\s0\fR
capability), the operation fails.
.PP
\&\fB\s-1BIO_DGRAM_CAP_PROVIDES_SRC_ADDR\s0\fR and \fB\s-1BIO_DGRAM_CAP_PROVIDES_DST_ADDR\s0\fR
indicate that the application using that half of a \s-1BIO\s0 datagram pair promises to
provide source and destination addresses respectively when writing datagrams to
that half of the \s-1BIO\s0 datagram pair. However, these capability flags do not
affect the behaviour of the \s-1BIO\s0 datagram pair.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBBIO_new_bio_dgram_pair()\fR returns 1 on success, with the new BIOs available in
\&\fBbio1\fR and \fBbio2\fR, or 0 on failure, with \s-1NULL\s0 pointers stored into the
locations for \fBbio1\fR and \fBbio2\fR. Check the error stack for more information.
.PP
\&\fBBIO_dgram_set_no_trunc()\fR, \fBBIO_dgram_set_caps()\fR and \fBBIO_dgram_set_mtu()\fR return 1
on success and 0 on failure.
.PP
\&\fBBIO_dgram_get_no_trunc()\fR returns 1 if no-truncate mode is enabled on a \s-1BIO,\s0 or 0
if no-truncate mode is not enabled or not supported on a given \s-1BIO.\s0
.PP
\&\fBBIO_dgram_get_effective_caps()\fR and \fBBIO_dgram_get_caps()\fR return zero if no
capabilities are supported.
.PP
\&\fBBIO_dgram_get_mtu()\fR returns the \s-1MTU\s0 value configured on the \s-1BIO,\s0 or zero if the
operation is not supported.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBBIO_s_bio\fR\|(3), \fBbio\fR\|(7)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2022 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

230
openssl-3.4.2/doc/man/man3/BIO_s_fd.3
View File

@@ -1,230 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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_S_FD 3ossl"
.TH BIO_S_FD 3ossl "2025-07-01" "3.4.2" "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_fd, BIO_set_fd, BIO_get_fd, BIO_new_fd \- file descriptor BIO
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bio.h>
\&
\& const BIO_METHOD *BIO_s_fd(void);
\&
\& int BIO_set_fd(BIO *b, int fd, int c);
\& int BIO_get_fd(BIO *b, int *c);
\&
\& BIO *BIO_new_fd(int fd, int close_flag);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBBIO_s_fd()\fR returns the file descriptor \s-1BIO\s0 method. This is a wrapper
round the platforms file descriptor routines such as \fBread()\fR and \fBwrite()\fR.
.PP
\&\fBBIO_read_ex()\fR and \fBBIO_write_ex()\fR read or write the underlying descriptor.
\&\fBBIO_puts()\fR is supported but \fBBIO_gets()\fR is not.
.PP
If the close flag is set then \fBclose()\fR is called on the underlying
file descriptor when the \s-1BIO\s0 is freed.
.PP
\&\fBBIO_reset()\fR attempts to change the file pointer to the start of file
such as by using \fBlseek(fd, 0, 0)\fR.
.PP
\&\fBBIO_seek()\fR sets the file pointer to position \fBofs\fR from start of file
such as by using \fBlseek(fd, ofs, 0)\fR.
.PP
\&\fBBIO_tell()\fR returns the current file position such as by calling
\&\fBlseek(fd, 0, 1)\fR.
.PP
\&\fBBIO_set_fd()\fR sets the file descriptor of \s-1BIO\s0 \fBb\fR to \fBfd\fR and the close
flag to \fBc\fR.
.PP
\&\fBBIO_get_fd()\fR places the file descriptor of \s-1BIO\s0 \fBb\fR in \fBc\fR if it is not \s-1NULL.\s0
It also returns the file descriptor.
.PP
\&\fBBIO_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 \fBBIO_read_ex()\fR and \fBBIO_write_ex()\fR depends on the behavior of the
platforms \fBread()\fR and \fBwrite()\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 \fBBIO_read_ex\fR\|(3) and \fBBIO_should_retry\fR\|(3)
manual pages.
.PP
File descriptor BIOs should not be used for socket I/O. Use socket BIOs
instead.
.PP
\&\fBBIO_set_fd()\fR and \fBBIO_get_fd()\fR are implemented as macros.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBBIO_s_fd()\fR returns the file descriptor \s-1BIO\s0 method.
.PP
\&\fBBIO_set_fd()\fR returns 1 on success or <=0 for failure.
.PP
\&\fBBIO_get_fd()\fR returns the file descriptor or \-1 if the \s-1BIO\s0 has not
been initialized. It also returns zero and negative values if other error occurs.
.PP
\&\fBBIO_new_fd()\fR returns the newly allocated \s-1BIO\s0 or \s-1NULL\s0 is an error
occurred.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
This is a file descriptor \s-1BIO\s0 version of \*(L"Hello World\*(R":
.PP
.Vb 1
\& BIO *out;
\&
\& out = BIO_new_fd(fileno(stdout), BIO_NOCLOSE);
\& BIO_printf(out, "Hello World\en");
\& BIO_free(out);
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBBIO_seek\fR\|(3), \fBBIO_tell\fR\|(3),
\&\fBBIO_reset\fR\|(3), \fBBIO_read_ex\fR\|(3),
\&\fBBIO_write_ex\fR\|(3), \fBBIO_puts\fR\|(3),
\&\fBBIO_gets\fR\|(3), \fBBIO_printf\fR\|(3),
\&\fBBIO_set_close\fR\|(3), \fBBIO_get_close\fR\|(3)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2021 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

304
openssl-3.4.2/doc/man/man3/BIO_s_file.3
View File

@@ -1,304 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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_S_FILE 3ossl"
.TH BIO_S_FILE 3ossl "2025-07-01" "3.4.2" "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
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bio.h>
\&
\& const BIO_METHOD *BIO_s_file(void);
\& BIO *BIO_new_file(const char *filename, const char *mode);
\& BIO *BIO_new_fp(FILE *stream, int flags);
\&
\& BIO_set_fp(BIO *b, FILE *fp, int flags);
\& BIO_get_fp(BIO *b, FILE **fpp);
\&
\& int BIO_read_filename(BIO *b, char *name);
\& int BIO_write_filename(BIO *b, char *name);
\& int BIO_append_filename(BIO *b, char *name);
\& int BIO_rw_filename(BIO *b, char *name);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBBIO_s_file()\fR returns the \s-1BIO\s0 file method. As its name implies it
is a wrapper round the stdio \s-1FILE\s0 structure and it is a
source/sink \s-1BIO.\s0
.PP
Calls to \fBBIO_read_ex()\fR and \fBBIO_write_ex()\fR read and write data to the
underlying stream. \fBBIO_gets()\fR and \fBBIO_puts()\fR are supported on file BIOs.
.PP
\&\fBBIO_flush()\fR on a file \s-1BIO\s0 calls the \fBfflush()\fR function on the wrapped
stream.
.PP
\&\fBBIO_reset()\fR attempts to change the file pointer to the start of file
using fseek(stream, 0, 0).
.PP
\&\fBBIO_seek()\fR sets the file pointer to position \fBofs\fR from start of file
using fseek(stream, ofs, 0).
.PP
\&\fBBIO_eof()\fR calls \fBfeof()\fR.
.PP
Setting the \s-1BIO_CLOSE\s0 flag calls \fBfclose()\fR on the stream when the \s-1BIO\s0
is freed.
.PP
\&\fBBIO_new_file()\fR creates a new file \s-1BIO\s0 with mode \fBmode\fR the meaning
of \fBmode\fR is the same as the stdio function \fBfopen()\fR. The \s-1BIO_CLOSE\s0
flag is set on the returned \s-1BIO.\s0
.PP
\&\fBBIO_new_fp()\fR creates a file \s-1BIO\s0 wrapping \fBstream\fR. Flags can be:
\&\s-1BIO_CLOSE, BIO_NOCLOSE\s0 (the close flag) \s-1BIO_FP_TEXT\s0 (sets the underlying
stream to text mode, default is binary: this only has any effect under
Win32).
.PP
\&\fBBIO_set_fp()\fR sets the fp of a file \s-1BIO\s0 to \fBfp\fR. \fBflags\fR has the same
meaning as in \fBBIO_new_fp()\fR, it is a macro.
.PP
\&\fBBIO_get_fp()\fR retrieves the fp of a file \s-1BIO,\s0 it is a macro.
.PP
\&\fBBIO_seek()\fR is a macro that sets the position pointer to \fBoffset\fR bytes
from the start of file.
.PP
\&\fBBIO_tell()\fR returns the value of the position pointer.
.PP
\&\fBBIO_read_filename()\fR, \fBBIO_write_filename()\fR, \fBBIO_append_filename()\fR and
\&\fBBIO_rw_filename()\fR set the file \s-1BIO\s0 \fBb\fR to use file \fBname\fR for
reading, writing, append or read write respectively.
.SH "NOTES"
.IX Header "NOTES"
When wrapping stdout, stdin or stderr the underlying stream should not
normally be closed so the \s-1BIO_NOCLOSE\s0 flag should be set.
.PP
Because the file \s-1BIO\s0 calls the underlying stdio functions any quirks
in stdio behaviour will be mirrored by the corresponding \s-1BIO.\s0
.PP
On Windows BIO_new_files reserves for the filename argument to be
\&\s-1UTF\-8\s0 encoded. In other words if you have to make it work in multi\-
lingual environment, encode filenames in \s-1UTF\-8.\s0
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBBIO_s_file()\fR returns the file \s-1BIO\s0 method.
.PP
\&\fBBIO_new_file()\fR and \fBBIO_new_fp()\fR return a file \s-1BIO\s0 or \s-1NULL\s0 if an error
occurred.
.PP
\&\fBBIO_set_fp()\fR and \fBBIO_get_fp()\fR return 1 for success or <=0 for failure
(although the current implementation never return 0).
.PP
\&\fBBIO_seek()\fR returns 0 for success or negative values for failure.
.PP
\&\fBBIO_tell()\fR returns the current file position or negative values for failure.
.PP
\&\fBBIO_read_filename()\fR, \fBBIO_write_filename()\fR, \fBBIO_append_filename()\fR and
\&\fBBIO_rw_filename()\fR return 1 for success or <=0 for failure.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
File \s-1BIO\s0 \*(L"hello world\*(R":
.PP
.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 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) <= 0)
\& /* Error */
\& BIO_printf(bio_out, "Hello World\en");
.Ve
.PP
Write to a file:
.PP
.Vb 1
\& BIO *out;
\&
\& out = BIO_new_file("filename.txt", "w");
\& if (!out)
\& /* Error */
\& BIO_printf(out, "Hello World\en");
\& BIO_free(out);
.Ve
.PP
Alternative technique:
.PP
.Vb 1
\& BIO *out;
\&
\& out = BIO_new(BIO_s_file());
\& if (out == NULL)
\& /* Error */
\& if (BIO_write_filename(out, "filename.txt") <= 0)
\& /* Error */
\& BIO_printf(out, "Hello World\en");
\& BIO_free(out);
.Ve
.SH "BUGS"
.IX Header "BUGS"
\&\fBBIO_reset()\fR and \fBBIO_seek()\fR are implemented using \fBfseek()\fR on the underlying
stream. The return value for \fBfseek()\fR is 0 for success or \-1 if an error
occurred this differs from other types of \s-1BIO\s0 which will typically return
1 for success and a non positive value if an error occurred.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBBIO_seek\fR\|(3), \fBBIO_tell\fR\|(3),
\&\fBBIO_reset\fR\|(3), \fBBIO_flush\fR\|(3),
\&\fBBIO_read_ex\fR\|(3),
\&\fBBIO_write_ex\fR\|(3), \fBBIO_puts\fR\|(3),
\&\fBBIO_gets\fR\|(3), \fBBIO_printf\fR\|(3),
\&\fBBIO_set_close\fR\|(3), \fBBIO_get_close\fR\|(3)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

351
openssl-3.4.2/doc/man/man3/BIO_s_mem.3
View File

@@ -1,351 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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_S_MEM 3ossl"
.TH BIO_S_MEM 3ossl "2025-07-01" "3.4.2" "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_secmem, BIO_s_dgram_mem,
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>
\&
\& const BIO_METHOD *BIO_s_mem(void);
\& const BIO_METHOD *BIO_s_dgram_mem(void);
\& const BIO_METHOD *BIO_s_secmem(void);
\&
\& BIO_set_mem_eof_return(BIO *b, int v);
\& long BIO_get_mem_data(BIO *b, char **pp);
\& BIO_set_mem_buf(BIO *b, BUF_MEM *bm, int c);
\& BIO_get_mem_ptr(BIO *b, BUF_MEM **pp);
\&
\& BIO *BIO_new_mem_buf(const void *buf, int len);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBBIO_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
\&\fBBIO_s_secmem()\fR is like \fBBIO_s_mem()\fR except that the secure heap is used
for buffer storage.
.PP
\&\fBBIO_s_dgram_mem()\fR is a memory \s-1BIO\s0 that respects datagram semantics. A single
call to \fBBIO_write\fR\|(3) will write a single datagram to the memory \s-1BIO. A\s0
subsequent call to \fBBIO_read\fR\|(3) will read the data in that datagram. The
\&\fBBIO_read\fR\|(3) call will never return more data than was written in the original
\&\fBBIO_write\fR\|(3) call even if there were subsequent \fBBIO_write\fR\|(3) calls that
wrote more datagrams. Each successive call to \fBBIO_read\fR\|(3) will read the next
datagram. If a \fBBIO_read\fR\|(3) call supplies a read buffer that is smaller than
the size of the datagram, then the read buffer will be completely filled and the
remaining data from the datagram will be discarded.
.PP
It is not possible to write a zero length datagram. Calling \fBBIO_write\fR\|(3) in
this case will return 0 and no datagrams will be written. Calling \fBBIO_read\fR\|(3)
when there are no datagrams in the \s-1BIO\s0 to read will return a negative result and
the \*(L"retry\*(R" flags will be set (i.e. calling \fBBIO_should_retry\fR\|(3) will return
true). A datagram mem \s-1BIO\s0 will never return true from \fBBIO_eof\fR\|(3).
.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
.PP
Memory BIOs except \fBBIO_s_dgram_mem()\fR support \fBBIO_gets()\fR and \fBBIO_puts()\fR.
.PP
\&\fBBIO_s_dgram_mem()\fR supports \fBBIO_sendmmsg\fR\|(3) and \fBBIO_recvmmsg\fR\|(3) calls
and calls related to \fB\s-1BIO_ADDR\s0\fR and \s-1MTU\s0 handling similarly to the
\&\fBBIO_s_dgram_pair\fR\|(3).
.PP
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 \fBBIO_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, otherwise it just restores the read
pointer to the state it was just after the last write was performed and the
data can be read again. On a read only \s-1BIO\s0 it similarly restores the \s-1BIO\s0 to
its original state and the read only data can be read again.
.PP
\&\fBBIO_eof()\fR is true if no data is in the \s-1BIO.\s0
.PP
\&\fBBIO_ctrl_pending()\fR returns the number of bytes currently stored.
.PP
\&\fBBIO_set_mem_eof_return()\fR sets the behaviour of memory \s-1BIO\s0 \fBb\fR when it is
empty. If the \fBv\fR is zero then an empty memory \s-1BIO\s0 will return \s-1EOF\s0 (that is
it will return zero and BIO_should_retry(b) will be false. If \fBv\fR is non
zero then it will return \fBv\fR when it is empty and it will set the read retry
flag (that is BIO_read_retry(b) is true). To avoid ambiguity with a normal
positive return value \fBv\fR should be set to a negative value, typically \-1.
Calling this macro will fail for datagram mem BIOs.
.PP
\&\fBBIO_get_mem_data()\fR sets *\fBpp\fR to a pointer to the start of the memory BIOs data
and returns the total amount of data available. It is implemented as a macro.
Note the pointer returned by this call is informative, no transfer of ownership
of this memory is implied. See notes on \fBBIO_set_close()\fR.
.PP
\&\fBBIO_set_mem_buf()\fR sets the internal \s-1BUF_MEM\s0 structure to \fBbm\fR and sets the
close flag to \fBc\fR, that is \fBc\fR should be either \s-1BIO_CLOSE\s0 or \s-1BIO_NOCLOSE.\s0
It is a macro.
.PP
\&\fBBIO_get_mem_ptr()\fR places the underlying \s-1BUF_MEM\s0 structure in *\fBpp\fR. It is
a macro.
.PP
\&\fBBIO_new_mem_buf()\fR creates a memory \s-1BIO\s0 using \fBlen\fR bytes of data at \fBbuf\fR,
if \fBlen\fR is \-1 then the \fBbuf\fR is assumed to be nul terminated and its
length is determined by \fBstrlen\fR. The \s-1BIO\s0 is set to a read only state and
as a result cannot be written to. This is useful when some data needs to be
made available from a static area of memory in the form of a \s-1BIO.\s0 The
supplied data is read directly from the supplied buffer: it is \fBnot\fR copied
first, so the supplied area of memory must be unchanged until the \s-1BIO\s0 is freed.
.PP
All of the five functions described above return an error with
\&\fBBIO_s_dgram_mem()\fR.
.SH "NOTES"
.IX Header "NOTES"
Writes to memory BIOs will always succeed if memory is available: that is
their size can grow indefinitely. An exception is \fBBIO_s_dgram_mem()\fR when
\&\fBBIO_set_write_buf_size\fR\|(3) is called on it. In such case the write buffer
size will be fixed and any writes that would overflow the buffer will return
an error.
.PP
Every write after partial read (not all data in the memory buffer was read)
to a read write memory \s-1BIO\s0 will have to move the unread data with an internal
copy operation, if a \s-1BIO\s0 contains a lot of data and it is read in small
chunks intertwined with writes the operation can be very slow. Adding
a buffering \s-1BIO\s0 to the chain can speed up the process.
.PP
Calling \fBBIO_set_mem_buf()\fR on a secmem or dgram \s-1BIO\s0 will give undefined results,
including perhaps a program crash.
.PP
Switching a memory \s-1BIO\s0 from read write to read only is not supported and
can give undefined results including a program crash. There are two notable
exceptions to the rule. The first one is to assign a static memory buffer
immediately after \s-1BIO\s0 creation and set the \s-1BIO\s0 as read only.
.PP
The other supported sequence is to start with a read write \s-1BIO\s0 then temporarily
switch it to read only and call \fBBIO_reset()\fR on the read only \s-1BIO\s0 immediately
before switching it back to read write. Before the \s-1BIO\s0 is freed it must be
switched back to the read write mode.
.PP
Calling \fBBIO_get_mem_ptr()\fR on read only \s-1BIO\s0 will return a \s-1BUF_MEM\s0 that
contains only the remaining data to be read. If the close status of the
\&\s-1BIO\s0 is set to \s-1BIO_NOCLOSE,\s0 before freeing the \s-1BUF_MEM\s0 the data pointer
in it must be set to \s-1NULL\s0 as the data pointer does not point to an
allocated memory.
.PP
Calling \fBBIO_reset()\fR on a read write memory \s-1BIO\s0 with \s-1BIO_FLAGS_NONCLEAR_RST\s0
flag set can have unexpected outcome when the reads and writes to the
\&\s-1BIO\s0 are intertwined. As documented above the \s-1BIO\s0 will be reset to the
state after the last completed write operation. The effects of reads
preceding that write operation cannot be undone.
.PP
Calling \fBBIO_get_mem_ptr()\fR prior to a \fBBIO_reset()\fR call with
\&\s-1BIO_FLAGS_NONCLEAR_RST\s0 set has the same effect as a write operation.
.PP
Calling \fBBIO_set_close()\fR with \s-1BIO_NOCLOSE\s0 orphans the \s-1BUF_MEM\s0 internal to the
\&\s-1BIO,\s0 _not_ its actual data buffer. See the examples section for the proper
method for claiming ownership of the data pointer for a deferred free operation.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBBIO_s_mem()\fR, \fBBIO_s_dgram_mem()\fR and \fBBIO_s_secmem()\fR return a valid memory
\&\fB\s-1BIO_METHOD\s0\fR structure.
.PP
\&\fBBIO_set_mem_eof_return()\fR, \fBBIO_set_mem_buf()\fR and \fBBIO_get_mem_ptr()\fR
return 1 on success or a value which is less than or equal to 0 if an error occurred.
.PP
\&\fBBIO_get_mem_data()\fR returns the total number of bytes available on success,
0 if b is \s-1NULL,\s0 or a negative value in case of other errors.
.PP
\&\fBBIO_new_mem_buf()\fR returns a valid \fB\s-1BIO\s0\fR structure on success or \s-1NULL\s0 on error.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
Create a memory \s-1BIO\s0 and write some data to it:
.PP
.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 2
\& char data[] = "Hello World";
\& 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 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
.PP
Extract the \s-1BUF_MEM\s0 ptr, claim ownership of the internal data and free the \s-1BIO\s0
and \s-1BUF_MEM\s0 structure:
.PP
.Vb 2
\& BUF_MEM *bptr;
\& char *data;
\&
\& BIO_get_mem_data(bio, &data);
\& BIO_get_mem_ptr(bio, &bptr);
\& BIO_set_close(mem, BIO_NOCLOSE); /* So BIO_free orphans BUF_MEM */
\& BIO_free(bio);
\& bptr\->data = NULL; /* Tell BUF_MEM to orphan data */
\& BUF_MEM_free(bptr);
\& ...
\& free(data);
.Ve
.SH "HISTORY"
.IX Header "HISTORY"
\&\fBBIO_s_dgram_mem()\fR was added in OpenSSL 3.2.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

176
openssl-3.4.2/doc/man/man3/BIO_s_null.3
View File

@@ -1,176 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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_S_NULL 3ossl"
.TH BIO_S_NULL 3ossl "2025-07-01" "3.4.2" "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_null \- null data sink
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bio.h>
\&
\& const BIO_METHOD *BIO_s_null(void);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBBIO_s_null()\fR returns the null sink \s-1BIO\s0 method. Data written to
the null sink is discarded, reads return \s-1EOF.\s0
.SH "NOTES"
.IX Header "NOTES"
A null sink \s-1BIO\s0 behaves in a similar manner to the Unix /dev/null
device.
.PP
A null bio can be placed on the end of a chain to discard any data
passed through it.
.PP
A null sink is useful if, for example, an application wishes to digest some
data by writing through a digest bio but not send the digested data anywhere.
Since a \s-1BIO\s0 chain must normally include a source/sink \s-1BIO\s0 this can be achieved
by adding a null sink \s-1BIO\s0 to the end of the chain
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBBIO_s_null()\fR returns the null sink \s-1BIO\s0 method.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

186
openssl-3.4.2/doc/man/man3/BIO_s_socket.3
View File

@@ -1,186 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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_S_SOCKET 3ossl"
.TH BIO_S_SOCKET 3ossl "2025-07-01" "3.4.2" "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_socket, BIO_new_socket \- socket BIO
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bio.h>
\&
\& const BIO_METHOD *BIO_s_socket(void);
\&
\& BIO *BIO_new_socket(int sock, int close_flag);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBBIO_s_socket()\fR returns the socket \s-1BIO\s0 method. This is a wrapper
round the platform's socket routines.
.PP
\&\fBBIO_read_ex()\fR and \fBBIO_write_ex()\fR read or write the underlying socket.
\&\fBBIO_puts()\fR is supported but \fBBIO_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
\&\fBBIO_new_socket()\fR returns a socket \s-1BIO\s0 using \fBsock\fR and \fBclose_flag\fR.
.SH "NOTES"
.IX Header "NOTES"
Socket BIOs also support any relevant functionality of file descriptor
BIOs.
.PP
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.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBBIO_s_socket()\fR returns the socket \s-1BIO\s0 method.
.PP
\&\fBBIO_new_socket()\fR returns the newly allocated \s-1BIO\s0 or \s-1NULL\s0 is an error
occurred.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

350
openssl-3.4.2/doc/man/man3/BIO_sendmmsg.3
View File

@@ -1,350 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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_SENDMMSG 3ossl"
.TH BIO_SENDMMSG 3ossl "2025-07-01" "3.4.2" "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_sendmmsg, BIO_recvmmsg, BIO_dgram_set_local_addr_enable,
BIO_dgram_get_local_addr_enable, BIO_dgram_get_local_addr_cap,
BIO_err_is_non_fatal \- send and receive multiple datagrams in a single call
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bio.h>
\&
\& typedef struct bio_msg_st {
\& void *data;
\& size_t data_len;
\& BIO_ADDR *peer, *local;
\& uint64_t flags;
\& } BIO_MSG;
\&
\& int BIO_sendmmsg(BIO *b, BIO_MSG *msg,
\& size_t stride, size_t num_msg, uint64_t flags,
\& size_t *msgs_processed);
\& int BIO_recvmmsg(BIO *b, BIO_MSG *msg,
\& size_t stride, size_t num_msg, uint64_t flags,
\& size_t *msgs_processed);
\&
\& int BIO_dgram_set_local_addr_enable(BIO *b, int enable);
\& int BIO_dgram_get_local_addr_enable(BIO *b, int *enable);
\& int BIO_dgram_get_local_addr_cap(BIO *b);
\& int BIO_err_is_non_fatal(unsigned int errcode);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBBIO_sendmmsg()\fR and \fBBIO_recvmmsg()\fR functions can be used to send and receive
multiple messages in a single call to a \s-1BIO.\s0 They are analogous to \fBsendmmsg\fR\|(2)
and \fBrecvmmsg\fR\|(2) on operating systems which provide those functions.
.PP
The \fB\s-1BIO_MSG\s0\fR structure provides a subset of the functionality of the \fBstruct
msghdr\fR structure defined by \s-1POSIX.\s0 These functions accept an array of
\&\fB\s-1BIO_MSG\s0\fR structures. On any particular invocation, these functions may process
all of the passed structures, some of them, or none of them. This is indicated
by the value stored in \fI*msgs_processed\fR, which expresses the number of
messages processed.
.PP
The caller should set the \fIdata\fR member of a \fB\s-1BIO_MSG\s0\fR to a buffer containing
the data to send, or to be filled with a received message. \fIdata_len\fR should be
set to the size of the buffer in bytes. If the given \fB\s-1BIO_MSG\s0\fR is processed (in
other words, if the integer returned by the function is greater than or equal to
that \fB\s-1BIO_MSG\s0\fR's array index), \fIdata_len\fR will be modified to specify the
actual amount of data sent or received.
.PP
The \fIflags\fR field of a \fB\s-1BIO_MSG\s0\fR provides input per-message flags to the
invocation. If the invocation processes that \fB\s-1BIO_MSG\s0\fR, the \fIflags\fR field is
written with output per-message flags, or zero if no such flags are applicable.
.PP
Currently, no input or output per-message flags are defined and this field
should be set to zero before calling \fBBIO_sendmmsg()\fR or \fBBIO_recvmmsg()\fR.
.PP
The \fIflags\fR argument to \fBBIO_sendmmsg()\fR and \fBBIO_recvmmsg()\fR provides global
flags which affect the entire invocation. No global flags are currently
defined and this argument should be set to zero.
.PP
When these functions are used to send and receive datagrams, the \fIpeer\fR field
of a \fB\s-1BIO_MSG\s0\fR allows the destination address of sent datagrams to be specified
on a per-datagram basis, and the source address of received datagrams to be
determined. The \fIpeer\fR field should be set to point to a \fB\s-1BIO_ADDR\s0\fR, which
will be read by \fBBIO_sendmmsg()\fR and used as the destination address for sent
datagrams, and written by \fBBIO_recvmmsg()\fR with the source address of received
datagrams.
.PP
Similarly, the \fIlocal\fR field of a \fB\s-1BIO_MSG\s0\fR allows the source address of sent
datagrams to be specified on a per-datagram basis, and the destination address
of received datagrams to be determined. Unlike \fIpeer\fR, support for \fIlocal\fR
must be explicitly enabled on a \fB\s-1BIO\s0\fR before it can be used; see
\&\fBBIO_dgram_set_local_addr_enable()\fR. If \fIlocal\fR is non-NULL in a \fB\s-1BIO_MSG\s0\fR and
support for \fIlocal\fR has not been enabled, processing of that \fB\s-1BIO_MSG\s0\fR fails.
.PP
\&\fIpeer\fR and \fIlocal\fR should be set to \s-1NULL\s0 if they are not required. Support for
\&\fIlocal\fR may not be available on all platforms; on these platforms, these
functions always fail if \fIlocal\fR is non-NULL.
.PP
If \fIlocal\fR is specified and local address support is enabled, but the operating
system does not report a local address for a specific received message, the
\&\fB\s-1BIO_ADDR\s0\fR it points to will be cleared (address family set to \f(CW\*(C`AF_UNSPEC\*(C'\fR).
This is known to happen on Windows when a packet is received which was sent by
the local system, regardless of whether the packet's destination address was the
loopback address or the \s-1IP\s0 address of a local non-loopback interface. This is
also known to happen on macOS in some circumstances, such as for packets sent
before local address support was enabled for a receiving socket. These are
OS-specific limitations. As such, users of this \s-1API\s0 using local address support
should expect to sometimes receive a cleared local \fB\s-1BIO_ADDR\s0\fR instead of the
correct value.
.PP
The \fIstride\fR argument must be set to \f(CW\*(C`sizeof(BIO_MSG)\*(C'\fR. This argument
facilitates backwards compatibility if fields are added to \fB\s-1BIO_MSG\s0\fR. Callers
must zero-initialize \fB\s-1BIO_MSG\s0\fR.
.PP
\&\fInum_msg\fR should be sent to the maximum number of messages to send or receive,
which is also the length of the array pointed to by \fImsg\fR.
.PP
\&\fImsgs_processed\fR must be non-NULL and points to an integer written with the
number of messages successfully processed; see the \s-1RETURN VALUES\s0 section for
further discussion.
.PP
Unlike most \s-1BIO\s0 functions, these functions explicitly support multi-threaded
use. Multiple concurrent writers and multiple concurrent readers of the same \s-1BIO\s0
are permitted in any combination. As such, these functions do not clear, set, or
otherwise modify \s-1BIO\s0 retry flags. The return value must be used to determine
whether an operation should be retried; see below.
.PP
The support for concurrent use extends to \fBBIO_sendmmsg()\fR and \fBBIO_recvmmsg()\fR
only, and no other function may be called on a given \s-1BIO\s0 while any call to
\&\fBBIO_sendmmsg()\fR or \fBBIO_recvmmsg()\fR is in progress, or vice versa.
.PP
\&\fBBIO_dgram_set_local_addr_enable()\fR and \fBBIO_dgram_get_local_addr_enable()\fR control
whether local address support is enabled. To enable local address support, call
\&\fBBIO_dgram_set_local_addr_enable()\fR with an argument of 1. The call will fail if
local address support is not available for the platform.
\&\fBBIO_dgram_get_local_addr_enable()\fR retrieves the value set by
\&\fBBIO_dgram_set_local_addr_enable()\fR.
.PP
\&\fBBIO_dgram_get_local_addr_cap()\fR determines if the \fB\s-1BIO\s0\fR is capable of supporting
local addresses.
.PP
\&\fBBIO_err_is_non_fatal()\fR determines if a packed error code represents an error
which is transient in nature.
.SH "NOTES"
.IX Header "NOTES"
Some implementations of the \fBBIO_sendmmsg()\fR and \fBBIO_recvmmsg()\fR \s-1BIO\s0 methods might
always process at most one message at a time, for example when OS-level
functionality to transmit or receive multiple messages at a time is not
available.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
On success, the functions \fBBIO_sendmmsg()\fR and \fBBIO_recvmmsg()\fR return 1 and write
the number of messages successfully processed (which need not be nonzero) to
\&\fImsgs_processed\fR. Where a positive value n is written to \fImsgs_processed\fR, all
entries in the \fB\s-1BIO_MSG\s0\fR array from 0 through n\-1 inclusive have their
\&\fIdata_len\fR and \fIflags\fR fields updated with the results of the operation on
that message. If the call was to \fBBIO_recvmmsg()\fR and the \fIpeer\fR or \fIlocal\fR
fields of that message are non-NULL, the \fB\s-1BIO_ADDR\s0\fR structures they point to
are written with the relevant address.
.PP
On failure, the functions \fBBIO_sendmmsg()\fR and \fBBIO_recvmmsg()\fR return 0 and write
zero to \fImsgs_processed\fR. Thus \fImsgs_processed\fR is always written regardless
of the outcome of the function call.
.PP
If \fBBIO_sendmmsg()\fR and \fBBIO_recvmmsg()\fR fail, they always raise an \fB\s-1ERR_LIB_BIO\s0\fR
error using \fBERR_raise\fR\|(3). Any error may be raised, but the following in
particular may be noted:
.IP "\fB\s-1BIO_R_LOCAL_ADDR_NOT_AVAILABLE\s0\fR" 2
.IX Item "BIO_R_LOCAL_ADDR_NOT_AVAILABLE"
The \fIlocal\fR field was set to a non-NULL value, but local address support is not
available or not enabled on the \s-1BIO.\s0
.IP "\fB\s-1BIO_R_PEER_ADDR_NOT_AVAILABLE\s0\fR" 2
.IX Item "BIO_R_PEER_ADDR_NOT_AVAILABLE"
The \fIpeer\fR field was set to a non-NULL value, but peer address support is not
available on the \s-1BIO.\s0
.IP "\fB\s-1BIO_R_UNSUPPORTED_METHOD\s0\fR" 2
.IX Item "BIO_R_UNSUPPORTED_METHOD"
The \fBBIO_sendmmsg()\fR or \fBBIO_recvmmsg()\fR method is not supported on the \s-1BIO.\s0
.IP "\fB\s-1BIO_R_NON_FATAL\s0\fR" 2
.IX Item "BIO_R_NON_FATAL"
The call failed due to a transient, non-fatal error (for example, because the
\&\s-1BIO\s0 is in nonblocking mode and the call would otherwise have blocked).
.Sp
Implementations of this interface which do not make system calls and thereby
pass through system error codes using \fB\s-1ERR_LIB_SYS\s0\fR (for example, memory-based
implementations) should issue this reason code to indicate a transient failure.
However, users of this interface should not test for this reason code directly,
as there are multiple possible packed error codes representing a transient
failure; use \fBBIO_err_is_non_fatal()\fR instead (discussed below).
.IP "Socket errors" 2
.IX Item "Socket errors"
OS-level socket errors are reported using an error with library code
\&\fB\s-1ERR_LIB_SYS\s0\fR; for a packed error code \fBerrcode\fR where
\&\f(CW\*(C`ERR_SYSTEM_ERROR(errcode) == 1\*(C'\fR, the OS-level socket error code can be
retrieved using \f(CW\*(C`ERR_GET_REASON(errcode)\*(C'\fR. The packed error code can be
retrieved by calling \fBERR_peek_last_error\fR\|(3) after the call to \fBBIO_sendmmsg()\fR
or \fBBIO_recvmmsg()\fR returns 0.
.IP "Non-fatal errors" 2
.IX Item "Non-fatal errors"
Whether an error is transient can be determined by passing the packed error code
to \fBBIO_err_is_non_fatal()\fR. Callers should do this instead of testing the reason
code directly, as there are many possible error codes which can indicate a
transient error, many of which are system specific.
.PP
Third parties implementing custom BIOs supporting the \fBBIO_sendmmsg()\fR or
\&\fBBIO_recvmmsg()\fR methods should note that it is a required part of the \s-1API\s0
contract that an error is always raised when either of these functions return 0.
.PP
\&\fBBIO_dgram_set_local_addr_enable()\fR returns 1 if local address support was
successfully enabled or disabled and 0 otherwise.
.PP
\&\fBBIO_dgram_get_local_addr_enable()\fR returns 1 if the local address support enable
flag was successfully retrieved.
.PP
\&\fBBIO_dgram_get_local_addr_cap()\fR returns 1 if the \fB\s-1BIO\s0\fR can support local
addresses.
.PP
\&\fBBIO_err_is_non_fatal()\fR returns 1 if the passed packed error code represents an
error which is transient in nature.
.SH "HISTORY"
.IX Header "HISTORY"
These functions were added in OpenSSL 3.2.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

453
openssl-3.4.2/doc/man/man3/BIO_set_callback.3
View File

@@ -1,453 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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_SET_CALLBACK 3ossl"
.TH BIO_SET_CALLBACK 3ossl "2025-07-01" "3.4.2" "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_ex, BIO_get_callback_ex, BIO_set_callback, BIO_get_callback,
BIO_set_callback_arg, BIO_get_callback_arg, BIO_debug_callback,
BIO_debug_callback_ex, BIO_callback_fn_ex, BIO_callback_fn
\&\- BIO callback functions
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bio.h>
\&
\& typedef long (*BIO_callback_fn_ex)(BIO *b, int oper, const char *argp,
\& size_t len, int argi,
\& long argl, int ret, size_t *processed);
\&
\& void BIO_set_callback_ex(BIO *b, BIO_callback_fn_ex callback);
\& BIO_callback_fn_ex BIO_get_callback_ex(const BIO *b);
\&
\& void BIO_set_callback_arg(BIO *b, char *arg);
\& char *BIO_get_callback_arg(const BIO *b);
\&
\& long BIO_debug_callback_ex(BIO *bio, int oper, const char *argp, size_t len,
\& int argi, long argl, int ret, size_t *processed);
.Ve
.PP
The following functions have been deprecated since OpenSSL 3.0, and can be
hidden entirely by defining \fB\s-1OPENSSL_API_COMPAT\s0\fR with a suitable version value,
see \fBopenssl_user_macros\fR\|(7):
.PP
.Vb 6
\& typedef long (*BIO_callback_fn)(BIO *b, int oper, const char *argp, int argi,
\& long argl, long ret);
\& void BIO_set_callback(BIO *b, BIO_callback_fn cb);
\& BIO_callback_fn BIO_get_callback(const BIO *b);
\& long BIO_debug_callback(BIO *bio, int cmd, const char *argp, int argi,
\& long argl, long ret);
\&
\& typedef struct bio_mmsg_cb_args_st {
\& BIO_MSG *msg;
\& size_t stride, num_msg;
\& uint64_t flags;
\& size_t *msgs_processed;
\& } BIO_MMSG_CB_ARGS;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBBIO_set_callback_ex()\fR and \fBBIO_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
\&\fBBIO_set_callback()\fR and \fBBIO_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 \fBBIO_set_callback_ex()\fR will get
called in preference to any set by \fBBIO_set_callback()\fR.
.PP
\&\fBBIO_set_callback_arg()\fR and \fBBIO_get_callback_arg()\fR are macros which can be
used to set and retrieve an argument for use in the callback.
.PP
\&\fBBIO_debug_callback_ex()\fR is a standard debugging callback which prints
out information relating to each \s-1BIO\s0 operation. If the callback
argument is set it is interpreted as a \s-1BIO\s0 to send the information
to, otherwise stderr is used. The \fBBIO_debug_callback()\fR function is the
deprecated version of the same callback for use with the old callback
format \fBBIO_set_callback()\fR function.
.PP
BIO_callback_fn_ex is the type of the callback function and BIO_callback_fn
is the type of the old format callback function. The meaning of each argument
is described below:
.IP "\fBb\fR" 4
.IX Item "b"
The \s-1BIO\s0 the callback is attached to is passed in \fBb\fR.
.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
.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.
.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 \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 \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)"
.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, 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, 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, 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)"
.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.
.IP "\fBBIO_sendmmsg(\s-1BIO\s0 *b, \s-1BIO_MSG\s0 *msg, size_t stride, size_t num_msg, uint64_t flags, size_t *msgs_processed)\fR" 4
.IX Item "BIO_sendmmsg(BIO *b, BIO_MSG *msg, size_t stride, size_t num_msg, uint64_t flags, size_t *msgs_processed)"
.Vb 1
\& callback_ex(b, BIO_CB_SENDMMSG, args, 0, 0, 0, 1, NULL)
.Ve
.Sp
or
.Sp
.Vb 1
\& callback(b, BIO_CB_SENDMMSG, args, 0, 0, 1)
.Ve
.Sp
is called before the call and
.Sp
.Vb 1
\& callback_ex(b, BIO_CB_SENDMMSG | BIO_CB_RETURN, args, ret, 0, 0, ret, NULL)
.Ve
.Sp
or
.Sp
.Vb 1
\& callback(b, BIO_CB_SENDMMSG | BIO_CB_RETURN, args, ret, 0, 0, ret)
.Ve
.Sp
after.
.Sp
\&\fBargs\fR is a pointer to a \fB\s-1BIO_MMSG_CB_ARGS\s0\fR structure containing the arguments
passed to \fBBIO_sendmmsg()\fR. \fBret\fR is the return value of the \fBBIO_sendmmsg()\fR call.
The return value of \fBBIO_sendmmsg()\fR is altered to the value returned by the
\&\fB\s-1BIO_CB_SENDMMSG\s0 | \s-1BIO_CB_RETURN\s0\fR call.
.IP "\fBBIO_recvmmsg(\s-1BIO\s0 *b, \s-1BIO_MSG\s0 *msg, size_t stride, size_t num_msg, uint64_t flags, size_t *msgs_processed)\fR" 4
.IX Item "BIO_recvmmsg(BIO *b, BIO_MSG *msg, size_t stride, size_t num_msg, uint64_t flags, size_t *msgs_processed)"
See the documentation for \fBBIO_sendmmsg()\fR. \fBBIO_recvmmsg()\fR works identically
except that \fB\s-1BIO_CB_RECVMMSG\s0\fR is used instead of \fB\s-1BIO_CB_SENDMMSG\s0\fR.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBBIO_get_callback_ex()\fR and \fBBIO_get_callback()\fR return the callback function
previously set by a call to \fBBIO_set_callback_ex()\fR and \fBBIO_set_callback()\fR
respectively.
.PP
\&\fBBIO_get_callback_arg()\fR returns a \fBchar\fR pointer to the value previously set
via a call to \fBBIO_set_callback_arg()\fR.
.PP
\&\fBBIO_debug_callback()\fR returns 1 or \fBret\fR if it's called after specific \s-1BIO\s0
operations.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
The \fBBIO_debug_callback_ex()\fR function is an example, its source is
in crypto/bio/bio_cb.c
.SH "HISTORY"
.IX Header "HISTORY"
The \fBBIO_debug_callback_ex()\fR function was added in OpenSSL 3.0.
.PP
\&\fBBIO_set_callback()\fR, \fBBIO_get_callback()\fR, and \fBBIO_debug_callback()\fR were
deprecated in OpenSSL 3.0. Use the non-deprecated _ex functions instead.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2021 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

276
openssl-3.4.2/doc/man/man3/BIO_should_retry.3
View File

@@ -1,276 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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_SHOULD_RETRY 3ossl"
.TH BIO_SHOULD_RETRY 3ossl "2025-07-01" "3.4.2" "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_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>
\&
\& int BIO_should_read(BIO *b);
\& int BIO_should_write(BIO *b);
\& int BIO_should_io_special(iBIO *b);
\& int BIO_retry_type(BIO *b);
\& int BIO_should_retry(BIO *b);
\&
\& BIO *BIO_get_retry_BIO(BIO *bio, int *reason);
\& int BIO_get_retry_reason(BIO *bio);
\& void BIO_set_retry_reason(BIO *bio, int reason);
.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 \fBBIO_read_ex()\fR or \fBBIO_write_ex()\fR
call.
.PP
\&\fBBIO_should_retry()\fR is true if the call that produced this condition
should then be retried at a later time.
.PP
If \fBBIO_should_retry()\fR is false then the cause is an error condition.
.PP
\&\fBBIO_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
\&\fBBIO_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
\&\fBBIO_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.
.PP
\&\fBBIO_retry_type()\fR returns a mask of the cause of a retry condition
consisting of the values \fB\s-1BIO_FLAGS_READ\s0\fR, \fB\s-1BIO_FLAGS_WRITE\s0\fR,
\&\fB\s-1BIO_FLAGS_IO_SPECIAL\s0\fR though current \s-1BIO\s0 types will only set one of
these.
.PP
\&\fBBIO_get_retry_BIO()\fR determines the precise reason for the special
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
\&\fBBIO_get_retry_reason()\fR returns the reason for a special condition if
passed the relevant \s-1BIO,\s0 for example as returned by \fBBIO_get_retry_BIO()\fR.
.PP
\&\fBBIO_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"
\&\fBBIO_should_read()\fR, \fBBIO_should_write()\fR, \fBBIO_should_io_special()\fR,
\&\fBBIO_retry_type()\fR, and \fBBIO_should_retry()\fR, are implemented as macros.
.PP
If \fBBIO_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 \fBBIO_read_ex()\fR on a socket \s-1BIO\s0 returns
0 and \fBBIO_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
the error queue. For more details see the individual \s-1BIO\s0 type manual
pages.
.PP
If the underlying I/O structure is in a blocking mode almost all current
\&\s-1BIO\s0 types will not request a retry, because the underlying I/O
calls will not. If the application knows that the \s-1BIO\s0 type will never
signal a retry then it need not call \fBBIO_should_retry()\fR after a failed
\&\s-1BIO I/O\s0 call. This is typically done with file BIOs.
.PP
\&\s-1SSL\s0 BIOs are the only current exception to this rule: they can request a
retry even if the underlying I/O structure is blocking, if a handshake
occurs during a call to \fBBIO_read()\fR. An application can retry the failed
call immediately or avoid this situation by setting \s-1SSL_MODE_AUTO_RETRY\s0
on the underlying \s-1SSL\s0 structure.
.PP
While an application may retry a failed non blocking call immediately
this is likely to be very inefficient because the call will fail
repeatedly until data can be processed or is available. An application
will normally wait until the necessary condition is satisfied. How
this is done depends on the underlying I/O structure.
.PP
For example if the cause is ultimately a socket and \fBBIO_should_read()\fR
is true then a call to \fBselect()\fR may be made to wait until data is
available and then retry the \s-1BIO\s0 operation. By combining the retry
conditions of several non blocking BIOs in a single \fBselect()\fR call
it is possible to service several BIOs in a single thread, though
the performance may be poor if \s-1SSL\s0 BIOs are present because long delays
can occur during the initial handshake process.
.PP
It is possible for a \s-1BIO\s0 to block indefinitely if the underlying I/O
structure cannot process or return any data. This depends on the behaviour of
the platforms I/O functions. This is often not desirable: one solution
is to use non blocking I/O and use a timeout on the \fBselect()\fR (or
equivalent) call.
.SH "BUGS"
.IX Header "BUGS"
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"
\&\fBBIO_should_read()\fR, \fBBIO_should_write()\fR, \fBBIO_should_io_special()\fR, and
\&\fBBIO_should_retry()\fR return either 1 or 0 based on the actual conditions
of the \fB\s-1BIO\s0\fR.
.PP
\&\fBBIO_retry_type()\fR returns a flag combination presenting the cause of a retry
condition or false if there is no retry condition.
.PP
\&\fBBIO_get_retry_BIO()\fR returns a valid \fB\s-1BIO\s0\fR structure.
.PP
\&\fBBIO_get_retry_reason()\fR returns the reason for a special condition.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBbio\fR\|(7)
.SH "HISTORY"
.IX Header "HISTORY"
The \fBBIO_get_retry_reason()\fR and \fBBIO_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 Apache License 2.0 (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
openssl-3.4.2/doc/man/man3/BIO_socket_wait.3
View File

@@ -1,200 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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_SOCKET_WAIT 3ossl"
.TH BIO_SOCKET_WAIT 3ossl "2025-07-01" "3.4.2" "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_wait,
BIO_wait,
BIO_do_connect_retry
\&\- BIO connection utility functions
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bio.h>
\&
\& #ifndef OPENSSL_NO_SOCK
\& int BIO_socket_wait(int fd, int for_read, time_t max_time);
\& #endif
\& int BIO_wait(BIO *bio, time_t max_time, unsigned int nap_milliseconds);
\& int BIO_do_connect_retry(BIO *bio, int timeout, int nap_milliseconds);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBBIO_socket_wait()\fR waits on the socket \fBfd\fR for reading if \fBfor_read\fR is not 0,
else for writing, at most until \fBmax_time\fR.
It succeeds immediately if \fBmax_time\fR == 0 (which means no timeout given).
.PP
\&\fBBIO_wait()\fR waits at most until \fBmax_time\fR on the given (typically socket-based)
\&\fBbio\fR, for reading if \fBbio\fR is supposed to read, else for writing.
It is used by \fBBIO_do_connect_retry()\fR and can be used together \fBBIO_read\fR\|(3).
It succeeds immediately if \fBmax_time\fR == 0 (which means no timeout given).
If sockets are not available it supports polling by succeeding after sleeping
at most the given \fBnap_milliseconds\fR in order to avoid a tight busy loop.
Via \fBnap_milliseconds\fR the caller determines the polling granularity.
.PP
\&\fBBIO_do_connect_retry()\fR connects via the given \fBbio\fR.
It retries \fBBIO_do_connect()\fR as far as needed to reach a definite outcome,
i.e., connection succeeded, timeout has been reached, or an error occurred.
For nonblocking and potentially even non-socket BIOs it polls
every \fBnap_milliseconds\fR and sleeps in between using \fBBIO_wait()\fR.
If \fBnap_milliseconds\fR is < 0 then a default value of 100 ms is used.
If the \fBtimeout\fR parameter is > 0 this indicates the maximum number of seconds
to wait until the connection is established or a definite error occurred.
A value of 0 enables waiting indefinitely (i.e, no timeout),
while a value < 0 means that \fBBIO_do_connect()\fR is tried only once.
The function may, directly or indirectly, invoke \fBERR_clear_error()\fR.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBBIO_socket_wait()\fR, \fBBIO_wait()\fR, and \fBBIO_do_connect_retry()\fR
return \-1 on error, 0 on timeout, and 1 on success.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBBIO_do_connect\fR\|(3), \fBBIO_read\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fBBIO_socket_wait()\fR, \fBBIO_wait()\fR, and \fBBIO_do_connect_retry()\fR
were added in OpenSSL 3.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2019\-2020 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

258
openssl-3.4.2/doc/man/man3/BN_BLINDING_new.3
View File

@@ -1,258 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 "BN_BLINDING_NEW 3ossl"
.TH BN_BLINDING_NEW 3ossl "2025-07-01" "3.4.2" "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_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);
\& void BN_BLINDING_free(BN_BLINDING *b);
\& int BN_BLINDING_update(BN_BLINDING *b, BN_CTX *ctx);
\& int BN_BLINDING_convert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx);
\& int BN_BLINDING_invert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx);
\& int BN_BLINDING_convert_ex(BIGNUM *n, BIGNUM *r, BN_BLINDING *b,
\& BN_CTX *ctx);
\& int BN_BLINDING_invert_ex(BIGNUM *n, const BIGNUM *r, BN_BLINDING *b,
\& BN_CTX *ctx);
\& int BN_BLINDING_is_current_thread(BN_BLINDING *b);
\& void BN_BLINDING_set_current_thread(BN_BLINDING *b);
\& int BN_BLINDING_lock(BN_BLINDING *b);
\& int BN_BLINDING_unlock(BN_BLINDING *b);
\& unsigned long BN_BLINDING_get_flags(const BN_BLINDING *b);
\& void BN_BLINDING_set_flags(BN_BLINDING *b, unsigned long flags);
\& 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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBBN_BLINDING_new()\fR allocates a new \fB\s-1BN_BLINDING\s0\fR structure and copies
the \fBA\fR and \fBAi\fR values into the newly created \fB\s-1BN_BLINDING\s0\fR object.
.PP
\&\fBBN_BLINDING_free()\fR frees the \fB\s-1BN_BLINDING\s0\fR structure.
If \fBb\fR is \s-1NULL,\s0 nothing is done.
.PP
\&\fBBN_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
necessary parameters are set, by re-creating the blinding parameters.
.PP
\&\fBBN_BLINDING_convert_ex()\fR multiplies \fBn\fR with the blinding factor \fBA\fR.
If \fBr\fR is not \s-1NULL\s0 a copy the inverse blinding factor \fBAi\fR will be
returned in \fBr\fR (this is useful if a \fB\s-1RSA\s0\fR object is shared among
several threads). \fBBN_BLINDING_invert_ex()\fR multiplies \fBn\fR with the
inverse blinding factor \fBAi\fR. If \fBr\fR is not \s-1NULL\s0 it will be used as
the inverse blinding.
.PP
\&\fBBN_BLINDING_convert()\fR and \fBBN_BLINDING_invert()\fR are wrapper
functions for \fBBN_BLINDING_convert_ex()\fR and \fBBN_BLINDING_invert_ex()\fR
with \fBr\fR set to \s-1NULL.\s0
.PP
\&\fBBN_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
\&\fBBN_BLINDING_set_current_thread()\fR sets the current thread as the
owner of the \fB\s-1BN_BLINDING\s0\fR structure.
.PP
\&\fBBN_BLINDING_lock()\fR locks the \fB\s-1BN_BLINDING\s0\fR structure.
.PP
\&\fBBN_BLINDING_unlock()\fR unlocks the \fB\s-1BN_BLINDING\s0\fR structure.
.PP
\&\fBBN_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
\&\fB\s-1BN_BLINDING_NO_RECREATE\s0\fR. \fB\s-1BN_BLINDING_NO_UPDATE\s0\fR inhibits the
automatic update of the \fB\s-1BN_BLINDING\s0\fR parameters after each use
and \fB\s-1BN_BLINDING_NO_RECREATE\s0\fR inhibits the automatic re-creation
of the \fB\s-1BN_BLINDING\s0\fR parameters after a fixed number of uses (currently
32). In newly allocated \fB\s-1BN_BLINDING\s0\fR objects no flags are set.
\&\fBBN_BLINDING_set_flags()\fR sets the \fB\s-1BN_BLINDING\s0\fR parameters flags.
.PP
\&\fBBN_BLINDING_create_param()\fR creates new \fB\s-1BN_BLINDING\s0\fR parameters
using the exponent \fBe\fR and the modulus \fBm\fR. \fBbn_mod_exp\fR and
\&\fBm_ctx\fR can be used to pass special functions for exponentiation
(normally \fBBN_mod_exp_mont()\fR and \fB\s-1BN_MONT_CTX\s0\fR).
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBBN_BLINDING_new()\fR returns the newly allocated \fB\s-1BN_BLINDING\s0\fR structure
or \s-1NULL\s0 in case of an error.
.PP
\&\fBBN_BLINDING_update()\fR, \fBBN_BLINDING_convert()\fR, \fBBN_BLINDING_invert()\fR,
\&\fBBN_BLINDING_convert_ex()\fR and \fBBN_BLINDING_invert_ex()\fR return 1 on
success and 0 if an error occurred.
.PP
\&\fBBN_BLINDING_is_current_thread()\fR returns 1 if the current thread owns
the \fB\s-1BN_BLINDING\s0\fR object, 0 otherwise.
.PP
\&\fBBN_BLINDING_set_current_thread()\fR doesn't return anything.
.PP
\&\fBBN_BLINDING_lock()\fR, \fBBN_BLINDING_unlock()\fR return 1 if the operation
succeeded or 0 on error.
.PP
\&\fBBN_BLINDING_get_flags()\fR returns the currently set \fB\s-1BN_BLINDING\s0\fR flags
(a \fBunsigned long\fR value).
.PP
\&\fBBN_BLINDING_create_param()\fR returns the newly created \fB\s-1BN_BLINDING\s0\fR
parameters or \s-1NULL\s0 on error.
.SH "HISTORY"
.IX Header "HISTORY"
\&\fBBN_BLINDING_thread_id()\fR was first introduced in OpenSSL 1.0.0, and it
deprecates \fBBN_BLINDING_set_thread_id()\fR and \fBBN_BLINDING_get_thread_id()\fR.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2005\-2017 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

223
openssl-3.4.2/doc/man/man3/BN_CTX_new.3
View File

@@ -1,223 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 "BN_CTX_NEW 3ossl"
.TH BN_CTX_NEW 3ossl "2025-07-01" "3.4.2" "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_ex, BN_CTX_new, BN_CTX_secure_new_ex, BN_CTX_secure_new, BN_CTX_free
\&\- allocate and free BN_CTX structures
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bn.h>
\&
\& BN_CTX *BN_CTX_new_ex(OSSL_LIB_CTX *ctx);
\& BN_CTX *BN_CTX_new(void);
\&
\& BN_CTX *BN_CTX_secure_new_ex(OSSL_LIB_CTX *ctx);
\& BN_CTX *BN_CTX_secure_new(void);
\&
\& void BN_CTX_free(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
library functions. Since dynamic memory allocation to create \fB\s-1BIGNUM\s0\fRs
is rather expensive when used in conjunction with repeated subroutine
calls, the \fB\s-1BN_CTX\s0\fR structure is used.
.PP
\&\fBBN_CTX_new_ex()\fR allocates and initializes a \fB\s-1BN_CTX\s0\fR structure for the given
library context \fBctx\fR. The <ctx> value may be \s-1NULL\s0 in which case the default
library context will be used. \fBBN_CTX_new()\fR is the same as \fBBN_CTX_new_ex()\fR except
that the default library context is always used.
.PP
\&\fBBN_CTX_secure_new_ex()\fR allocates and initializes a \fB\s-1BN_CTX\s0\fR structure
but uses the secure heap (see \fBCRYPTO_secure_malloc\fR\|(3)) to hold the
\&\fB\s-1BIGNUM\s0\fRs for the given library context \fBctx\fR. The <ctx> value may be \s-1NULL\s0 in
which case the default library context will be used. \fBBN_CTX_secure_new()\fR is the
same as \fBBN_CTX_secure_new_ex()\fR except that the default library context is always
used.
.PP
\&\fBBN_CTX_free()\fR frees the components of the \fB\s-1BN_CTX\s0\fR and the structure itself.
Since \fBBN_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 \fBBN_CTX_end()\fR must be called before the \fB\s-1BN_CTX\s0\fR may
be freed by \fBBN_CTX_free()\fR. If \fBc\fR is \s-1NULL,\s0 nothing is done.
.PP
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"
\&\fBBN_CTX_new()\fR and \fBBN_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
\&\fBERR_get_error\fR\|(3).
.PP
\&\fBBN_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
\&\fBBN_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"
\&\fBERR_get_error\fR\|(3), \fBBN_add\fR\|(3),
\&\fBBN_CTX_start\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fBBN_CTX_init()\fR was removed in OpenSSL 1.1.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

189
openssl-3.4.2/doc/man/man3/BN_CTX_start.3
View File

@@ -1,189 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 "BN_CTX_START 3ossl"
.TH BN_CTX_START 3ossl "2025-07-01" "3.4.2" "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_start, BN_CTX_get, BN_CTX_end \- use temporary BIGNUM variables
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bn.h>
\&
\& void BN_CTX_start(BN_CTX *ctx);
\&
\& BIGNUM *BN_CTX_get(BN_CTX *ctx);
\&
\& void BN_CTX_end(BN_CTX *ctx);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
These functions are used to obtain temporary \fB\s-1BIGNUM\s0\fR variables from
a \fB\s-1BN_CTX\s0\fR (which can been created by using \fBBN_CTX_new\fR\|(3))
in order to save the overhead of repeatedly creating and
freeing \fB\s-1BIGNUM\s0\fRs in functions that are called from inside a loop.
.PP
A function must call \fBBN_CTX_start()\fR first. Then, \fBBN_CTX_get()\fR may be
called repeatedly to obtain temporary \fB\s-1BIGNUM\s0\fRs. All \fBBN_CTX_get()\fR
calls must be made before calling any other functions that use the
\&\fBctx\fR as an argument.
.PP
Finally, \fBBN_CTX_end()\fR must be called before returning from the function.
If \fBctx\fR is \s-1NULL,\s0 nothing is done.
When \fBBN_CTX_end()\fR is called, the \fB\s-1BIGNUM\s0\fR pointers obtained from
\&\fBBN_CTX_get()\fR become invalid.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBBN_CTX_start()\fR and \fBBN_CTX_end()\fR return no values.
.PP
\&\fBBN_CTX_get()\fR returns a pointer to the \fB\s-1BIGNUM\s0\fR, or \fB\s-1NULL\s0\fR on error.
Once \fBBN_CTX_get()\fR has failed, the subsequent calls will return \fB\s-1NULL\s0\fR
as well, so it is sufficient to check the return value of the last
\&\fBBN_CTX_get()\fR call. In case of an error, an error code is set, which
can be obtained by \fBERR_get_error\fR\|(3).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBBN_CTX_new\fR\|(3)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

276
openssl-3.4.2/doc/man/man3/BN_add.3
View File

@@ -1,276 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 "BN_ADD 3ossl"
.TH BN_ADD 3ossl "2025-07-01" "3.4.2" "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_mod_sqrt, BN_exp, BN_mod_exp, BN_gcd \-
arithmetic operations on BIGNUMs
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bn.h>
\&
\& int BN_add(BIGNUM *r, const BIGNUM *a, const BIGNUM *b);
\&
\& int BN_sub(BIGNUM *r, const BIGNUM *a, const BIGNUM *b);
\&
\& int BN_mul(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx);
\&
\& int BN_sqr(BIGNUM *r, const BIGNUM *a, BN_CTX *ctx);
\&
\& int BN_div(BIGNUM *dv, BIGNUM *rem, const BIGNUM *a, const BIGNUM *d,
\& BN_CTX *ctx);
\&
\& int BN_mod(BIGNUM *rem, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx);
\&
\& int BN_nnmod(BIGNUM *r, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx);
\&
\& int BN_mod_add(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, const BIGNUM *m,
\& BN_CTX *ctx);
\&
\& int BN_mod_sub(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, const BIGNUM *m,
\& BN_CTX *ctx);
\&
\& int BN_mod_mul(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, const BIGNUM *m,
\& BN_CTX *ctx);
\&
\& int BN_mod_sqr(BIGNUM *r, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx);
\&
\& BIGNUM *BN_mod_sqrt(BIGNUM *in, const BIGNUM *a, const BIGNUM *p, BN_CTX *ctx);
\&
\& int BN_exp(BIGNUM *r, const BIGNUM *a, const BIGNUM *p, BN_CTX *ctx);
\&
\& int BN_mod_exp(BIGNUM *r, const BIGNUM *a, const BIGNUM *p,
\& const BIGNUM *m, BN_CTX *ctx);
\&
\& int BN_gcd(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBBN_add()\fR adds \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.
.PP
\&\fBBN_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
\&\fBBN_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.
For multiplication by powers of 2, use \fBBN_lshift\fR\|(3).
.PP
\&\fBBN_sqr()\fR takes the square of \fIa\fR and places the result in \fIr\fR
(\f(CW\*(C`r=a^2\*(C'\fR). \fIr\fR and \fIa\fR may be the same \fB\s-1BIGNUM\s0\fR.
This function is faster than BN_mul(r,a,a).
.PP
\&\fBBN_div()\fR divides \fIa\fR by \fId\fR and places the result in \fIdv\fR and the
remainder in \fIrem\fR (\f(CW\*(C`dv=a/d, rem=a%d\*(C'\fR). Either of \fIdv\fR and \fIrem\fR may
be \fB\s-1NULL\s0\fR, in which case the respective value is not returned.
The result is rounded towards zero; thus if \fIa\fR is negative, the
remainder will be zero or negative.
For division by powers of 2, use \fBBN_rshift\fR\|(3).
.PP
\&\fBBN_mod()\fR corresponds to \fBBN_div()\fR with \fIdv\fR set to \fB\s-1NULL\s0\fR.
.PP
\&\fBBN_nnmod()\fR reduces \fIa\fR modulo \fIm\fR and places the nonnegative
remainder in \fIr\fR.
.PP
\&\fBBN_mod_add()\fR adds \fIa\fR to \fIb\fR modulo \fIm\fR and places the nonnegative
result in \fIr\fR.
.PP
\&\fBBN_mod_sub()\fR subtracts \fIb\fR from \fIa\fR modulo \fIm\fR and places the
nonnegative result in \fIr\fR.
.PP
\&\fBBN_mod_mul()\fR multiplies \fIa\fR by \fIb\fR and finds the nonnegative
remainder respective to modulus \fIm\fR (\f(CW\*(C`r=(a*b) mod m\*(C'\fR). \fIr\fR may be
the same \fB\s-1BIGNUM\s0\fR as \fIa\fR or \fIb\fR. For more efficient algorithms for
repeated computations using the same modulus, see
\&\fBBN_mod_mul_montgomery\fR\|(3) and
\&\fBBN_mod_mul_reciprocal\fR\|(3).
.PP
\&\fBBN_mod_sqr()\fR takes the square of \fIa\fR modulo \fBm\fR and places the
result in \fIr\fR.
.PP
\&\fBBN_mod_sqrt()\fR returns the modular square root of \fIa\fR such that
\&\f(CW\*(C`in^2 = a (mod p)\*(C'\fR. The modulus \fIp\fR must be a
prime, otherwise an error or an incorrect \*(L"result\*(R" will be returned.
The result is stored into \fIin\fR which can be \s-1NULL.\s0 The result will be
newly allocated in that case.
.PP
\&\fBBN_exp()\fR raises \fIa\fR to the \fIp\fR\-th power and places the result in \fIr\fR
(\f(CW\*(C`r=a^p\*(C'\fR). This function is faster than repeated applications of
\&\fBBN_mul()\fR.
.PP
\&\fBBN_mod_exp()\fR computes \fIa\fR to the \fIp\fR\-th power modulo \fIm\fR (\f(CW\*(C`r=a^p %
m\*(C'\fR). This function uses less time and space than \fBBN_exp()\fR. Do not call this
function when \fBm\fR is even and any of the parameters have the
\&\fB\s-1BN_FLG_CONSTTIME\s0\fR flag set.
.PP
\&\fBBN_gcd()\fR computes the greatest common divisor of \fIa\fR and \fIb\fR and
places the result in \fIr\fR. \fIr\fR may be the same \fB\s-1BIGNUM\s0\fR as \fIa\fR or
\&\fIb\fR.
.PP
For all functions, \fIctx\fR is a previously allocated \fB\s-1BN_CTX\s0\fR used for
temporary variables; see \fBBN_CTX_new\fR\|(3).
.PP
Unless noted otherwise, the result \fB\s-1BIGNUM\s0\fR must be different from
the arguments.
.SH "NOTES"
.IX Header "NOTES"
For modular operations such as \fBBN_nnmod()\fR or \fBBN_mod_exp()\fR it is an error
to use the same \fB\s-1BIGNUM\s0\fR object for the modulus as for the output.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
The \fBBN_mod_sqrt()\fR returns the result (possibly incorrect if \fIp\fR is
not a prime), or \s-1NULL.\s0
.PP
For all remaining functions, 1 is returned for success, 0 on error. The return
value should always be checked (e.g., \f(CW\*(C`if (!BN_add(r,a,b)) goto err;\*(C'\fR).
The error codes can be obtained by \fBERR_get_error\fR\|(3).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBERR_get_error\fR\|(3), \fBBN_CTX_new\fR\|(3),
\&\fBBN_add_word\fR\|(3), \fBBN_set_bit\fR\|(3)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2024 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

193
openssl-3.4.2/doc/man/man3/BN_add_word.3
View File

@@ -1,193 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 "BN_ADD_WORD 3ossl"
.TH BN_ADD_WORD 3ossl "2025-07-01" "3.4.2" "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
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bn.h>
\&
\& int BN_add_word(BIGNUM *a, BN_ULONG w);
\&
\& int BN_sub_word(BIGNUM *a, BN_ULONG w);
\&
\& int BN_mul_word(BIGNUM *a, BN_ULONG w);
\&
\& BN_ULONG BN_div_word(BIGNUM *a, BN_ULONG w);
\&
\& BN_ULONG BN_mod_word(const BIGNUM *a, BN_ULONG w);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
These functions perform arithmetic operations on BIGNUMs with unsigned
integers. They are much more efficient than the normal \s-1BIGNUM\s0
arithmetic operations.
.PP
\&\fBBN_add_word()\fR adds \fBw\fR to \fBa\fR (\f(CW\*(C`a+=w\*(C'\fR).
.PP
\&\fBBN_sub_word()\fR subtracts \fBw\fR from \fBa\fR (\f(CW\*(C`a\-=w\*(C'\fR).
.PP
\&\fBBN_mul_word()\fR multiplies \fBa\fR and \fBw\fR (\f(CW\*(C`a*=w\*(C'\fR).
.PP
\&\fBBN_div_word()\fR divides \fBa\fR by \fBw\fR (\f(CW\*(C`a/=w\*(C'\fR) and returns the remainder.
.PP
\&\fBBN_mod_word()\fR returns the remainder of \fBa\fR divided by \fBw\fR (\f(CW\*(C`a%w\*(C'\fR).
.PP
For \fBBN_div_word()\fR and \fBBN_mod_word()\fR, \fBw\fR must not be 0.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBBN_add_word()\fR, \fBBN_sub_word()\fR and \fBBN_mul_word()\fR return 1 for success, 0
on error. The error codes can be obtained by \fBERR_get_error\fR\|(3).
.PP
\&\fBBN_mod_word()\fR and \fBBN_div_word()\fR return \fBa\fR%\fBw\fR on success and
\&\fB(\s-1BN_ULONG\s0)\-1\fR if an error occurred.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBERR_get_error\fR\|(3), \fBBN_add\fR\|(3)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2017 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

281
openssl-3.4.2/doc/man/man3/BN_bn2bin.3
View File

@@ -1,281 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 "BN_BN2BIN 3ossl"
.TH BN_BN2BIN 3ossl "2025-07-01" "3.4.2" "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_bn2binpad, BN_signed_bn2bin, BN_bn2bin, BN_bin2bn, BN_signed_bin2bn,
BN_bn2lebinpad, BN_signed_bn2lebin, BN_lebin2bn, BN_signed_lebin2bn,
BN_bn2nativepad, BN_signed_bn2native, BN_native2bn, BN_signed_native2bn,
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);
\& int BN_signed_bn2bin(const BIGNUM *a, unsigned char *to, int tolen);
\& BIGNUM *BN_bin2bn(const unsigned char *s, int len, BIGNUM *ret);
\& BIGNUM *BN_signed_bin2bn(const unsigned char *s, int len, BIGNUM *ret);
\&
\& int BN_bn2lebinpad(const BIGNUM *a, unsigned char *to, int tolen);
\& int BN_signed_bn2lebin(const BIGNUM *a, unsigned char *to, int tolen);
\& BIGNUM *BN_lebin2bn(const unsigned char *s, int len, BIGNUM *ret);
\& BIGNUM *BN_signed_lebin2bn(const unsigned char *s, int len, BIGNUM *ret);
\&
\& int BN_bn2nativepad(const BIGNUM *a, unsigned char *to, int tolen);
\& int BN_signed_bn2native(const BIGNUM *a, unsigned char *to, int tolen);
\& BIGNUM *BN_native2bn(const unsigned char *s, int len, BIGNUM *ret);
\& BIGNUM *BN_signed_native2bn(const unsigned char *s, int len, BIGNUM *ret);
\&
\& char *BN_bn2hex(const BIGNUM *a);
\& char *BN_bn2dec(const BIGNUM *a);
\& int BN_hex2bn(BIGNUM **a, const char *str);
\& int BN_dec2bn(BIGNUM **a, const char *str);
\&
\& int BN_print(BIO *fp, const BIGNUM *a);
\& int BN_print_fp(FILE *fp, const BIGNUM *a);
\&
\& int BN_bn2mpi(const BIGNUM *a, unsigned char *to);
\& BIGNUM *BN_mpi2bn(unsigned char *s, int len, BIGNUM *ret);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBBN_bn2bin()\fR converts the absolute value of \fBa\fR into big-endian form
and stores it at \fBto\fR. \fBto\fR must point to BN_num_bytes(\fBa\fR) bytes of
memory.
.PP
\&\fBBN_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 zeros if necessary. If \fBtolen\fR is less than
BN_num_bytes(\fBa\fR) an error is returned.
.PP
\&\fBBN_signed_bn2bin()\fR converts the value of \fBa\fR into big-endian signed 2's
complements form and stores it at \fBto\fR. \fBtolen\fR indicates the length of
the output buffer \fBto\fR. The result is signed extended (padded with 0x00
for positive numbers or with 0xff for negative numbers) if necessary.
If \fBtolen\fR is smaller than the necessary size (which may be
\&\f(CW\*(C`<BN_num_bytes(\f(CBa\f(CW) + 1\*(C'\fR>), an error is returned.
.PP
\&\fBBN_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
\&\fBBN_signed_bin2bn()\fR converts the integer in big-endian signed 2's complement
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
\&\fBBN_bn2lebinpad()\fR, \fBBN_signed_bn2lebin()\fR and \fBBN_lebin2bn()\fR are identical to
\&\fBBN_bn2binpad()\fR, \fBBN_signed_bn2bin()\fR and \fBBN_bin2bn()\fR except the buffer is in
little-endian format.
.PP
\&\fBBN_bn2nativepad()\fR, \fBBN_signed_bn2native()\fR and \fBBN_native2bn()\fR are identical
to \fBBN_bn2binpad()\fR, \fBBN_signed_bn2bin()\fR and \fBBN_bin2bn()\fR except the buffer is
in native format, i.e. most significant byte first on big-endian platforms,
and least significant byte first on little-endian platforms.
.PP
\&\fBBN_bn2hex()\fR and \fBBN_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 \fBOPENSSL_free()\fR.
.PP
\&\fBBN_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.
\&\fBBN_dec2bn()\fR is the same using the decimal system.
.PP
\&\fBBN_print()\fR and \fBBN_print_fp()\fR write the hexadecimal encoding of \fBa\fR,
with a leading '\-' for negative numbers, to the \fB\s-1BIO\s0\fR or \fB\s-1FILE\s0\fR
\&\fBfp\fR.
.PP
\&\fBBN_bn2mpi()\fR and \fBBN_mpi2bn()\fR convert \fB\s-1BIGNUM\s0\fRs from and to a format
that consists of the number's length in bytes represented as a 4\-byte
big-endian number, and the number itself in big-endian format, where
the most significant bit signals a negative number (the representation
of numbers with the \s-1MSB\s0 set is prefixed with null byte).
.PP
\&\fBBN_bn2mpi()\fR stores the representation of \fBa\fR at \fBto\fR, where \fBto\fR
must be large enough to hold the result. The size can be determined by
calling BN_bn2mpi(\fBa\fR, \s-1NULL\s0).
.PP
\&\fBBN_mpi2bn()\fR converts the \fBlen\fR bytes long representation at \fBs\fR to
a \fB\s-1BIGNUM\s0\fR and stores it at \fBret\fR, or in a newly allocated \fB\s-1BIGNUM\s0\fR
if \fBret\fR is \s-1NULL.\s0
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBBN_bn2bin()\fR returns the length of the big-endian number placed at \fBto\fR.
\&\fBBN_bin2bn()\fR returns the \fB\s-1BIGNUM\s0\fR, \s-1NULL\s0 on error.
.PP
\&\fBBN_bn2binpad()\fR, \fBBN_signed_bn2bin()\fR, \fBBN_bn2lebinpad()\fR, \fBBN_signed_bn2lebin()\fR,
\&\fBBN_bn2nativepad()\fR, and_signed \fBBN_bn2native()\fR return the number of bytes
written or \-1 if the supplied buffer is too small.
.PP
\&\fBBN_bn2hex()\fR and \fBBN_bn2dec()\fR return a NUL-terminated string, or \s-1NULL\s0
on error. \fBBN_hex2bn()\fR and \fBBN_dec2bn()\fR return the number of characters
used in parsing, or 0 on error, in which
case no new \fB\s-1BIGNUM\s0\fR will be created.
.PP
\&\fBBN_print_fp()\fR and \fBBN_print()\fR return 1 on success, 0 on write errors.
.PP
\&\fBBN_bn2mpi()\fR returns the length of the representation. \fBBN_mpi2bn()\fR
returns the \fB\s-1BIGNUM\s0\fR, and \s-1NULL\s0 on error.
.PP
The error codes can be obtained by \fBERR_get_error\fR\|(3).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBERR_get_error\fR\|(3), \fBBN_zero\fR\|(3),
\&\fBASN1_INTEGER_to_BN\fR\|(3),
\&\fBBN_num_bytes\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
The functions \fBBN_signed_bin2bn()\fR, \fBBN_signed_bn2bin()\fR, \fBBN_signed_lebin2bn()\fR,
\&\fBBN_signed_bn2lebin()\fR, \fBBN_signed_native2bn()\fR, \fBBN_signed_bn2native()\fR
were added in OpenSSL 3.2.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2024 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

196
openssl-3.4.2/doc/man/man3/BN_cmp.3
View File

@@ -1,196 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 "BN_CMP 3ossl"
.TH BN_CMP 3ossl "2025-07-01" "3.4.2" "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_cmp, BN_ucmp, BN_is_zero, BN_is_one, BN_is_word, BN_abs_is_word, BN_is_odd, BN_are_coprime
\&\- BIGNUM comparison and test functions
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bn.h>
\&
\& int BN_cmp(const BIGNUM *a, const BIGNUM *b);
\& int BN_ucmp(const BIGNUM *a, const BIGNUM *b);
\&
\& int BN_is_zero(const BIGNUM *a);
\& int BN_is_one(const BIGNUM *a);
\& int BN_is_word(const BIGNUM *a, const BN_ULONG w);
\& int BN_abs_is_word(const BIGNUM *a, const BN_ULONG w);
\& int BN_is_odd(const BIGNUM *a);
\&
\& int BN_are_coprime(BIGNUM *a, const BIGNUM *b, BN_CTX *ctx);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBBN_cmp()\fR compares the numbers \fIa\fR and \fIb\fR. \fBBN_ucmp()\fR compares their
absolute values.
.PP
\&\fBBN_is_zero()\fR, \fBBN_is_one()\fR, \fBBN_is_word()\fR and \fBBN_abs_is_word()\fR test if
\&\fIa\fR equals 0, 1, \fIw\fR, or |\fIw\fR| respectively.
\&\fBBN_is_odd()\fR tests if \fIa\fR is odd.
.PP
\&\fBBN_are_coprime()\fR determines if \fBa\fR and \fBb\fR are coprime.
\&\fBctx\fR is used internally for storing temporary variables.
The values of \fBa\fR and \fBb\fR and \fBctx\fR must not be \s-1NULL.\s0
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBBN_cmp()\fR returns \-1 if \fIa\fR < \fIb\fR, 0 if \fIa\fR == \fIb\fR and 1 if
\&\fIa\fR > \fIb\fR. \fBBN_ucmp()\fR is the same using the absolute values
of \fIa\fR and \fIb\fR.
.PP
\&\fBBN_is_zero()\fR, \fBBN_is_one()\fR \fBBN_is_word()\fR, \fBBN_abs_is_word()\fR and
\&\fBBN_is_odd()\fR return 1 if the condition is true, 0 otherwise.
.PP
\&\fBBN_are_coprime()\fR returns 1 if the \fB\s-1BIGNUM\s0\fR's are coprime, otherwise it
returns 0.
.SH "HISTORY"
.IX Header "HISTORY"
Prior to OpenSSL 1.1.0, \fBBN_is_zero()\fR, \fBBN_is_one()\fR, \fBBN_is_word()\fR,
\&\fBBN_abs_is_word()\fR and \fBBN_is_odd()\fR were macros.
.PP
The function \fBBN_are_coprime()\fR was added in OpenSSL 3.1.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2021 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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
openssl-3.4.2/doc/man/man3/BN_copy.3
View File

@@ -1,191 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 "BN_COPY 3ossl"
.TH BN_COPY 3ossl "2025-07-01" "3.4.2" "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, BN_with_flags \- copy BIGNUMs
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bn.h>
\&
\& BIGNUM *BN_copy(BIGNUM *to, const BIGNUM *from);
\&
\& BIGNUM *BN_dup(const BIGNUM *from);
\&
\& void BN_with_flags(BIGNUM *dest, const BIGNUM *b, int flags);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBBN_copy()\fR copies \fBfrom\fR to \fBto\fR. \fBBN_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 \fBBN_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"
\&\fBBN_copy()\fR returns \fBto\fR on success, \s-1NULL\s0 on error. \fBBN_dup()\fR returns
the new \fB\s-1BIGNUM\s0\fR, and \s-1NULL\s0 on error. The error codes can be obtained
by \fBERR_get_error\fR\|(3).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBERR_get_error\fR\|(3)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2017 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

382
openssl-3.4.2/doc/man/man3/BN_generate_prime.3
View File

@@ -1,382 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 "BN_GENERATE_PRIME 3ossl"
.TH BN_GENERATE_PRIME 3ossl "2025-07-01" "3.4.2" "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_ex2, BN_generate_prime_ex, BN_is_prime_ex, BN_check_prime,
BN_is_prime_fasttest_ex, BN_GENCB_call, BN_GENCB_new, BN_GENCB_free,
BN_GENCB_set_old, BN_GENCB_set, BN_GENCB_get_arg, BN_generate_prime,
BN_is_prime, BN_is_prime_fasttest \- generate primes and test for primality
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bn.h>
\&
\& int BN_generate_prime_ex2(BIGNUM *ret, int bits, int safe,
\& const BIGNUM *add, const BIGNUM *rem, BN_GENCB *cb,
\& BN_CTX *ctx);
\&
\& int BN_generate_prime_ex(BIGNUM *ret, int bits, int safe, const BIGNUM *add,
\& const BIGNUM *rem, BN_GENCB *cb);
\&
\& int BN_check_prime(const BIGNUM *p, BN_CTX *ctx, BN_GENCB *cb);
\&
\& int BN_GENCB_call(BN_GENCB *cb, int a, int b);
\&
\& BN_GENCB *BN_GENCB_new(void);
\&
\& void BN_GENCB_free(BN_GENCB *cb);
\&
\& void BN_GENCB_set_old(BN_GENCB *gencb,
\& void (*callback)(int, int, void *), void *cb_arg);
\&
\& void BN_GENCB_set(BN_GENCB *gencb,
\& int (*callback)(int, int, BN_GENCB *), void *cb_arg);
\&
\& void *BN_GENCB_get_arg(BN_GENCB *cb);
.Ve
.PP
The following functions have been deprecated since OpenSSL 0.9.8, and can be
hidden entirely by defining \fB\s-1OPENSSL_API_COMPAT\s0\fR with a suitable version value,
see \fBopenssl_user_macros\fR\|(7):
.PP
.Vb 3
\& BIGNUM *BN_generate_prime(BIGNUM *ret, int num, int safe, BIGNUM *add,
\& BIGNUM *rem, void (*callback)(int, int, void *),
\& void *cb_arg);
\&
\& int BN_is_prime(const BIGNUM *p, int nchecks,
\& void (*callback)(int, int, void *), BN_CTX *ctx, void *cb_arg);
\&
\& int BN_is_prime_fasttest(const BIGNUM *p, int nchecks,
\& void (*callback)(int, int, void *), BN_CTX *ctx,
\& void *cb_arg, int do_trial_division);
.Ve
.PP
The following functions have been deprecated since OpenSSL 3.0, and can be
hidden entirely by defining \fB\s-1OPENSSL_API_COMPAT\s0\fR with a suitable version value,
see \fBopenssl_user_macros\fR\|(7):
.PP
.Vb 1
\& 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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBBN_generate_prime_ex2()\fR generates a pseudo-random prime number of
at least bit length \fBbits\fR using the \s-1BN_CTX\s0 provided in \fBctx\fR. The value of
\&\fBctx\fR must not be \s-1NULL.\s0
.PP
The returned number is probably prime with a negligible error.
The maximum error rate is 2^\-128.
It's 2^\-287 for a 512 bit prime, 2^\-435 for a 1024 bit prime,
2^\-648 for a 2048 bit prime, and lower than 2^\-882 for primes larger
than 2048 bit.
.PP
If \fBadd\fR is \fB\s-1NULL\s0\fR the returned prime number will have exact bit
length \fBbits\fR with the top most two bits set.
.PP
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" 2
\&\fBBN_GENCB_call(cb, 0, i)\fR is called after generating the i\-th
potential prime number.
.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" 2
When a prime has been found, \fBBN_GENCB_call(cb, 2, i)\fR is called.
.IP "\(bu" 2
The callers of \fBBN_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:
.PP
If \fBadd\fR is not \fB\s-1NULL\s0\fR, the prime will fulfill the condition p % \fBadd\fR
== \fBrem\fR (p % \fBadd\fR == 1 if \fBrem\fR == \fB\s-1NULL\s0\fR) in order to suit a given
generator.
.PP
If \fBsafe\fR is true, it will be a safe prime (i.e. a prime p so
that (p\-1)/2 is also prime). If \fBsafe\fR is true, and \fBrem\fR == \fB\s-1NULL\s0\fR
the condition will be p % \fBadd\fR == 3.
It is recommended that \fBadd\fR is a multiple of 4.
.PP
The random generator must be seeded prior to calling \fBBN_generate_prime_ex()\fR.
If the automatic seeding or reseeding of the OpenSSL \s-1CSPRNG\s0 fails due to
external circumstances (see \s-1\fBRAND\s0\fR\|(7)), the operation will fail.
The random number generator configured for the \s-1OSSL_LIB_CTX\s0 associated with
\&\fBctx\fR will be used.
.PP
\&\fBBN_generate_prime_ex()\fR is the same as \fBBN_generate_prime_ex2()\fR except that no
\&\fBctx\fR parameter is passed.
In this case the random number generator associated with the default \s-1OSSL_LIB_CTX\s0
will be used.
.PP
\&\fBBN_check_prime()\fR, \fBBN_is_prime_ex()\fR, \fBBN_is_prime_fasttest_ex()\fR, \fBBN_is_prime()\fR
and \fBBN_is_prime_fasttest()\fR test if the number \fBp\fR is prime.
The functions tests until one of the tests shows that \fBp\fR is composite,
or all the tests passed.
If \fBp\fR passes all these tests, it is considered a probable prime.
.PP
The test performed on \fBp\fR are trial division by a number of small primes
and rounds of the of the Miller-Rabin probabilistic primality test.
.PP
The functions do at least 64 rounds of the Miller-Rabin test giving a maximum
false positive rate of 2^\-128.
If the size of \fBp\fR is more than 2048 bits, they do at least 128 rounds
giving a maximum false positive rate of 2^\-256.
.PP
If \fBnchecks\fR is larger than the minimum above (64 or 128), \fBnchecks\fR
rounds of the Miller-Rabin test will be done.
.PP
If \fBdo_trial_division\fR set to \fB0\fR, the trial division will be skipped.
\&\fBBN_is_prime_ex()\fR and \fBBN_is_prime()\fR always skip the trial division.
.PP
\&\fBBN_is_prime_ex()\fR, \fBBN_is_prime_fasttest_ex()\fR, \fBBN_is_prime()\fR
and \fBBN_is_prime_fasttest()\fR are deprecated.
.PP
\&\fBBN_is_prime_fasttest()\fR and \fBBN_is_prime()\fR behave just like
\&\fBBN_is_prime_fasttest_ex()\fR and \fBBN_is_prime_ex()\fR respectively, but with the old
style call back.
.PP
\&\fBctx\fR is a preallocated \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
If the trial division is done, and no divisors are found and \fBcb\fR
is not \fB\s-1NULL\s0\fR, \fBBN_GENCB_call(cb, 1, \-1)\fR is called.
.PP
After each round of the Miller-Rabin probabilistic primality test,
if \fBcb\fR is not \fB\s-1NULL\s0\fR, \fBBN_GENCB_call(cb, 1, j)\fR is called
with \fBj\fR the iteration (j = 0, 1, ...).
.PP
\&\fBBN_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 \fBBN_GENCB_new()\fR,
and freed through a call to \fBBN_GENCB_free()\fR. If the argument is \s-1NULL,\s0
nothing is done.
.PP
For \*(L"new\*(R" style callbacks a \s-1BN_GENCB\s0 structure should be initialised with a
call to \fBBN_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 \fBBN_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
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
\&\fBBN_generate_prime()\fR (deprecated) works in the same way as
\&\fBBN_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. \fBBN_is_prime()\fR and \fBBN_is_prime_fasttest()\fR
can similarly be compared to \fBBN_is_prime_ex()\fR and
\&\fBBN_is_prime_fasttest_ex()\fR, respectively.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBBN_generate_prime_ex()\fR return 1 on success or 0 on error.
.PP
\&\fBBN_is_prime_ex()\fR, \fBBN_is_prime_fasttest_ex()\fR, \fBBN_is_prime()\fR,
\&\fBBN_is_prime_fasttest()\fR and BN_check_prime return 0 if the number is composite,
1 if it is prime with an error probability of less than 0.25^\fBnchecks\fR, and
\&\-1 on error.
.PP
\&\fBBN_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 \fBERR_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"
\&\fBDH_generate_parameters\fR\|(3), \fBDSA_generate_parameters\fR\|(3),
\&\fBRSA_generate_key\fR\|(3), \fBERR_get_error\fR\|(3), \fBRAND_bytes\fR\|(3),
\&\s-1\fBRAND\s0\fR\|(7)
.SH "HISTORY"
.IX Header "HISTORY"
The \fBBN_is_prime_ex()\fR and \fBBN_is_prime_fasttest_ex()\fR functions were
deprecated in OpenSSL 3.0.
.PP
The \fBBN_GENCB_new()\fR, \fBBN_GENCB_free()\fR,
and \fBBN_GENCB_get_arg()\fR functions were added in OpenSSL 1.1.0.
.PP
\&\fBBN_check_prime()\fR was added in OpenSSL 3.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2024 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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
openssl-3.4.2/doc/man/man3/BN_mod_exp_mont.3
View File

@@ -1,197 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 "BN_MOD_EXP_MONT 3ossl"
.TH BN_MOD_EXP_MONT 3ossl "2025-07-01" "3.4.2" "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_exp_mont, BN_mod_exp_mont_consttime, BN_mod_exp_mont_consttime_x2 \-
Montgomery exponentiation
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bn.h>
\&
\& int BN_mod_exp_mont(BIGNUM *rr, const BIGNUM *a, const BIGNUM *p,
\& const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *in_mont);
\&
\& int BN_mod_exp_mont_consttime(BIGNUM *rr, const BIGNUM *a, const BIGNUM *p,
\& const BIGNUM *m, BN_CTX *ctx,
\& BN_MONT_CTX *in_mont);
\&
\& int BN_mod_exp_mont_consttime_x2(BIGNUM *rr1, const BIGNUM *a1,
\& const BIGNUM *p1, const BIGNUM *m1,
\& BN_MONT_CTX *in_mont1, BIGNUM *rr2,
\& const BIGNUM *a2, const BIGNUM *p2,
\& const BIGNUM *m2, BN_MONT_CTX *in_mont2,
\& BN_CTX *ctx);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBBN_mod_exp_mont()\fR computes \fIa\fR to the \fIp\fR\-th power modulo \fIm\fR (\f(CW\*(C`rr=a^p % m\*(C'\fR)
using Montgomery multiplication. \fIin_mont\fR is a Montgomery context and can be
\&\s-1NULL.\s0 In the case \fIin_mont\fR is \s-1NULL,\s0 it will be initialized within the
function, so you can save time on initialization if you provide it in advance.
.PP
\&\fBBN_mod_exp_mont_consttime()\fR computes \fIa\fR to the \fIp\fR\-th power modulo \fIm\fR
(\f(CW\*(C`rr=a^p % m\*(C'\fR) using Montgomery multiplication. It is a variant of
\&\fBBN_mod_exp_mont\fR\|(3) that uses fixed windows and the special precomputation
memory layout to limit data-dependency to a minimum to protect secret exponents.
It is called automatically when \fBBN_mod_exp_mont\fR\|(3) is called with parameters
\&\fIa\fR, \fIp\fR, \fIm\fR, any of which have \fB\s-1BN_FLG_CONSTTIME\s0\fR flag.
.PP
\&\fBBN_mod_exp_mont_consttime_x2()\fR computes two independent exponentiations \fIa1\fR to
the \fIp1\fR\-th power modulo \fIm1\fR (\f(CW\*(C`rr1=a1^p1 % m1\*(C'\fR) and \fIa2\fR to the \fIp2\fR\-th
power modulo \fIm2\fR (\f(CW\*(C`rr2=a2^p2 % m2\*(C'\fR) using Montgomery multiplication. For some
fixed and equal modulus sizes \fIm1\fR and \fIm2\fR it uses optimizations that allow
to speedup two exponentiations. In all other cases the function reduces to two
calls of \fBBN_mod_exp_mont_consttime\fR\|(3).
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
For all functions 1 is returned for success, 0 on error.
The error codes can be obtained by \fBERR_get_error\fR\|(3).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBERR_get_error\fR\|(3), \fBBN_mod_exp_mont\fR\|(3)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2021 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

176
openssl-3.4.2/doc/man/man3/BN_mod_inverse.3
View File

@@ -1,176 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 "BN_MOD_INVERSE 3ossl"
.TH BN_MOD_INVERSE 3ossl "2025-07-01" "3.4.2" "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_inverse \- compute inverse modulo n
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bn.h>
\&
\& BIGNUM *BN_mod_inverse(BIGNUM *r, BIGNUM *a, const BIGNUM *n,
\& BN_CTX *ctx);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBBN_mod_inverse()\fR computes the inverse of \fBa\fR modulo \fBn\fR
places the result in \fBr\fR (\f(CW\*(C`(a*r)%n==1\*(C'\fR). If \fBr\fR is \s-1NULL,\s0
a new \fB\s-1BIGNUM\s0\fR is created.
.PP
\&\fBctx\fR is a previously allocated \fB\s-1BN_CTX\s0\fR used for temporary
variables. \fBr\fR may be the same \fB\s-1BIGNUM\s0\fR as \fBa\fR.
.SH "NOTES"
.IX Header "NOTES"
It is an error to use the same \fB\s-1BIGNUM\s0\fR as \fBn\fR.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBBN_mod_inverse()\fR returns the \fB\s-1BIGNUM\s0\fR containing the inverse, and
\&\s-1NULL\s0 on error. The error codes can be obtained by \fBERR_get_error\fR\|(3).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBERR_get_error\fR\|(3), \fBBN_add\fR\|(3)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2017 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

220
openssl-3.4.2/doc/man/man3/BN_mod_mul_montgomery.3
View File

@@ -1,220 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 "BN_MOD_MUL_MONTGOMERY 3ossl"
.TH BN_MOD_MUL_MONTGOMERY 3ossl "2025-07-01" "3.4.2" "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_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_free(BN_MONT_CTX *mont);
\&
\& int BN_MONT_CTX_set(BN_MONT_CTX *mont, const BIGNUM *m, BN_CTX *ctx);
\& BN_MONT_CTX *BN_MONT_CTX_copy(BN_MONT_CTX *to, BN_MONT_CTX *from);
\&
\& int BN_mod_mul_montgomery(BIGNUM *r, BIGNUM *a, BIGNUM *b,
\& BN_MONT_CTX *mont, BN_CTX *ctx);
\&
\& int BN_from_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont,
\& BN_CTX *ctx);
\&
\& int BN_to_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont,
\& BN_CTX *ctx);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
These functions implement Montgomery multiplication. They are used
automatically when \fBBN_mod_exp\fR\|(3) is called with suitable input,
but they may be useful when several operations are to be performed
using the same modulus.
.PP
\&\fBBN_MONT_CTX_new()\fR allocates and initializes a \fB\s-1BN_MONT_CTX\s0\fR structure.
.PP
\&\fBBN_MONT_CTX_set()\fR sets up the \fImont\fR structure from the modulus \fIm\fR
by precomputing its inverse and a value R.
.PP
\&\fBBN_MONT_CTX_copy()\fR copies the \fB\s-1BN_MONT_CTX\s0\fR \fIfrom\fR to \fIto\fR.
.PP
\&\fBBN_MONT_CTX_free()\fR frees the components of the \fB\s-1BN_MONT_CTX\s0\fR, and, if
it was created by \fBBN_MONT_CTX_new()\fR, also the structure itself.
If \fBmont\fR is \s-1NULL,\s0 nothing is done.
.PP
\&\fBBN_mod_mul_montgomery()\fR computes Mont(\fIa\fR,\fIb\fR):=\fIa\fR*\fIb\fR*R^\-1 and places
the result in \fIr\fR.
.PP
\&\fBBN_from_montgomery()\fR performs the Montgomery reduction \fIr\fR = \fIa\fR*R^\-1.
.PP
\&\fBBN_to_montgomery()\fR computes Mont(\fIa\fR,R^2), i.e. \fIa\fR*R.
Note that \fIa\fR must be nonnegative 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.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBBN_MONT_CTX_new()\fR returns the newly allocated \fB\s-1BN_MONT_CTX\s0\fR, and \s-1NULL\s0
on error.
.PP
\&\fBBN_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 \fBERR_get_error\fR\|(3).
.SH "WARNINGS"
.IX Header "WARNINGS"
The inputs must be reduced modulo \fBm\fR, otherwise the result will be
outside the expected range.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBERR_get_error\fR\|(3), \fBBN_add\fR\|(3),
\&\fBBN_CTX_new\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fBBN_MONT_CTX_init()\fR was removed in OpenSSL 1.1.0
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

207
openssl-3.4.2/doc/man/man3/BN_mod_mul_reciprocal.3
View File

@@ -1,207 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 "BN_MOD_MUL_RECIPROCAL 3ossl"
.TH BN_MOD_MUL_RECIPROCAL 3ossl "2025-07-01" "3.4.2" "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_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_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, const BIGNUM *a, BN_RECP_CTX *recp,
\& BN_CTX *ctx);
\&
\& int BN_mod_mul_reciprocal(BIGNUM *r, const BIGNUM *a, const BIGNUM *b,
\& BN_RECP_CTX *recp, BN_CTX *ctx);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBBN_mod_mul_reciprocal()\fR can be used to perform an efficient
\&\fBBN_mod_mul\fR\|(3) operation when the operation will be performed
repeatedly with the same modulus. It computes \fBr\fR=(\fBa\fR*\fBb\fR)%\fBm\fR
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
\&\fBBN_RECP_CTX_new()\fR allocates and initializes a \fB\s-1BN_RECP\s0\fR structure.
.PP
\&\fBBN_RECP_CTX_free()\fR frees the components of the \fB\s-1BN_RECP\s0\fR, and, if it
was created by \fBBN_RECP_CTX_new()\fR, also the structure itself.
If \fBrecp\fR is \s-1NULL,\s0 nothing is done.
.PP
\&\fBBN_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
integer. The result and the number of bits it was shifted left will
later be stored in \fBrecp\fR.
.PP
\&\fBBN_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 cannot be shared between threads.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBBN_RECP_CTX_new()\fR returns the newly allocated \fB\s-1BN_RECP_CTX\s0\fR, and \s-1NULL\s0
on error.
.PP
\&\fBBN_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 \fBERR_get_error\fR\|(3).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBERR_get_error\fR\|(3), \fBBN_add\fR\|(3),
\&\fBBN_CTX_new\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fBBN_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 Apache License 2.0 (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>.

195
openssl-3.4.2/doc/man/man3/BN_new.3
View File

@@ -1,195 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 "BN_NEW 3ossl"
.TH BN_NEW 3ossl "2025-07-01" "3.4.2" "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_secure_new, BN_clear, BN_free, BN_clear_free \- allocate and free BIGNUMs
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bn.h>
\&
\& BIGNUM *BN_new(void);
\&
\& BIGNUM *BN_secure_new(void);
\&
\& void BN_clear(BIGNUM *a);
\&
\& void BN_free(BIGNUM *a);
\&
\& void BN_clear_free(BIGNUM *a);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBBN_new()\fR allocates and initializes a \fB\s-1BIGNUM\s0\fR structure.
\&\fBBN_secure_new()\fR does the same except that the secure heap
\&\fBOPENSSL_secure_malloc\fR\|(3) is used to store the value.
.PP
\&\fBBN_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
to the value 0.
If \fBa\fR is \s-1NULL,\s0 nothing is done.
.PP
\&\fBBN_free()\fR frees the components of the \fB\s-1BIGNUM\s0\fR, and if it was created
by \fBBN_new()\fR, also the structure itself. \fBBN_clear_free()\fR additionally
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"
\&\fBBN_new()\fR and \fBBN_secure_new()\fR
return a pointer to the \fB\s-1BIGNUM\s0\fR initialised to the value 0.
If the allocation fails,
they return \fB\s-1NULL\s0\fR and set an error code that can be obtained
by \fBERR_get_error\fR\|(3).
.PP
\&\fBBN_clear()\fR, \fBBN_free()\fR and \fBBN_clear_free()\fR have no return values.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBERR_get_error\fR\|(3), \fBOPENSSL_secure_malloc\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fBBN_init()\fR was removed in OpenSSL 1.1.0; use \fBBN_new()\fR instead.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2017 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

192
openssl-3.4.2/doc/man/man3/BN_num_bytes.3
View File

@@ -1,192 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 "BN_NUM_BYTES 3ossl"
.TH BN_NUM_BYTES 3ossl "2025-07-01" "3.4.2" "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_num_bits, BN_num_bytes, BN_num_bits_word \- get BIGNUM size
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bn.h>
\&
\& int BN_num_bytes(const BIGNUM *a);
\&
\& int BN_num_bits(const BIGNUM *a);
\&
\& int BN_num_bits_word(BN_ULONG w);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBBN_num_bytes()\fR returns the size of a \fB\s-1BIGNUM\s0\fR in bytes.
.PP
\&\fBBN_num_bits_word()\fR returns the number of significant bits in a word.
If we take 0x00000432 as an example, it returns 11, not 16, not 32.
Basically, except for a zero, it returns \fIfloor(log2(w))+1\fR.
.PP
\&\fBBN_num_bits()\fR returns the number of significant bits in a \fB\s-1BIGNUM\s0\fR,
following the same principle as \fBBN_num_bits_word()\fR.
.PP
\&\fBBN_num_bytes()\fR is a macro.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
The size.
.SH "NOTES"
.IX Header "NOTES"
Some have tried using \fBBN_num_bits()\fR on individual numbers in \s-1RSA\s0 keys,
\&\s-1DH\s0 keys and \s-1DSA\s0 keys, and found that they don't always come up with
the number of bits they expected (something like 512, 1024, 2048,
\&...). This is because generating a number with some specific number
of bits doesn't always set the highest bits, thereby making the number
of \fIsignificant\fR bits a little lower. If you want to know the \*(L"key
size\*(R" of such a key, either use functions like \fBRSA_size()\fR, \fBDH_size()\fR
and \fBDSA_size()\fR, or use \fBBN_num_bytes()\fR and multiply with 8 (although
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"
\&\fBDH_size\fR\|(3), \fBDSA_size\fR\|(3),
\&\fBRSA_size\fR\|(3)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2017 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

252
openssl-3.4.2/doc/man/man3/BN_rand.3
View File

@@ -1,252 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 "BN_RAND 3ossl"
.TH BN_RAND 3ossl "2025-07-01" "3.4.2" "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_ex, BN_rand, BN_priv_rand_ex, BN_priv_rand, BN_pseudo_rand,
BN_rand_range_ex, BN_rand_range, BN_priv_rand_range_ex, BN_priv_rand_range,
BN_pseudo_rand_range
\&\- generate pseudo\-random number
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bn.h>
\&
\& int BN_rand_ex(BIGNUM *rnd, int bits, int top, int bottom,
\& unsigned int strength, BN_CTX *ctx);
\& int BN_rand(BIGNUM *rnd, int bits, int top, int bottom);
\&
\& int BN_priv_rand_ex(BIGNUM *rnd, int bits, int top, int bottom,
\& unsigned int strength, BN_CTX *ctx);
\& int BN_priv_rand(BIGNUM *rnd, int bits, int top, int bottom);
\&
\& int BN_rand_range_ex(BIGNUM *rnd, const BIGNUM *range, unsigned int strength,
\& BN_CTX *ctx);
\& int BN_rand_range(BIGNUM *rnd, const BIGNUM *range);
\&
\& int BN_priv_rand_range_ex(BIGNUM *rnd, const BIGNUM *range, unsigned int strength,
\& BN_CTX *ctx);
\& int BN_priv_rand_range(BIGNUM *rnd, const BIGNUM *range);
.Ve
.PP
The following functions have been deprecated since OpenSSL 3.0, and can be
hidden entirely by defining \fB\s-1OPENSSL_API_COMPAT\s0\fR with a suitable version value,
see \fBopenssl_user_macros\fR\|(7):
.PP
.Vb 2
\& int BN_pseudo_rand(BIGNUM *rnd, int bits, int top, int bottom);
\& int BN_pseudo_rand_range(BIGNUM *rnd, const BIGNUM *range);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBBN_rand_ex()\fR generates a cryptographically strong pseudo-random
number of \fIbits\fR in length and security strength at least \fIstrength\fR bits
using the random number generator for the library context associated with
\&\fIctx\fR. The function stores the generated data in \fIrnd\fR. The parameter \fIctx\fR
may be \s-1NULL\s0 in which case the default library context is used.
If \fIbits\fR is less than zero, or too small to
accommodate the requirements specified by the \fItop\fR and \fIbottom\fR
parameters, an error is returned.
The \fItop\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*\fIbits\fR length.
If \fIbottom\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 \fIbits\fR is 1 then \fItop\fR cannot also be \fB\s-1BN_RAND_TOP_TWO\s0\fR.
.PP
\&\fBBN_rand()\fR is the same as \fBBN_rand_ex()\fR except that the default library context
is always used.
.PP
\&\fBBN_rand_range_ex()\fR generates a cryptographically strong pseudo-random
number \fIrnd\fR, of security strength at least \fIstrength\fR bits,
in the range 0 <= \fIrnd\fR < \fIrange\fR using the random number
generator for the library context associated with \fIctx\fR. The parameter \fIctx\fR
may be \s-1NULL\s0 in which case the default library context is used.
.PP
\&\fBBN_rand_range()\fR is the same as \fBBN_rand_range_ex()\fR except that the default
library context is always used.
.PP
\&\fBBN_priv_rand_ex()\fR, \fBBN_priv_rand()\fR, \fBBN_priv_rand_rand_ex()\fR and
\&\fBBN_priv_rand_range()\fR have the same semantics as \fBBN_rand_ex()\fR, \fBBN_rand()\fR,
\&\fBBN_rand_range_ex()\fR and \fBBN_rand_range()\fR respectively. They are intended to be
used for generating values that should remain private, and mirror the
same difference between \fBRAND_bytes\fR\|(3) and \fBRAND_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 \fBERR_get_error\fR\|(3).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBERR_get_error\fR\|(3),
\&\fBRAND_add\fR\|(3),
\&\fBRAND_bytes\fR\|(3),
\&\fBRAND_priv_bytes\fR\|(3),
\&\s-1\fBRAND\s0\fR\|(7),
\&\s-1\fBEVP_RAND\s0\fR\|(7)
.SH "HISTORY"
.IX Header "HISTORY"
.IP "\(bu" 2
Starting with OpenSSL release 1.1.0, \fBBN_pseudo_rand()\fR has been identical
to \fBBN_rand()\fR and \fBBN_pseudo_rand_range()\fR has been identical to
\&\fBBN_rand_range()\fR.
The \fBBN_pseudo_rand()\fR and \fBBN_pseudo_rand_range()\fR functions were
deprecated in OpenSSL 3.0.
.IP "\(bu" 2
The \fBBN_priv_rand()\fR and \fBBN_priv_rand_range()\fR functions were added in
OpenSSL 1.1.1.
.IP "\(bu" 2
The \fBBN_rand_ex()\fR, \fBBN_priv_rand_ex()\fR, \fBBN_rand_range_ex()\fR and
\&\fBBN_priv_rand_range_ex()\fR functions were added in OpenSSL 3.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2022 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

181
openssl-3.4.2/doc/man/man3/BN_security_bits.3
View File

@@ -1,181 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 "BN_SECURITY_BITS 3ossl"
.TH BN_SECURITY_BITS 3ossl "2025-07-01" "3.4.2" "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_security_bits \- returns bits of security based on given numbers
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bn.h>
\&
\& int BN_security_bits(int L, int N);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBBN_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, \fBBN_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"
\&\s-1ECC\s0 (Elliptic Curve Cryptography) is not covered by the \fBBN_security_bits()\fR
function. The symmetric algorithms are not covered neither.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBDH_security_bits\fR\|(3), \fBDSA_security_bits\fR\|(3), \fBRSA_security_bits\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
The \fBBN_security_bits()\fR function was added in OpenSSL 1.1.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2017\-2019 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

204
openssl-3.4.2/doc/man/man3/BN_set_bit.3
View File

@@ -1,204 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 "BN_SET_BIT 3ossl"
.TH BN_SET_BIT 3ossl "2025-07-01" "3.4.2" "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
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bn.h>
\&
\& int BN_set_bit(BIGNUM *a, int n);
\& int BN_clear_bit(BIGNUM *a, int n);
\&
\& int BN_is_bit_set(const BIGNUM *a, int n);
\&
\& int BN_mask_bits(BIGNUM *a, int n);
\&
\& int BN_lshift(BIGNUM *r, const BIGNUM *a, int n);
\& int BN_lshift1(BIGNUM *r, BIGNUM *a);
\&
\& int BN_rshift(BIGNUM *r, BIGNUM *a, int n);
\& int BN_rshift1(BIGNUM *r, BIGNUM *a);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBBN_set_bit()\fR sets bit \fBn\fR in \fBa\fR to 1 (\f(CW\*(C`a|=(1<<n)\*(C'\fR). The
number is expanded if necessary.
.PP
\&\fBBN_clear_bit()\fR sets bit \fBn\fR in \fBa\fR to 0 (\f(CW\*(C`a&=~(1<<n)\*(C'\fR). An
error occurs if \fBa\fR is shorter than \fBn\fR bits.
.PP
\&\fBBN_is_bit_set()\fR tests if bit \fBn\fR in \fBa\fR is set.
.PP
\&\fBBN_mask_bits()\fR truncates \fBa\fR to an \fBn\fR bit number
(\f(CW\*(C`a&=~((~0)<<n)\*(C'\fR). An error occurs if \fBn\fR is negative. An error is
also returned if the internal representation of \fBa\fR is already shorter than
\&\fBn\fR bits. The internal representation depends on the platform's word size, and
this error can be safely ignored. Use \fBBN_num_bits\fR\|(3) to determine the exact
number of bits if needed.
.PP
\&\fBBN_lshift()\fR shifts \fBa\fR left by \fBn\fR bits and places the result in
\&\fBr\fR (\f(CW\*(C`r=a*2^n\*(C'\fR). Note that \fBn\fR must be nonnegative. \fBBN_lshift1()\fR shifts
\&\fBa\fR left by one and places the result in \fBr\fR (\f(CW\*(C`r=2*a\*(C'\fR).
.PP
\&\fBBN_rshift()\fR shifts \fBa\fR right by \fBn\fR bits and places the result in
\&\fBr\fR (\f(CW\*(C`r=a/2^n\*(C'\fR). Note that \fBn\fR must be nonnegative. \fBBN_rshift1()\fR shifts
\&\fBa\fR right by one and places the result in \fBr\fR (\f(CW\*(C`r=a/2\*(C'\fR).
.PP
For the shift functions, \fBr\fR and \fBa\fR may be the same variable.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBBN_is_bit_set()\fR returns 1 if the bit is set, 0 otherwise.
.PP
All other functions return 1 for success, 0 on error. The error codes
can be obtained by \fBERR_get_error\fR\|(3).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBBN_num_bytes\fR\|(3), \fBBN_add\fR\|(3)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2024 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

163
openssl-3.4.2/doc/man/man3/BN_swap.3
View File

@@ -1,163 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 "BN_SWAP 3ossl"
.TH BN_SWAP 3ossl "2025-07-01" "3.4.2" "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_swap \- exchange BIGNUMs
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bn.h>
\&
\& void BN_swap(BIGNUM *a, BIGNUM *b);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBBN_swap()\fR exchanges the values of \fIa\fR and \fIb\fR.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBBN_swap()\fR does not return a value.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

198
openssl-3.4.2/doc/man/man3/BN_zero.3
View File

@@ -1,198 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 "BN_ZERO 3ossl"
.TH BN_ZERO 3ossl "2025-07-01" "3.4.2" "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
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bn.h>
\&
\& void BN_zero(BIGNUM *a);
\& int BN_one(BIGNUM *a);
\&
\& const BIGNUM *BN_value_one(void);
\&
\& int BN_set_word(BIGNUM *a, BN_ULONG w);
\& unsigned BN_ULONG BN_get_word(BIGNUM *a);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\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
\&\fBBN_zero()\fR, \fBBN_one()\fR and \fBBN_set_word()\fR set \fBa\fR to the values 0, 1 and
\&\fBw\fR respectively. \fBBN_zero()\fR and \fBBN_one()\fR are macros.
.PP
\&\fBBN_value_one()\fR returns a \fB\s-1BIGNUM\s0\fR constant of value 1. This constant
is useful for use in comparisons and assignment.
.PP
\&\fBBN_get_word()\fR returns \fBa\fR, if it can be represented as a \fB\s-1BN_ULONG\s0\fR.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBBN_get_word()\fR returns the value \fBa\fR, or all-bits-set if \fBa\fR cannot
be represented as a single integer.
.PP
\&\fBBN_one()\fR and \fBBN_set_word()\fR return 1 on success, 0 otherwise.
\&\fBBN_value_one()\fR returns the constant.
\&\fBBN_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
with the error condition returned by \fBBN_get_word()\fR which uses that
as an error value.
.PP
\&\fB\s-1BN_ULONG\s0\fR should probably be a typedef.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBBN_bn2bin\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
In OpenSSL 0.9.8, \fBBN_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
Licensed under the Apache License 2.0 (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>.

207
openssl-3.4.2/doc/man/man3/BUF_MEM_new.3
View File

@@ -1,207 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 "BUF_MEM_NEW 3ossl"
.TH BUF_MEM_NEW 3ossl "2025-07-01" "3.4.2" "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,
BUF_MEM_grow_clean, BUF_reverse
\&\- simple character array structure
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/buffer.h>
\&
\& BUF_MEM *BUF_MEM_new(void);
\&
\& BUF_MEM *BUF_MEM_new_ex(unsigned long flags);
\&
\& void BUF_MEM_free(BUF_MEM *a);
\&
\& int BUF_MEM_grow(BUF_MEM *str, int len);
\& size_t BUF_MEM_grow_clean(BUF_MEM *str, size_t len);
\&
\& void BUF_reverse(unsigned char *out, const unsigned char *in, size_t size);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The buffer library handles simple character arrays. Buffers are used for
various purposes in the library, most notably memory BIOs.
.PP
\&\fBBUF_MEM_new()\fR allocates a new buffer of zero size.
.PP
\&\fBBUF_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 \fBCRYPTO_secure_malloc\fR\|(3).
.PP
\&\fBBUF_MEM_free()\fR frees up an already existing buffer. The data is zeroed
before freeing up in case the buffer contains sensitive data.
If the argument is \s-1NULL,\s0 nothing is done.
.PP
\&\fBBUF_MEM_grow()\fR changes the size of an already existing buffer to
\&\fBlen\fR. Any data already in the buffer is preserved if it increases in
size.
.PP
\&\fBBUF_MEM_grow_clean()\fR is similar to \fBBUF_MEM_grow()\fR but it sets any free'd
or additionally-allocated memory to zero.
.PP
\&\fBBUF_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"
\&\fBBUF_MEM_new()\fR returns the buffer or \s-1NULL\s0 on error.
.PP
\&\fBBUF_MEM_free()\fR has no return value.
.PP
\&\fBBUF_MEM_grow()\fR and \fBBUF_MEM_grow_clean()\fR return
zero on error or the new size (i.e., \fBlen\fR).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBbio\fR\|(7),
\&\fBCRYPTO_secure_malloc\fR\|(3).
.SH "HISTORY"
.IX Header "HISTORY"
The \fBBUF_MEM_new_ex()\fR function was added in OpenSSL 1.1.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2024 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

246
openssl-3.4.2/doc/man/man3/CMAC_CTX.3
View File

@@ -1,246 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 "CMAC_CTX 3ossl"
.TH CMAC_CTX 3ossl "2025-07-01" "3.4.2" "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"
CMAC_CTX, CMAC_CTX_new, CMAC_CTX_cleanup, CMAC_CTX_free,
CMAC_CTX_get0_cipher_ctx, CMAC_CTX_copy, CMAC_Init, CMAC_Update, CMAC_Final,
CMAC_resume
\&\- create cipher\-based message authentication codes
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/cmac.h>
.Ve
.PP
The following functions have been deprecated since OpenSSL 3.0, and can be
disabled entirely by defining \fB\s-1OPENSSL_API_COMPAT\s0\fR with a suitable version
value, see \fBopenssl_user_macros\fR\|(7).
.PP
.Vb 1
\& typedef struct CMAC_CTX_st CMAC_CTX;
\&
\& CMAC_CTX *CMAC_CTX_new(void);
\& void CMAC_CTX_cleanup(CMAC_CTX *ctx);
\& void CMAC_CTX_free(CMAC_CTX *ctx);
\& EVP_CIPHER_CTX *CMAC_CTX_get0_cipher_ctx(CMAC_CTX *ctx);
\& int CMAC_CTX_copy(CMAC_CTX *out, const CMAC_CTX *in);
\& int CMAC_Init(CMAC_CTX *ctx, const void *key, size_t keylen,
\& const EVP_CIPHER *cipher, ENGINE *impl);
\& int CMAC_Update(CMAC_CTX *ctx, const void *data, size_t dlen);
\& int CMAC_Final(CMAC_CTX *ctx, unsigned char *out, size_t *poutlen);
\& int CMAC_resume(CMAC_CTX *ctx);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The low-level \s-1MAC\s0 functions documented on this page are deprecated.
Applications should use the new \s-1\fBEVP_MAC\s0\fR\|(3) interface.
Specifically, utilize the following functions for \s-1MAC\s0 operations:
.IP "\fBEVP_MAC_CTX_new\fR\|(3) to create a new \s-1MAC\s0 context." 4
.IX Item "EVP_MAC_CTX_new to create a new MAC context."
.PD 0
.IP "\fBEVP_MAC_CTX_free\fR\|(3) to free the \s-1MAC\s0 context." 4
.IX Item "EVP_MAC_CTX_free to free the MAC context."
.IP "\fBEVP_MAC_init\fR\|(3) to initialize the \s-1MAC\s0 context." 4
.IX Item "EVP_MAC_init to initialize the MAC context."
.IP "\fBEVP_MAC_update\fR\|(3) to update the \s-1MAC\s0 with data." 4
.IX Item "EVP_MAC_update to update the MAC with data."
.IP "\fBEVP_MAC_final\fR\|(3) to finalize the \s-1MAC\s0 and retrieve the output." 4
.IX Item "EVP_MAC_final to finalize the MAC and retrieve the output."
.PD
.PP
Alternatively, for a single-step \s-1MAC\s0 computation, use the \fBEVP_Q_mac\fR\|(3)
function.
.PP
The \fB\s-1CMAC_CTX\s0\fR type is a structure used for the provision of \s-1CMAC\s0
(Cipher-based Message Authentication Code) operations.
.PP
\&\fBCMAC_CTX_new()\fR creates a new \fB\s-1CMAC_CTX\s0\fR structure and returns a pointer to it.
.PP
\&\fBCMAC_CTX_cleanup()\fR resets the \fB\s-1CMAC_CTX\s0\fR structure, clearing any internal data
but not freeing the structure itself.
.PP
\&\fBCMAC_CTX_free()\fR frees the \fB\s-1CMAC_CTX\s0\fR structure and any associated resources.
If the argument is \s-1NULL,\s0 no action is taken.
.PP
\&\fBCMAC_CTX_get0_cipher_ctx()\fR returns a pointer to the internal \fB\s-1EVP_CIPHER_CTX\s0\fR
structure within the \fB\s-1CMAC_CTX\s0\fR.
.PP
\&\fBCMAC_CTX_copy()\fR copies the state from one \fB\s-1CMAC_CTX\s0\fR structure to another.
.PP
\&\fBCMAC_Init()\fR initializes the \fB\s-1CMAC_CTX\s0\fR structure for a new \s-1CMAC\s0 calculation
with the specified key, key length, and cipher type.
Optionally, an \fB\s-1ENGINE\s0\fR can be provided.
.PP
\&\fBCMAC_Update()\fR processes data to be included in the \s-1CMAC\s0 calculation.
This function can be called multiple times to update the context with
additional data.
.PP
\&\fBCMAC_Final()\fR finalizes the \s-1CMAC\s0 calculation and retrieves the resulting
\&\s-1MAC\s0 value. The output is stored in the provided buffer, and the length is
stored in the variable pointed to by \fIpoutlen\fR. To determine the required
buffer size, call with \fIout\fR set to \s-1NULL,\s0 which stores only the length in
\&\fIpoutlen\fR. Allocate a buffer of this size and call \fBCMAC_Final()\fR again with
the allocated buffer to retrieve the \s-1MAC.\s0
.PP
\&\fBCMAC_resume()\fR resumes a previously finalized \s-1CMAC\s0 calculation, allowing
additional data to be processed and a new \s-1MAC\s0 to be generated.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBCMAC_CTX_new()\fR returns a pointer to a new \fB\s-1CMAC_CTX\s0\fR structure or \s-1NULL\s0 if
an error occurs.
.PP
\&\fBCMAC_CTX_get0_cipher_ctx()\fR returns a pointer to the internal
\&\fB\s-1EVP_CIPHER_CTX\s0\fR structure, or \s-1NULL\s0 if an error occurs.
.PP
\&\fBCMAC_CTX_copy()\fR, \fBCMAC_Init()\fR, \fBCMAC_Update()\fR, \fBCMAC_Final()\fR and \fBCMAC_resume()\fR
return 1 for success or 0 if an error occurs.
.SH "HISTORY"
.IX Header "HISTORY"
All functions described here were deprecated in OpenSSL 3.0. For replacements,
see \fBEVP_MAC_CTX_new\fR\|(3), \fBEVP_MAC_CTX_free\fR\|(3), \fBEVP_MAC_init\fR\|(3),
\&\fBEVP_MAC_update\fR\|(3), and \fBEVP_MAC_final\fR\|(3).
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2024 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

199
openssl-3.4.2/doc/man/man3/CMS_EncryptedData_decrypt.3
View File

@@ -1,199 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 "CMS_ENCRYPTEDDATA_DECRYPT 3ossl"
.TH CMS_ENCRYPTEDDATA_DECRYPT 3ossl "2025-07-01" "3.4.2" "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_EncryptedData_decrypt, CMS_EnvelopedData_decrypt
\&\- Decrypt CMS EncryptedData or EnvelopedData
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/cms.h>
\&
\& int CMS_EncryptedData_decrypt(CMS_ContentInfo *cms,
\& const unsigned char *key, size_t keylen,
\& BIO *dcont, BIO *out, unsigned int flags);
\&
\& BIO *CMS_EnvelopedData_decrypt(CMS_EnvelopedData *env, BIO *detached_data,
\& EVP_PKEY *pkey, X509 *cert,
\& ASN1_OCTET_STRING *secret, unsigned int flags,
\& OSSL_LIB_CTX *libctx, const char *propq);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBCMS_EncryptedData_decrypt()\fR decrypts a \fIcms\fR EncryptedData object using the
symmetric \fIkey\fR of size \fIkeylen\fR bytes. \fIout\fR is a \s-1BIO\s0 to write the content
to and \fIflags\fR is an optional set of flags.
\&\fIdcont\fR is used in the rare case where the encrypted content is detached. It
will normally be set to \s-1NULL.\s0
.PP
The following flags can be passed in the \fIflags\fR parameter.
.PP
If the \fB\s-1CMS_TEXT\s0\fR flag is set \s-1MIME\s0 headers for type \f(CW\*(C`text/plain\*(C'\fR are deleted
from the content. If the content is not of type \f(CW\*(C`text/plain\*(C'\fR then an error is
returned.
.PP
\&\fBCMS_EnvelopedData_decrypt()\fR decrypts, similarly to \fBCMS_decrypt\fR\|(3),
a \s-1CMS\s0 EnvelopedData object \fIenv\fR using the symmetric key \fIsecret\fR if it
is not \s-1NULL,\s0 otherwise the private key of the recipient \fIpkey\fR.
If \fIpkey\fR is given, it is recommended to provide also the associated
certificate in \fIcert\fR \- see \fBCMS_decrypt\fR\|(3) and the \s-1NOTES\s0 on \fIcert\fR there.
The optional parameters \fIflags\fR and \fIdcont\fR are used as described above.
The optional parameters library context \fIlibctx\fR and property query \fIpropq\fR
are used when retrieving algorithms from providers.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBCMS_EncryptedData_decrypt()\fR returns 0 if an error occurred otherwise returns 1.
.PP
\&\fBCMS_EnvelopedData_decrypt()\fR returns \s-1NULL\s0 if an error occurred,
otherwise a \s-1BIO\s0 containing the decypted content.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBERR_get_error\fR\|(3), \fBCMS_EncryptedData_encrypt\fR\|(3), \fBCMS_decrypt\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fBCMS_EnvelopedData_decrypt()\fR was added in OpenSSL 3.2.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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
openssl-3.4.2/doc/man/man3/CMS_EncryptedData_encrypt.3
View File

@@ -1,200 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 "CMS_ENCRYPTEDDATA_ENCRYPT 3ossl"
.TH CMS_ENCRYPTEDDATA_ENCRYPT 3ossl "2025-07-01" "3.4.2" "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_EncryptedData_encrypt_ex, CMS_EncryptedData_encrypt
\&\- Create CMS EncryptedData
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/cms.h>
\&
\& CMS_ContentInfo *CMS_EncryptedData_encrypt_ex(BIO *in,
\& const EVP_CIPHER *cipher,
\& const unsigned char *key,
\& size_t keylen,
\& unsigned int flags,
\& OSSL_LIB_CTX *ctx,
\& const char *propq);
\&
\& CMS_ContentInfo *CMS_EncryptedData_encrypt(BIO *in,
\& const EVP_CIPHER *cipher, const unsigned char *key, size_t keylen,
\& unsigned int flags);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBCMS_EncryptedData_encrypt_ex()\fR creates a \fBCMS_ContentInfo\fR structure
with a type \fBNID_pkcs7_encrypted\fR. \fIin\fR is a \s-1BIO\s0 containing the data to
encrypt using \fIcipher\fR and the encryption key \fIkey\fR of size \fIkeylen\fR bytes.
The library context \fIlibctx\fR and the property query \fIpropq\fR are used when
retrieving algorithms from providers. \fIflags\fR is a set of optional flags.
.PP
The \fIflags\fR field supports the options \fB\s-1CMS_DETACHED\s0\fR, \fB\s-1CMS_STREAM\s0\fR and
\&\fB\s-1CMS_PARTIAL\s0\fR. Internally \fBCMS_final()\fR is called unless \fB\s-1CMS_STREAM\s0\fR and/or
\&\fB\s-1CMS_PARTIAL\s0\fR is specified.
.PP
The algorithm passed in the \fIcipher\fR parameter must support \s-1ASN1\s0 encoding of
its parameters.
.PP
The \fBCMS_ContentInfo\fR structure can be freed using \fBCMS_ContentInfo_free\fR\|(3).
.PP
\&\fBCMS_EncryptedData_encrypt()\fR is similar to \fBCMS_EncryptedData_encrypt_ex()\fR
but uses default values of \s-1NULL\s0 for the library context \fIlibctx\fR and the
property query \fIpropq\fR.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
If the allocation fails, \fBCMS_EncryptedData_encrypt_ex()\fR and
\&\fBCMS_EncryptedData_encrypt()\fR return \s-1NULL\s0 and set an error code that can be
obtained by \fBERR_get_error\fR\|(3). Otherwise they return a pointer to the newly
allocated structure.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBERR_get_error\fR\|(3), \fBCMS_final\fR\|(3), \fBCMS_EncryptedData_decrypt\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
The \fBCMS_EncryptedData_encrypt_ex()\fR method was added in OpenSSL 3.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2020\-2021 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

212
openssl-3.4.2/doc/man/man3/CMS_EnvelopedData_create.3
View File

@@ -1,212 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 "CMS_ENVELOPEDDATA_CREATE 3ossl"
.TH CMS_ENVELOPEDDATA_CREATE 3ossl "2025-07-01" "3.4.2" "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_EnvelopedData_create_ex, CMS_EnvelopedData_create,
CMS_AuthEnvelopedData_create, CMS_AuthEnvelopedData_create_ex
\&\- Create CMS envelope
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/cms.h>
\&
\& CMS_ContentInfo *
\& CMS_EnvelopedData_create_ex(const EVP_CIPHER *cipher, OSSL_LIB_CTX *libctx,
\& const char *propq);
\& CMS_ContentInfo *CMS_EnvelopedData_create(const EVP_CIPHER *cipher);
\&
\& CMS_ContentInfo *
\& CMS_AuthEnvelopedData_create_ex(const EVP_CIPHER *cipher, OSSL_LIB_CTX *libctx,
\& const char *propq);
\& CMS_ContentInfo *CMS_AuthEnvelopedData_create(const EVP_CIPHER *cipher);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBCMS_EnvelopedData_create_ex()\fR creates a \fBCMS_ContentInfo\fR structure
with a type \fBNID_pkcs7_enveloped\fR. \fIcipher\fR is the symmetric cipher to use.
The library context \fIlibctx\fR and the property query \fIpropq\fR are used when
retrieving algorithms from providers.
.PP
\&\fBCMS_AuthEnvelopedData_create_ex()\fR creates a \fBCMS_ContentInfo\fR
structure with a type \fBNID_id_smime_ct_authEnvelopedData\fR. \fBcipher\fR is the
symmetric \s-1AEAD\s0 cipher to use. Currently only \s-1AES\s0 variants with \s-1GCM\s0 mode are
supported. The library context \fIlibctx\fR and the property query \fIpropq\fR are
used when retrieving algorithms from providers.
.PP
The algorithm passed in the \fIcipher\fR parameter must support \s-1ASN1\s0 encoding of
its parameters.
.PP
The recipients can be added later using \fBCMS_add1_recipient_cert\fR\|(3) or
\&\fBCMS_add0_recipient_key\fR\|(3).
.PP
The \fBCMS_ContentInfo\fR structure needs to be finalized using \fBCMS_final\fR\|(3)
and then freed using \fBCMS_ContentInfo_free\fR\|(3).
.PP
\&\fBCMS_EnvelopedData_create()\fR and \fBCMS_AuthEnvelopedData_create()\fR are similar to
\&\fBCMS_EnvelopedData_create_ex()\fR and \fBCMS_AuthEnvelopedData_create_ex()\fR
but use default values of \s-1NULL\s0 for
the library context \fIlibctx\fR and the property query \fIpropq\fR.
.SH "NOTES"
.IX Header "NOTES"
Although \fBCMS_EnvelopedData_create_ex()\fR, and \fBCMS_EnvelopedData_create()\fR,
\&\fBCMS_AuthEnvelopedData_create_ex()\fR, and \fBCMS_AuthEnvelopedData_create()\fR allocate
a new \fBCMS_ContentInfo\fR structure, they are not usually used in applications.
The wrappers \fBCMS_encrypt\fR\|(3) and \fBCMS_decrypt\fR\|(3) are often used instead.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
If the allocation fails, \fBCMS_EnvelopedData_create_ex()\fR,
\&\fBCMS_EnvelopedData_create()\fR, \fBCMS_AuthEnvelopedData_create_ex()\fR, and
\&\fBCMS_AuthEnvelopedData_create()\fR return \s-1NULL\s0 and set an error code that can be
obtained by \fBERR_get_error\fR\|(3). Otherwise they return a pointer to the newly
allocated structure.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBERR_get_error\fR\|(3), \fBCMS_encrypt\fR\|(3), \fBCMS_decrypt\fR\|(3), \fBCMS_final\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
The \fBCMS_EnvelopedData_create_ex()\fR method was added in OpenSSL 3.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2020\-2021 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

215
openssl-3.4.2/doc/man/man3/CMS_add0_cert.3
View File

@@ -1,215 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 "CMS_ADD0_CERT 3ossl"
.TH CMS_ADD0_CERT 3ossl "2025-07-01" "3.4.2" "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
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/cms.h>
\&
\& int CMS_add0_cert(CMS_ContentInfo *cms, X509 *cert);
\& int CMS_add1_cert(CMS_ContentInfo *cms, X509 *cert);
\& STACK_OF(X509) *CMS_get1_certs(CMS_ContentInfo *cms);
\&
\& int CMS_add0_crl(CMS_ContentInfo *cms, X509_CRL *crl);
\& int CMS_add1_crl(CMS_ContentInfo *cms, X509_CRL *crl);
\& STACK_OF(X509_CRL) *CMS_get1_crls(CMS_ContentInfo *cms);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBCMS_add0_cert()\fR and \fBCMS_add1_cert()\fR add certificate \fIcert\fR to \fIcms\fR
unless it is already present.
This is used by \fBCMS_sign_ex\fR\|(3) and \fBCMS_sign\fR\|(3) and may be used before
calling \fBCMS_verify\fR\|(3) to help chain building in certificate validation.
As the 0 implies, \fBCMS_add0_cert()\fR adds \fIcert\fR internally to \fIcms\fR
and on success it must not be freed up by the caller.
In contrast, the caller of \fBCMS_add1_cert()\fR must free \fIcert\fR.
\&\fIcms\fR must be of type signed data or (authenticated) enveloped data.
For signed data, such a certificate can be used when signing or verifying
to fill in the signer certificate or to provide an extra \s-1CA\s0 certificate
that may be needed for chain building in certificate validation.
.PP
\&\fBCMS_get1_certs()\fR returns all certificates in \fIcms\fR.
.PP
\&\fBCMS_add0_crl()\fR and \fBCMS_add1_crl()\fR add \s-1CRL\s0 \fIcrl\fR to \fIcms\fR.
\&\fIcms\fR must be of type signed data or (authenticated) enveloped data.
For signed data, such a \s-1CRL\s0 may be used in certificate validation
with \fBCMS_verify\fR\|(3).
It may be given both for inclusion when signing a \s-1CMS\s0 message
and when verifying a signed \s-1CMS\s0 message.
.PP
\&\fBCMS_get1_crls()\fR returns all CRLs in \fIcms\fR.
.SH "NOTES"
.IX Header "NOTES"
The CMS_ContentInfo structure \fIcms\fR must be of type signed data or enveloped
data or authenticated enveloped data or an error will be returned.
.PP
For signed data, certificates and CRLs are added to the \fIcertificates\fR and
\&\fIcrls\fR fields of SignedData structure.
For enveloped data they are added to \fBOriginatorInfo\fR.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBCMS_add0_cert()\fR, \fBCMS_add1_cert()\fR and \fBCMS_add0_crl()\fR and \fBCMS_add1_crl()\fR return
1 for success and 0 for failure.
.PP
\&\fBCMS_get1_certs()\fR and \fBCMS_get1_crls()\fR return the \s-1STACK\s0 of certificates or CRLs
or \s-1NULL\s0 if there are none or an error occurs.
Besides out-of-memory, the only error which will occur
in practice is if the \fIcms\fR type is invalid.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBERR_get_error\fR\|(3),
\&\fBCMS_sign\fR\|(3), \fBCMS_sign_ex\fR\|(3), \fBCMS_verify\fR\|(3),
\&\fBCMS_encrypt\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fBCMS_add0_cert()\fR and \fBCMS_add1_cert()\fR have been changed in OpenSSL 3.2
not to throw an error if a certificate to be added is already present.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2008\-2024 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

216
openssl-3.4.2/doc/man/man3/CMS_add1_recipient_cert.3
View File

@@ -1,216 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 "CMS_ADD1_RECIPIENT_CERT 3ossl"
.TH CMS_ADD1_RECIPIENT_CERT 3ossl "2025-07-01" "3.4.2" "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_add1_recipient, 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(CMS_ContentInfo *cms, X509 *recip,
\& EVP_PKEY *originatorPrivKey,
\& X509 *originator, 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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBCMS_add1_recipient()\fR adds recipient \fBrecip\fR and provides the originator pkey
\&\fBoriginatorPrivKey\fR and originator certificate \fBoriginator\fR to CMS_ContentInfo.
The originator-related fields are relevant only in case when the keyAgreement
method of providing of the shared key is in use.
.PP
\&\fBCMS_add1_recipient_cert()\fR adds recipient \fBrecip\fR to CMS_ContentInfo enveloped
data structure \fBcms\fR as a KeyTransRecipientInfo structure.
.PP
\&\fBCMS_add0_recipient_key()\fR adds symmetric key \fBkey\fR of length \fBkeylen\fR using
wrapping algorithm \fBnid\fR, identifier \fBid\fR of length \fBidlen\fR and optional
values \fBdate\fR, \fBotherTypeId\fR and \fBotherType\fR to CMS_ContentInfo enveloped
data structure \fBcms\fR as a KEKRecipientInfo structure.
.PP
The CMS_ContentInfo structure should be obtained from an initial call to
\&\fBCMS_encrypt()\fR with the flag \fB\s-1CMS_PARTIAL\s0\fR set.
.SH "NOTES"
.IX Header "NOTES"
The main purpose of this function is to provide finer control over a \s-1CMS\s0
enveloped data structure where the simpler \fBCMS_encrypt()\fR function defaults are
not appropriate. For example if one or more KEKRecipientInfo structures
need to be added. New attributes can also be added using the returned
CMS_RecipientInfo structure and the \s-1CMS\s0 attribute utility functions.
.PP
OpenSSL will by default identify recipient certificates using issuer name
and serial number. If \fB\s-1CMS_USE_KEYID\s0\fR is set it will use the subject key
identifier value instead. An error occurs if all recipient certificates do not
have a subject key identifier extension.
.PP
Currently only \s-1AES\s0 based key wrapping algorithms are supported for \fBnid\fR,
specifically: NID_id_aes128_wrap, NID_id_aes192_wrap and NID_id_aes256_wrap.
If \fBnid\fR is set to \fBNID_undef\fR then an \s-1AES\s0 wrap algorithm will be used
consistent with \fBkeylen\fR.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBCMS_add1_recipient_cert()\fR and \fBCMS_add0_recipient_key()\fR return an internal
pointer to the CMS_RecipientInfo structure just added or \s-1NULL\s0 if an error
occurs.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBERR_get_error\fR\|(3), \fBCMS_decrypt\fR\|(3),
\&\fBCMS_final\fR\|(3),
.SH "HISTORY"
.IX Header "HISTORY"
\&\fBCMS_add1_recipient_cert\fR and \fBCMS_add0_recipient_key\fR were added in
OpenSSL 3.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2008\-2020 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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
openssl-3.4.2/doc/man/man3/CMS_add1_signer.3
View File

@@ -1,240 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 "CMS_ADD1_SIGNER 3ossl"
.TH CMS_ADD1_SIGNER 3ossl "2025-07-01" "3.4.2" "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_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);
\&
\& int CMS_SignerInfo_sign(CMS_SignerInfo *si);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBCMS_add1_signer()\fR adds a signer with certificate \fBsigncert\fR and private
key \fBpkey\fR using message digest \fBmd\fR to CMS_ContentInfo SignedData
structure \fBcms\fR.
.PP
The CMS_ContentInfo structure should be obtained from an initial call to
\&\fBCMS_sign()\fR with the flag \fB\s-1CMS_PARTIAL\s0\fR set or in the case or re-signing a
valid CMS_ContentInfo SignedData structure.
.PP
If the \fBmd\fR parameter is \fB\s-1NULL\s0\fR then the default digest for the public
key algorithm will be used.
.PP
Unless the \fB\s-1CMS_REUSE_DIGEST\s0\fR flag is set the returned CMS_ContentInfo
structure is not complete and must be finalized either by streaming (if
applicable) or a call to \fBCMS_final()\fR.
.PP
The \fBCMS_SignerInfo_sign()\fR function explicitly signs a CMS_SignerInfo
structure, its main use is when the \fB\s-1CMS_REUSE_DIGEST\s0\fR and \fB\s-1CMS_PARTIAL\s0\fR flags
are both set.
.SH "NOTES"
.IX Header "NOTES"
The main purpose of \fBCMS_add1_signer()\fR is to provide finer control
over a \s-1CMS\s0 signed data structure where the simpler \fBCMS_sign()\fR function defaults
are not appropriate. For example if multiple signers or non default digest
algorithms are needed. New attributes can also be added using the returned
CMS_SignerInfo structure and the \s-1CMS\s0 attribute utility functions or the
\&\s-1CMS\s0 signed receipt request functions.
.PP
Any of the following flags (ored together) can be passed in the \fBflags\fR
parameter.
.PP
If \fB\s-1CMS_REUSE_DIGEST\s0\fR is set then an attempt is made to copy the content
digest value from the CMS_ContentInfo structure: to add a signer to an existing
structure. An error occurs if a matching digest value cannot be found to copy.
The returned CMS_ContentInfo structure will be valid and finalized when this
flag is set.
.PP
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 \fBCMS_SignerInfo_sign()\fR is
needed to finalize it.
.PP
If \fB\s-1CMS_NOCERTS\s0\fR is set the signer's certificate will not be included in the
CMS_ContentInfo structure, the signer's certificate must still be supplied in
the \fBsigncert\fR parameter though. This can reduce the size of the signature if
the signers certificate can be obtained by other means: for example a
previously signed message.
.PP
The SignedData structure includes several \s-1CMS\s0 signedAttributes including the
signing time, the \s-1CMS\s0 content type and the supported list of ciphers in an
SMIMECapabilities attribute. If \fB\s-1CMS_NOATTR\s0\fR is set then no signedAttributes
will be used. If \fB\s-1CMS_NOSMIMECAP\s0\fR is set then just the SMIMECapabilities are
omitted.
.PP
OpenSSL will by default identify signing certificates using issuer name
and serial number. If \fB\s-1CMS_USE_KEYID\s0\fR is set it will use the subject key
identifier value instead. An error occurs if the signing certificate does not
have a subject key identifier extension.
.PP
If present the SMIMECapabilities attribute indicates support for the following
algorithms in preference order: 256 bit \s-1AES,\s0 Gost R3411\-94, Gost 28147\-89, 192
bit \s-1AES, 128\s0 bit \s-1AES,\s0 triple \s-1DES, 128\s0 bit \s-1RC2, 64\s0 bit \s-1RC2, DES\s0 and 40 bit \s-1RC2.\s0
If any of these algorithms is not available then it will not be included: for example the \s-1GOST\s0 algorithms will not be included if the \s-1GOST ENGINE\s0 is
not loaded.
.PP
\&\fBCMS_add1_signer()\fR returns an internal pointer to the CMS_SignerInfo
structure just added, this can be used to set additional attributes
before it is finalized.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBCMS_add1_signer()\fR returns an internal pointer to the CMS_SignerInfo
structure just added or \s-1NULL\s0 if an error occurs.
.PP
\&\fBCMS_SignerInfo_sign()\fR returns 1 on success, 0 on failure.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBERR_get_error\fR\|(3), \fBCMS_sign\fR\|(3),
\&\fBCMS_final\fR\|(3),
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2014\-2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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
openssl-3.4.2/doc/man/man3/CMS_compress.3
View File

@@ -1,208 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 "CMS_COMPRESS 3ossl"
.TH CMS_COMPRESS 3ossl "2025-07-01" "3.4.2" "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_compress \- create a CMS CompressedData structure
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/cms.h>
\&
\& CMS_ContentInfo *CMS_compress(BIO *in, int comp_nid, unsigned int flags);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBCMS_compress()\fR creates and returns a \s-1CMS\s0 CompressedData structure. \fBcomp_nid\fR
is the compression algorithm to use or \fBNID_undef\fR to use the default
algorithm (zlib compression). \fBin\fR is the content to be compressed.
\&\fBflags\fR is an optional set of flags.
.PP
The only currently supported compression algorithm is zlib using the \s-1NID\s0
NID_zlib_compression.
.PP
If zlib support is not compiled into OpenSSL then \fBCMS_compress()\fR will return
an error.
.PP
If the \fB\s-1CMS_TEXT\s0\fR flag is set \s-1MIME\s0 headers for type \fBtext/plain\fR are
prepended to the data.
.PP
Normally the supplied content is translated into \s-1MIME\s0 canonical format (as
required by the S/MIME specifications) if \fB\s-1CMS_BINARY\s0\fR is set no translation
occurs. This option should be used if the supplied data is in binary format
otherwise the translation will corrupt it. If \fB\s-1CMS_BINARY\s0\fR is set then
\&\fB\s-1CMS_TEXT\s0\fR is ignored.
.PP
If the \fB\s-1CMS_STREAM\s0\fR flag is set a partial \fBCMS_ContentInfo\fR structure is
returned suitable for streaming I/O: no data is read from the \s-1BIO\s0 \fBin\fR.
.PP
The compressed data is included in the CMS_ContentInfo structure, unless
\&\fB\s-1CMS_DETACHED\s0\fR is set in which case it is omitted. This is rarely used in
practice and is not supported by \fBSMIME_write_CMS()\fR.
.PP
If the flag \fB\s-1CMS_STREAM\s0\fR is set the returned \fBCMS_ContentInfo\fR structure is
\&\fBnot\fR complete and outputting its contents via a function that does not
properly finalize the \fBCMS_ContentInfo\fR structure will give unpredictable
results.
.PP
Several functions including \fBSMIME_write_CMS()\fR, \fBi2d_CMS_bio_stream()\fR,
\&\fBPEM_write_bio_CMS_stream()\fR finalize the structure. Alternatively finalization
can be performed by obtaining the streaming \s-1ASN1\s0 \fB\s-1BIO\s0\fR directly using
\&\fBBIO_new_CMS()\fR.
.PP
Additional compression parameters such as the zlib compression level cannot
currently be set.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBCMS_compress()\fR returns either a CMS_ContentInfo structure or \s-1NULL\s0 if an error
occurred. The error can be obtained from \fBERR_get_error\fR\|(3).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBERR_get_error\fR\|(3), \fBCMS_uncompress\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
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 Apache License 2.0 (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>.

185
openssl-3.4.2/doc/man/man3/CMS_data_create.3
View File

@@ -1,185 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 "CMS_DATA_CREATE 3ossl"
.TH CMS_DATA_CREATE 3ossl "2025-07-01" "3.4.2" "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_data_create_ex, CMS_data_create
\&\- Create CMS Data object
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/cms.h>
\&
\& CMS_ContentInfo *CMS_data_create_ex(BIO *in, unsigned int flags,
\& OSSL_LIB_CTX *libctx, const char *propq);
\& CMS_ContentInfo *CMS_data_create(BIO *in, unsigned int flags);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBCMS_data_create_ex()\fR creates a \fBCMS_ContentInfo\fR structure
with a type \fBNID_pkcs7_data\fR. The data is supplied via the \fIin\fR \s-1BIO.\s0
The library context \fIlibctx\fR and the property query \fIpropq\fR are used when
retrieving algorithms from providers. The \fIflags\fR field supports the
\&\fB\s-1CMS_STREAM\s0\fR flag. Internally \fBCMS_final()\fR is called unless \fB\s-1CMS_STREAM\s0\fR is
specified.
.PP
The \fBCMS_ContentInfo\fR structure can be freed using \fBCMS_ContentInfo_free\fR\|(3).
.PP
\&\fBCMS_data_create()\fR is similar to \fBCMS_data_create_ex()\fR
but uses default values of \s-1NULL\s0 for the library context \fIlibctx\fR and the
property query \fIpropq\fR.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
If the allocation fails, \fBCMS_data_create_ex()\fR and \fBCMS_data_create()\fR
return \s-1NULL\s0 and set an error code that can be obtained by \fBERR_get_error\fR\|(3).
Otherwise they return a pointer to the newly allocated structure.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBERR_get_error\fR\|(3), \fBCMS_final\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
The \fBCMS_data_create_ex()\fR method was added in OpenSSL 3.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2020\-2021 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

251
openssl-3.4.2/doc/man/man3/CMS_decrypt.3
View File

@@ -1,251 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 "CMS_DECRYPT 3ossl"
.TH CMS_DECRYPT 3ossl "2025-07-01" "3.4.2" "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_decrypt, CMS_decrypt_set1_pkey_and_peer,
CMS_decrypt_set1_pkey, CMS_decrypt_set1_password
\&\- 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_set1_pkey_and_peer(CMS_ContentInfo *cms,
\& EVP_PKEY *pk, X509 *cert, X509 *peer);
\& int CMS_decrypt_set1_pkey(CMS_ContentInfo *cms, EVP_PKEY *pk, X509 *cert);
\& int CMS_decrypt_set1_password(CMS_ContentInfo *cms,
\& unsigned char *pass, ossl_ssize_t passlen);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBCMS_decrypt()\fR extracts the decrypted content from a \s-1CMS\s0 EnvelopedData
or AuthEnvelopedData structure.
It uses \fBCMS_decrypt_set1_pkey()\fR to decrypt the content
with the recipient private key \fIpkey\fR if \fIpkey\fR is not \s-1NULL.\s0
In this case, the associated certificate is recommended to provide in \fIcert\fR \-
see the \s-1NOTES\s0 below.
\&\fIout\fR is a \s-1BIO\s0 to write the content to and
\&\fIflags\fR is an optional set of flags.
If \fIpkey\fR is \s-1NULL\s0 the function assumes that decryption was already done
(e.g., using \fBCMS_decrypt_set1_pkey()\fR or \fBCMS_decrypt_set1_password()\fR) and just
provides the content unless \fIcert\fR, \fIdcont\fR, and \fIout\fR are \s-1NULL\s0 as well.
The \fIdcont\fR parameter is used in the rare case where the encrypted content
is detached. It will normally be set to \s-1NULL.\s0
.PP
\&\fBCMS_decrypt_set1_pkey_and_peer()\fR decrypts the CMS_ContentInfo structure \fIcms\fR
using the private key \fIpkey\fR, the corresponding certificate \fIcert\fR, which is
recommended but may be \s-1NULL,\s0 and the (optional) originator certificate \fIpeer\fR.
On success, it also records in \fIcms\fR the decryption key \fIpkey\fR, and then
should be followed by \f(CW\*(C`CMS_decrypt(cms, NULL, NULL, dcont, out, flags)\*(C'\fR.
This call deallocates any decryption key stored in \fIcms\fR.
.PP
\&\fBCMS_decrypt_set1_pkey()\fR is the same as
\&\fBCMS_decrypt_set1_pkey_and_peer()\fR with \fIpeer\fR being \s-1NULL.\s0
.PP
\&\fBCMS_decrypt_set1_password()\fR decrypts the CMS_ContentInfo structure \fIcms\fR
using the secret \fIpass\fR of length \fIpasslen\fR.
On success, it also records in \fIcms\fR the decryption key used, and then
should be followed by \f(CW\*(C`CMS_decrypt(cms, NULL, NULL, dcont, out, flags)\*(C'\fR.
This call deallocates any decryption key stored in \fIcms\fR.
.SH "NOTES"
.IX Header "NOTES"
Although the recipients certificate is not needed to decrypt the data it is
needed to locate the appropriate (of possible several) recipients in the \s-1CMS\s0
structure.
.PP
If \fIcert\fR is set to \s-1NULL\s0 all possible recipients are tried. This case however
is problematic. To thwart the \s-1MMA\s0 attack (Bleichenbacher's attack on
\&\s-1PKCS\s0 #1 v1.5 \s-1RSA\s0 padding) all recipients are tried whether they succeed or
not. If no recipient succeeds then a random symmetric key is used to decrypt
the content: this will typically output garbage and may (but is not guaranteed
to) ultimately return a padding error only. If \fBCMS_decrypt()\fR just returned an
error when all recipient encrypted keys failed to decrypt an attacker could
use this in a timing attack. If the special flag \fB\s-1CMS_DEBUG_DECRYPT\s0\fR is set
then the above behaviour is modified and an error \fBis\fR returned if no
recipient encrypted key can be decrypted \fBwithout\fR generating a random
content encryption key. Applications should use this flag with
\&\fBextreme caution\fR especially in automated gateways as it can leave them
open to attack.
.PP
It is possible to determine the correct recipient key by other means (for
example looking them up in a database) and setting them in the \s-1CMS\s0 structure
in advance using the \s-1CMS\s0 utility functions such as \fBCMS_set1_pkey()\fR,
or use \fBCMS_decrypt_set1_password()\fR if the recipient has a symmetric key.
In these cases both \fIcert\fR and \fIpkey\fR should be set to \s-1NULL.\s0
.PP
To process KEKRecipientInfo types \fBCMS_set1_key()\fR or \fBCMS_RecipientInfo_set0_key()\fR
and \fBCMS_RecipientInfo_decrypt()\fR should be called before \fBCMS_decrypt()\fR and
\&\fIcert\fR and \fIpkey\fR set to \s-1NULL.\s0
.PP
The following flags can be passed in the \fIflags\fR parameter.
.PP
If the \fB\s-1CMS_TEXT\s0\fR flag is set \s-1MIME\s0 headers for type \f(CW\*(C`text/plain\*(C'\fR are deleted
from the content. If the content is not of type \f(CW\*(C`text/plain\*(C'\fR then an error is
returned.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBCMS_decrypt()\fR, \fBCMS_decrypt_set1_pkey_and_peer()\fR,
\&\fBCMS_decrypt_set1_pkey()\fR, and \fBCMS_decrypt_set1_password()\fR
return either 1 for success or 0 for failure.
The error can be obtained from \fBERR_get_error\fR\|(3).
.SH "BUGS"
.IX Header "BUGS"
The \fBset1_\fR part of these function names is misleading
and should better read: \fBwith_\fR.
.PP
The lack of single pass processing and the need to hold all data in memory as
mentioned in \fBCMS_verify()\fR also applies to \fBCMS_decrypt()\fR.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBERR_get_error\fR\|(3), \fBCMS_encrypt\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fBCMS_decrypt_set1_pkey_and_peer()\fR and \fBCMS_decrypt_set1_password()\fR
were added in OpenSSL 3.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2008\-2020 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

188
openssl-3.4.2/doc/man/man3/CMS_digest_create.3
View File

@@ -1,188 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 "CMS_DIGEST_CREATE 3ossl"
.TH CMS_DIGEST_CREATE 3ossl "2025-07-01" "3.4.2" "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_digest_create_ex, CMS_digest_create
\&\- Create CMS DigestedData object
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/cms.h>
\&
\& CMS_ContentInfo *CMS_digest_create_ex(BIO *in, const EVP_MD *md,
\& unsigned int flags, OSSL_LIB_CTX *ctx,
\& const char *propq);
\&
\& CMS_ContentInfo *CMS_digest_create(BIO *in, const EVP_MD *md,
\& unsigned int flags);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBCMS_digest_create_ex()\fR creates a \fBCMS_ContentInfo\fR structure
with a type \fBNID_pkcs7_digest\fR. The data supplied via the \fIin\fR \s-1BIO\s0 is digested
using \fImd\fR. The library context \fIlibctx\fR and the property query \fIpropq\fR are
used when retrieving algorithms from providers.
The \fIflags\fR field supports the \fB\s-1CMS_DETACHED\s0\fR and \fB\s-1CMS_STREAM\s0\fR flags,
Internally \fBCMS_final()\fR is called unless \fB\s-1CMS_STREAM\s0\fR is specified.
.PP
The \fBCMS_ContentInfo\fR structure can be freed using \fBCMS_ContentInfo_free\fR\|(3).
.PP
\&\fBCMS_digest_create()\fR is similar to \fBCMS_digest_create_ex()\fR
but uses default values of \s-1NULL\s0 for the library context \fIlibctx\fR and the
property query \fIpropq\fR.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
If the allocation fails, \fBCMS_digest_create_ex()\fR and \fBCMS_digest_create()\fR
return \s-1NULL\s0 and set an error code that can be obtained by \fBERR_get_error\fR\|(3).
Otherwise they return a pointer to the newly allocated structure.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBERR_get_error\fR\|(3), \fBCMS_final\fR\|(3)>
.SH "HISTORY"
.IX Header "HISTORY"
The \fBCMS_digest_create_ex()\fR method was added in OpenSSL 3.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2020\-2021 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

245
openssl-3.4.2/doc/man/man3/CMS_encrypt.3
View File

@@ -1,245 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 "CMS_ENCRYPT 3ossl"
.TH CMS_ENCRYPT 3ossl "2025-07-01" "3.4.2" "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_encrypt_ex, CMS_encrypt \- create a CMS envelopedData structure
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/cms.h>
\&
\& CMS_ContentInfo *CMS_encrypt_ex(STACK_OF(X509) *certs, BIO *in,
\& const EVP_CIPHER *cipher, unsigned int flags,
\& OSSL_LIB_CTX *libctx, const char *propq);
\& CMS_ContentInfo *CMS_encrypt(STACK_OF(X509) *certs, BIO *in,
\& const EVP_CIPHER *cipher, unsigned int flags);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBCMS_encrypt_ex()\fR creates and returns a \s-1CMS\s0 EnvelopedData or
AuthEnvelopedData structure. \fIcerts\fR is a list of recipient certificates.
\&\fIin\fR is the content to be encrypted. \fIcipher\fR is the symmetric cipher to use.
\&\fIflags\fR is an optional set of flags. The library context \fIlibctx\fR and the
property query \fIpropq\fR are used internally when retrieving algorithms from
providers.
.PP
Only certificates carrying \s-1RSA,\s0 Diffie-Hellman or \s-1EC\s0 keys are supported by this
function.
.PP
\&\fBEVP_des_ede3_cbc()\fR (triple \s-1DES\s0) is the algorithm of choice for S/MIME use
because most clients will support it.
.PP
The algorithm passed in the \fBcipher\fR parameter must support \s-1ASN1\s0 encoding of
its parameters. If the cipher mode is \s-1GCM,\s0 then an AuthEnvelopedData structure
containing \s-1MAC\s0 is used. Otherwise an EnvelopedData structure is used. Currently
the \s-1AES\s0 variants with \s-1GCM\s0 mode are the only supported \s-1AEAD\s0 algorithms.
.PP
Many browsers implement a \*(L"sign and encrypt\*(R" option which is simply an S/MIME
envelopedData containing an S/MIME signed message. This can be readily produced
by storing the S/MIME signed message in a memory \s-1BIO\s0 and passing it to
\&\fBCMS_encrypt()\fR.
.PP
The following flags can be passed in the \fBflags\fR parameter.
.PP
If the \fB\s-1CMS_TEXT\s0\fR flag is set \s-1MIME\s0 headers for type \fBtext/plain\fR are
prepended to the data.
.PP
Normally the supplied content is translated into \s-1MIME\s0 canonical format (as
required by the S/MIME specifications) if \fB\s-1CMS_BINARY\s0\fR is set no translation
occurs. This option should be used if the supplied data is in binary format
otherwise the translation will corrupt it. If \fB\s-1CMS_BINARY\s0\fR is set then
\&\fB\s-1CMS_TEXT\s0\fR is ignored.
.PP
OpenSSL will by default identify recipient certificates using issuer name
and serial number. If \fB\s-1CMS_USE_KEYID\s0\fR is set it will use the subject key
identifier value instead. An error occurs if all recipient certificates do not
have a subject key identifier extension.
.PP
If the \fB\s-1CMS_STREAM\s0\fR flag is set a partial \fBCMS_ContentInfo\fR structure is
returned suitable for streaming I/O: no data is read from the \s-1BIO\s0 \fBin\fR.
.PP
If the \fB\s-1CMS_PARTIAL\s0\fR flag is set a partial \fBCMS_ContentInfo\fR structure is
returned to which additional recipients and attributes can be added before
finalization.
.PP
The data being encrypted is included in the CMS_ContentInfo structure, unless
\&\fB\s-1CMS_DETACHED\s0\fR is set in which case it is omitted. This is rarely used in
practice and is not supported by \fBSMIME_write_CMS()\fR.
.PP
If the flag \fB\s-1CMS_STREAM\s0\fR is set the returned \fBCMS_ContentInfo\fR structure is
\&\fBnot\fR complete and outputting its contents via a function that does not
properly finalize the \fBCMS_ContentInfo\fR structure will give unpredictable
results.
.PP
Several functions including \fBSMIME_write_CMS()\fR, \fBi2d_CMS_bio_stream()\fR,
\&\fBPEM_write_bio_CMS_stream()\fR finalize the structure. Alternatively finalization
can be performed by obtaining the streaming \s-1ASN1\s0 \fB\s-1BIO\s0\fR directly using
\&\fBBIO_new_CMS()\fR.
.PP
The recipients specified in \fBcerts\fR use a \s-1CMS\s0 KeyTransRecipientInfo info
structure. KEKRecipientInfo is also supported using the flag \fB\s-1CMS_PARTIAL\s0\fR
and \fBCMS_add0_recipient_key()\fR.
.PP
The parameter \fBcerts\fR may be \s-1NULL\s0 if \fB\s-1CMS_PARTIAL\s0\fR is set and recipients
added later using \fBCMS_add1_recipient_cert()\fR or \fBCMS_add0_recipient_key()\fR.
.PP
\&\fBCMS_encrypt()\fR is similar to \fBCMS_encrypt_ex()\fR but uses default values
of \s-1NULL\s0 for the library context \fIlibctx\fR and the property query \fIpropq\fR.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBCMS_encrypt_ex()\fR and \fBCMS_encrypt()\fR return either a CMS_ContentInfo
structure or \s-1NULL\s0 if an error occurred. The error can be obtained from
\&\fBERR_get_error\fR\|(3).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBERR_get_error\fR\|(3), \fBCMS_decrypt\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
The function \fBCMS_encrypt_ex()\fR was added in OpenSSL 3.0.
.PP
The \fB\s-1CMS_STREAM\s0\fR flag was first supported in OpenSSL 1.0.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2008\-2020 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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
openssl-3.4.2/doc/man/man3/CMS_final.3
View File

@@ -1,191 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 "CMS_FINAL 3ossl"
.TH CMS_FINAL 3ossl "2025-07-01" "3.4.2" "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_final, CMS_final_digest \- finalise a CMS_ContentInfo structure
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/cms.h>
\&
\& int CMS_final(CMS_ContentInfo *cms, BIO *data, BIO *dcont, unsigned int flags);
\& int CMS_final_digest(CMS_ContentInfo *cms, const unsigned char *md,
\& unsigned int mdlen, BIO *dcont, unsigned int flags);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBCMS_final()\fR finalises the structure \fBcms\fR. Its 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
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
.PP
\&\fBCMS_final_digest()\fR finalises the structure \fBcms\fR using a pre-computed digest,
rather than computing the digest from the original data.
.SH "NOTES"
.IX Header "NOTES"
These functions will normally be called when the \fB\s-1CMS_PARTIAL\s0\fR flag is used. It
should only be used when streaming is not performed because the streaming
I/O functions perform finalisation operations internally.
.PP
To sign a pre-computed digest, \fBCMS_sign\fR\|(3) or \fBCMS_sign_ex()\fR is called
with the \fBdata\fR parameter set to \s-1NULL\s0 before the \s-1CMS\s0 structure is finalised
with the digest provided to \fBCMS_final_digest()\fR in binary form.
When signing a pre-computed digest, the security relies on the digest and its
computation from the original message being trusted.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBCMS_final()\fR and \fBCMS_final_digest()\fR return 1 for success or 0 for failure.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBERR_get_error\fR\|(3), \fBCMS_sign\fR\|(3),
\&\fBCMS_encrypt\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fBCMS_final_digest()\fR was added in OpenSSL 3.2.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2008\-2022 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

285
openssl-3.4.2/doc/man/man3/CMS_get0_RecipientInfos.3
View File

@@ -1,285 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 "CMS_GET0_RECIPIENTINFOS 3ossl"
.TH CMS_GET0_RECIPIENTINFOS 3ossl "2025-07-01" "3.4.2" "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_kari_set0_pkey_and_peer,
CMS_RecipientInfo_kari_set0_pkey,
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
\& #include <openssl/cms.h>
\&
\& STACK_OF(CMS_RecipientInfo) *CMS_get0_RecipientInfos(CMS_ContentInfo *cms);
\& int CMS_RecipientInfo_type(CMS_RecipientInfo *ri);
\&
\& int CMS_RecipientInfo_ktri_get0_signer_id(CMS_RecipientInfo *ri,
\& ASN1_OCTET_STRING **keyid,
\& X509_NAME **issuer,
\& ASN1_INTEGER **sno);
\& int CMS_RecipientInfo_ktri_cert_cmp(CMS_RecipientInfo *ri, X509 *cert);
\& int CMS_RecipientInfo_set0_pkey(CMS_RecipientInfo *ri, EVP_PKEY *pkey);
\& int CMS_RecipientInfo_kari_set0_pkey_and_peer(CMS_RecipientInfo *ri,
\& EVP_PKEY *pk, X509 *peer);
\& int CMS_RecipientInfo_kari_set0_pkey(CMS_RecipientInfo *ri, EVP_PKEY *pk);
\& 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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The function \fBCMS_get0_RecipientInfos()\fR returns all the CMS_RecipientInfo
structures associated with a \s-1CMS\s0 EnvelopedData structure.
.PP
\&\fBCMS_RecipientInfo_type()\fR returns the type of CMS_RecipientInfo structure \fBri\fR.
It will currently return \s-1CMS_RECIPINFO_TRANS, CMS_RECIPINFO_AGREE,
CMS_RECIPINFO_KEK, CMS_RECIPINFO_PASS,\s0 or \s-1CMS_RECIPINFO_OTHER.\s0
.PP
\&\fBCMS_RecipientInfo_ktri_get0_signer_id()\fR retrieves the certificate recipient
identifier associated with a specific CMS_RecipientInfo structure \fBri\fR, which
must be of type \s-1CMS_RECIPINFO_TRANS.\s0 Either the keyidentifier will be set in
\&\fBkeyid\fR or \fBboth\fR issuer name and serial number in \fBissuer\fR and \fBsno\fR.
.PP
\&\fBCMS_RecipientInfo_ktri_cert_cmp()\fR compares the certificate \fBcert\fR against the
CMS_RecipientInfo structure \fBri\fR, which must be of type \s-1CMS_RECIPINFO_TRANS.\s0
It returns zero if the comparison is successful and non zero if not.
.PP
\&\fBCMS_RecipientInfo_set0_pkey()\fR associates the private key \fBpkey\fR with
the CMS_RecipientInfo structure \fBri\fR, which must be of type
\&\s-1CMS_RECIPINFO_TRANS.\s0
.PP
\&\fBCMS_RecipientInfo_kari_set0_pkey_and_peer()\fR associates the private key \fBpkey\fR
and peer certificate \fBpeer\fR with the CMS_RecipientInfo structure \fBri\fR, which
must be of type \s-1CMS_RECIPINFO_AGREE.\s0
.PP
\&\fBCMS_RecipientInfo_kari_set0_pkey()\fR associates the private key \fBpkey\fR with the
CMS_RecipientInfo structure \fBri\fR, which must be of type \s-1CMS_RECIPINFO_AGREE.\s0
.PP
\&\fBCMS_RecipientInfo_kekri_get0_id()\fR retrieves the key information from the
CMS_RecipientInfo structure \fBri\fR which must be of type \s-1CMS_RECIPINFO_KEK.\s0 Any
of the remaining parameters can be \s-1NULL\s0 if the application is not interested in
the value of a field. Where a field is optional and absent \s-1NULL\s0 will be written
to the corresponding parameter. The keyEncryptionAlgorithm field is written to
\&\fBpalg\fR, the \fBkeyIdentifier\fR field is written to \fBpid\fR, the \fBdate\fR field if
present is written to \fBpdate\fR, if the \fBother\fR field is present the components
\&\fBkeyAttrId\fR and \fBkeyAttr\fR are written to parameters \fBpotherid\fR and
\&\fBpothertype\fR.
.PP
\&\fBCMS_RecipientInfo_kekri_id_cmp()\fR compares the \s-1ID\s0 in the \fBid\fR and \fBidlen\fR
parameters against the \fBkeyIdentifier\fR CMS_RecipientInfo structure \fBri\fR,
which must be of type \s-1CMS_RECIPINFO_KEK.\s0 It returns zero if the comparison is
successful and non zero if not.
.PP
\&\fBCMS_RecipientInfo_set0_key()\fR associates the symmetric key \fBkey\fR of length
\&\fBkeylen\fR with the CMS_RecipientInfo structure \fBri\fR, which must be of type
\&\s-1CMS_RECIPINFO_KEK.\s0
.PP
\&\fBCMS_RecipientInfo_decrypt()\fR attempts to decrypt CMS_RecipientInfo structure
\&\fBri\fR in structure \fBcms\fR. A key must have been associated with the structure
first.
.PP
\&\fBCMS_RecipientInfo_encrypt()\fR attempts to encrypt CMS_RecipientInfo structure
\&\fBri\fR in structure \fBcms\fR. A key must have been associated with the structure
first and the content encryption key must be available: for example by a
previous call to \fBCMS_RecipientInfo_decrypt()\fR.
.SH "NOTES"
.IX Header "NOTES"
The main purpose of these functions is to enable an application to lookup
recipient keys using any appropriate technique when the simpler method
of \fBCMS_decrypt()\fR is not appropriate.
.PP
In typical usage and application will retrieve all CMS_RecipientInfo structures
using \fBCMS_get0_RecipientInfos()\fR and check the type of each using
\&\fBCMS_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
\&\fBCMS_RecipientInfo_decrypt()\fR called. If successful \fBCMS_decrypt()\fR can be called
with a \s-1NULL\s0 key to decrypt the enveloped content.
.PP
The \fBCMS_RecipientInfo_encrypt()\fR can be used to add a new recipient to an
existing enveloped data structure. Typically an application will first decrypt
an appropriate CMS_RecipientInfo structure to make the content encrypt key
available, it will then add a new recipient using a function such as
\&\fBCMS_add1_recipient_cert()\fR and finally encrypt the content encryption key
using \fBCMS_RecipientInfo_encrypt()\fR.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBCMS_get0_RecipientInfos()\fR returns all CMS_RecipientInfo structures, or \s-1NULL\s0 if
an error occurs.
.PP
\&\fBCMS_RecipientInfo_ktri_get0_signer_id()\fR, \fBCMS_RecipientInfo_set0_pkey()\fR,
\&\fBCMS_RecipientInfo_kekri_get0_id()\fR, \fBCMS_RecipientInfo_set0_key()\fR and
\&\fBCMS_RecipientInfo_decrypt()\fR return 1 for success or 0 if an error occurs.
\&\fBCMS_RecipientInfo_encrypt()\fR return 1 for success or 0 if an error occurs.
.PP
\&\fBCMS_RecipientInfo_ktri_cert_cmp()\fR and \fBCMS_RecipientInfo_kekri_cmp()\fR return 0
for a successful comparison and non zero otherwise.
.PP
Any error can be obtained from \fBERR_get_error\fR\|(3).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBERR_get_error\fR\|(3), \fBCMS_decrypt\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fBCMS_RecipientInfo_kari_set0_pkey_and_peer\fR and \fBCMS_RecipientInfo_kari_set0_pkey\fR
were added in OpenSSL 3.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2008\-2020 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

221
openssl-3.4.2/doc/man/man3/CMS_get0_SignerInfos.3
View File

@@ -1,221 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 "CMS_GET0_SIGNERINFOS 3ossl"
.TH CMS_GET0_SIGNERINFOS 3ossl "2025-07-01" "3.4.2" "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_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
\& #include <openssl/cms.h>
\&
\& STACK_OF(CMS_SignerInfo) *CMS_get0_SignerInfos(CMS_ContentInfo *cms);
\&
\& int CMS_SignerInfo_get0_signer_id(CMS_SignerInfo *si, ASN1_OCTET_STRING **keyid,
\& X509_NAME **issuer, ASN1_INTEGER **sno);
\& ASN1_OCTET_STRING *CMS_SignerInfo_get0_signature(CMS_SignerInfo *si);
\& int CMS_SignerInfo_cert_cmp(CMS_SignerInfo *si, X509 *cert);
\& void CMS_SignerInfo_set1_signer_cert(CMS_SignerInfo *si, X509 *signer);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The function \fBCMS_get0_SignerInfos()\fR returns all the CMS_SignerInfo structures
associated with a \s-1CMS\s0 signedData structure.
.PP
\&\fBCMS_SignerInfo_get0_signer_id()\fR retrieves the certificate signer identifier
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
\&\fBCMS_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.
.PP
\&\fBCMS_SignerInfo_cert_cmp()\fR compares the certificate \fBcert\fR against the signer
identifier \fBsi\fR. It returns zero if the comparison is successful and non zero
if not.
.PP
\&\fBCMS_SignerInfo_set1_signer_cert()\fR sets the signers certificate of \fBsi\fR to
\&\fBsigner\fR.
.SH "NOTES"
.IX Header "NOTES"
The main purpose of these functions is to enable an application to lookup
signers certificates using any appropriate technique when the simpler method
of \fBCMS_verify()\fR is not appropriate.
.PP
In typical usage and application will retrieve all CMS_SignerInfo structures
using \fBCMS_get0_SignerInfo()\fR and retrieve the identifier information using
\&\s-1CMS.\s0 It will then obtain the signer certificate by some unspecified means
(or return and error if it cannot be found) and set it using
\&\fBCMS_SignerInfo_set1_signer_cert()\fR.
.PP
Once all signer certificates have been set \fBCMS_verify()\fR can be used.
.PP
Although \fBCMS_get0_SignerInfos()\fR can return \s-1NULL\s0 if an error occurs \fBor\fR if
there are no signers this is not a problem in practice because the only
error which can occur is if the \fBcms\fR structure is not of type signedData
due to application error.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBCMS_get0_SignerInfos()\fR returns all CMS_SignerInfo structures, or \s-1NULL\s0 there
are no signers or an error occurs.
.PP
\&\fBCMS_SignerInfo_get0_signer_id()\fR returns 1 for success and 0 for failure.
.PP
\&\fBCMS_SignerInfo_cert_cmp()\fR returns 0 for a successful comparison and non
zero otherwise.
.PP
\&\fBCMS_SignerInfo_set1_signer_cert()\fR does not return a value.
.PP
Any error can be obtained from \fBERR_get_error\fR\|(3)
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBERR_get_error\fR\|(3), \fBCMS_verify\fR\|(3)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2008\-2018 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

218
openssl-3.4.2/doc/man/man3/CMS_get0_type.3
View File

@@ -1,218 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 "CMS_GET0_TYPE 3ossl"
.TH CMS_GET0_TYPE 3ossl "2025-07-01" "3.4.2" "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_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(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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBCMS_get0_type()\fR returns the content type of a CMS_ContentInfo structure as
an \s-1ASN1_OBJECT\s0 pointer. An application can then decide how to process the
CMS_ContentInfo structure based on this value.
.PP
\&\fBCMS_set1_eContentType()\fR sets the embedded content type of a CMS_ContentInfo
structure. It should be called with \s-1CMS\s0 functions (such as \fBCMS_sign\fR\|(3),
\&\fBCMS_encrypt\fR\|(3))
with the \fB\s-1CMS_PARTIAL\s0\fR
flag and \fBbefore\fR the structure is finalised, otherwise the results are
undefined.
.PP
\&\s-1ASN1_OBJECT\s0 *\fBCMS_get0_eContentType()\fR returns a pointer to the embedded
content type.
.PP
\&\fBCMS_get0_content()\fR returns a pointer to the \fB\s-1ASN1_OCTET_STRING\s0\fR pointer
containing the embedded content.
.SH "NOTES"
.IX Header "NOTES"
As the \fB0\fR implies \fBCMS_get0_type()\fR, \fBCMS_get0_eContentType()\fR and
\&\fBCMS_get0_content()\fR return internal pointers which should \fBnot\fR be freed up.
\&\fBCMS_set1_eContentType()\fR copies the supplied \s-1OID\s0 and it \fBshould\fR be freed up
after use.
.PP
The \fB\s-1ASN1_OBJECT\s0\fR values returned can be converted to an integer \fB\s-1NID\s0\fR value
using \fBOBJ_obj2nid()\fR. For the currently supported content types the following
values are returned:
.PP
.Vb 6
\& NID_pkcs7_data
\& NID_pkcs7_signed
\& NID_pkcs7_digest
\& NID_id_smime_ct_compressedData:
\& NID_pkcs7_encrypted
\& NID_pkcs7_enveloped
.Ve
.PP
The return value of \fBCMS_get0_content()\fR is a pointer to the \fB\s-1ASN1_OCTET_STRING\s0\fR
content pointer. That means that for example:
.PP
.Vb 1
\& ASN1_OCTET_STRING **pconf = CMS_get0_content(cms);
.Ve
.PP
\&\fB*pconf\fR could be \s-1NULL\s0 if there is no embedded content. Applications can
access, modify or create the embedded content in a \fBCMS_ContentInfo\fR structure
using this function. Applications usually will not need to modify the
embedded content as it is normally set by higher level functions.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBCMS_get0_type()\fR and \fBCMS_get0_eContentType()\fR return an \s-1ASN1_OBJECT\s0 structure.
.PP
\&\fBCMS_set1_eContentType()\fR returns 1 for success or 0 if an error occurred. The
error can be obtained from \fBERR_get_error\fR\|(3).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBERR_get_error\fR\|(3)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2008\-2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

222
openssl-3.4.2/doc/man/man3/CMS_get1_ReceiptRequest.3
View File

@@ -1,222 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 "CMS_GET1_RECEIPTREQUEST 3ossl"
.TH CMS_GET1_RECEIPTREQUEST 3ossl "2025-07-01" "3.4.2" "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_ReceiptRequest_create0_ex, 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_ex(
\& unsigned char *id, int idlen, int allorfirst,
\& STACK_OF(GENERAL_NAMES) *receiptList, STACK_OF(GENERAL_NAMES) *receiptsTo,
\& OSSL_LIB_CTX *libctx);
\& 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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBCMS_ReceiptRequest_create0_ex()\fR creates a signed receipt request
structure. The \fBsignedContentIdentifier\fR field is set using \fIid\fR and \fIidlen\fR,
or it is set to 32 bytes of pseudo random data if \fIid\fR is \s-1NULL.\s0
If \fIreceiptList\fR is \s-1NULL\s0 the allOrFirstTier option in \fIreceiptsFrom\fR is used
and set to the value of the \fIallorfirst\fR parameter. If \fIreceiptList\fR is not
\&\s-1NULL\s0 the \fIreceiptList\fR option in \fIreceiptsFrom\fR is used. The \fIreceiptsTo\fR
parameter specifies the \fIreceiptsTo\fR field value. The library context \fIlibctx\fR
is used to find the public random generator.
.PP
\&\fBCMS_ReceiptRequest_create0()\fR is similar to
\&\fBCMS_ReceiptRequest_create0_ex()\fR but uses default values of \s-1NULL\s0 for the
library context \fIlibctx\fR.
.PP
The \fBCMS_add1_ReceiptRequest()\fR function adds a signed receipt request \fBrr\fR
to SignerInfo structure \fBsi\fR.
.PP
int \fBCMS_get1_ReceiptRequest()\fR looks for a signed receipt request in \fBsi\fR, if
any is found it is decoded and written to \fBprr\fR.
.PP
\&\fBCMS_ReceiptRequest_get0_values()\fR retrieves the values of a receipt request.
The signedContentIdentifier is copied to \fBpcid\fR. If the \fBallOrFirstTier\fR
option of \fBreceiptsFrom\fR is used its value is copied to \fBpallorfirst\fR
otherwise the \fBreceiptList\fR field is copied to \fBplist\fR. The \fBreceiptsTo\fR
parameter is copied to \fBprto\fR.
.SH "NOTES"
.IX Header "NOTES"
For more details of the meaning of the fields see \s-1RFC2634.\s0
.PP
The contents of a signed receipt should only be considered meaningful if the
corresponding CMS_ContentInfo structure can be successfully verified using
\&\fBCMS_verify()\fR.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBCMS_ReceiptRequest_create0_ex()\fR and \fBCMS_ReceiptRequest_create0()\fR return
a signed receipt request structure or \s-1NULL\s0 if an error occurred.
.PP
\&\fBCMS_add1_ReceiptRequest()\fR returns 1 for success or 0 if an error occurred.
.PP
\&\fBCMS_get1_ReceiptRequest()\fR returns 1 is a signed receipt request is found and
decoded. It returns 0 if a signed receipt request is not present and \-1 if
it is present but malformed.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBERR_get_error\fR\|(3), \fBCMS_sign\fR\|(3),
\&\fBCMS_sign_receipt\fR\|(3), \fBCMS_verify\fR\|(3)
\&\fBCMS_verify_receipt\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
The function \fBCMS_ReceiptRequest_create0_ex()\fR was added in OpenSSL 3.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2008\-2021 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

274
openssl-3.4.2/doc/man/man3/CMS_sign.3
View File

@@ -1,274 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 "CMS_SIGN 3ossl"
.TH CMS_SIGN 3ossl "2025-07-01" "3.4.2" "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_sign, CMS_sign_ex \- create a CMS SignedData structure
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/cms.h>
\&
\& CMS_ContentInfo *CMS_sign_ex(X509 *signcert, EVP_PKEY *pkey,
\& STACK_OF(X509) *certs, BIO *data,
\& unsigned int flags, OSSL_LIB_CTX *ctx,
\& const char *propq);
\& CMS_ContentInfo *CMS_sign(X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs,
\& BIO *data, unsigned int flags);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBCMS_sign_ex()\fR creates and returns a \s-1CMS\s0 SignedData structure.
\&\fIsigncert\fR is the certificate to sign with, \fIpkey\fR is the corresponding
private key. \fIcerts\fR is an optional additional set of certificates to include
in the \s-1CMS\s0 structure (for example any intermediate CAs in the chain). The
library context \fIlibctx\fR and the property query \fIpropq\fR are used when
retrieving algorithms from providers. Any or all of these parameters can be
\&\fB\s-1NULL\s0\fR, see \fB\s-1NOTES\s0\fR below.
.PP
The data to be signed is read from \s-1BIO\s0 \fBdata\fR.
.PP
\&\fBflags\fR is an optional set of flags.
.PP
\&\fBCMS_sign()\fR is similar to \fBCMS_sign_ex()\fR but uses default values of \s-1NULL\s0
for the library context \fIlibctx\fR and the property query \fIpropq\fR.
.SH "NOTES"
.IX Header "NOTES"
Any of the following flags (ored together) can be passed in the \fBflags\fR
parameter.
.PP
Many S/MIME clients expect the signed content to include valid \s-1MIME\s0 headers. If
the \fB\s-1CMS_TEXT\s0\fR flag is set \s-1MIME\s0 headers for type \fBtext/plain\fR are prepended
to the data.
.PP
If \fB\s-1CMS_NOCERTS\s0\fR is set the signer's certificate will not be included in the
CMS_ContentInfo structure, the signer's certificate must still be supplied in
the \fBsigncert\fR parameter though. This can reduce the size of the signature if
the signers certificate can be obtained by other means: for example a
previously signed message.
.PP
The data being signed is included in the CMS_ContentInfo structure, unless
\&\fB\s-1CMS_DETACHED\s0\fR is set in which case it is omitted. This is used for
CMS_ContentInfo detached signatures which are used in S/MIME plaintext signed
messages for example.
.PP
Normally the supplied content is translated into \s-1MIME\s0 canonical format (as
required by the S/MIME specifications) if \fB\s-1CMS_BINARY\s0\fR is set no translation
occurs. This option should be used if the supplied data is in binary format
otherwise the translation will corrupt it.
.PP
The SignedData structure includes several \s-1CMS\s0 signedAttributes including the
signing time, the \s-1CMS\s0 content type and the supported list of ciphers in an
SMIMECapabilities attribute. If \fB\s-1CMS_NOATTR\s0\fR is set then no signedAttributes
will be used. If \fB\s-1CMS_NOSMIMECAP\s0\fR is set then just the SMIMECapabilities are
omitted.
.PP
If present the SMIMECapabilities attribute indicates support for the following
algorithms in preference order: 256 bit \s-1AES,\s0 Gost R3411\-94, Gost 28147\-89, 192
bit \s-1AES, 128\s0 bit \s-1AES,\s0 triple \s-1DES, 128\s0 bit \s-1RC2, 64\s0 bit \s-1RC2, DES\s0 and 40 bit \s-1RC2.\s0
If any of these algorithms is not available then it will not be included:
for example the \s-1GOST\s0 algorithms will not be included if the \s-1GOST ENGINE\s0 is
not loaded.
.PP
OpenSSL will by default identify signing certificates using issuer name
and serial number. If \fB\s-1CMS_USE_KEYID\s0\fR is set it will use the subject key
identifier value instead. An error occurs if the signing certificate does not
have a subject key identifier extension.
.PP
If the flags \fB\s-1CMS_STREAM\s0\fR is set then the returned \fBCMS_ContentInfo\fR
structure is just initialized ready to perform the signing operation. The
signing is however \fBnot\fR performed and the data to be signed is not read from
the \fBdata\fR parameter. Signing is deferred until after the data has been
written. In this way data can be signed in a single pass.
.PP
If the \fB\s-1CMS_PARTIAL\s0\fR flag is set a partial \fBCMS_ContentInfo\fR structure is
output to which additional signers and capabilities can be added before
finalization.
.PP
If the flag \fB\s-1CMS_STREAM\s0\fR is set the returned \fBCMS_ContentInfo\fR structure is
\&\fBnot\fR complete and outputting its contents via a function that does not
properly finalize the \fBCMS_ContentInfo\fR structure will give unpredictable
results.
.PP
Several functions including \fBSMIME_write_CMS()\fR, \fBi2d_CMS_bio_stream()\fR,
\&\fBPEM_write_bio_CMS_stream()\fR finalize the structure. Alternatively finalization
can be performed by obtaining the streaming \s-1ASN1\s0 \fB\s-1BIO\s0\fR directly using
\&\fBBIO_new_CMS()\fR.
.PP
If a signer is specified it will use the default digest for the signing
algorithm. This is \fB\s-1SHA256\s0\fR for both \s-1RSA\s0 and \s-1DSA\s0 keys.
.PP
If \fBsigncert\fR and \fBpkey\fR are \s-1NULL\s0 then a certificates only \s-1CMS\s0 structure is
output.
.PP
The function \fBCMS_sign()\fR is a basic \s-1CMS\s0 signing function whose output will be
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 \fBCMS_add1_signer()\fR, non default digests can be used and custom
attributes added. \fBCMS_final()\fR must then be called to finalize the
structure if streaming is not enabled.
.SH "BUGS"
.IX Header "BUGS"
Some attributes such as counter signatures are not supported.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBCMS_sign_ex()\fR and \fBCMS_sign()\fR return either a valid CMS_ContentInfo
structure or \s-1NULL\s0 if an error occurred. The error can be obtained from
\&\fBERR_get_error\fR\|(3).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBERR_get_error\fR\|(3), \fBCMS_verify\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
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.
.PP
The \fBCMS_sign_ex()\fR method was added in OpenSSL 3.0.
.PP
Since OpenSSL 3.2, \fBCMS_sign_ex()\fR and \fBCMS_sign()\fR ignore any duplicate
certificates in their \fIcerts\fR argument and no longer throw an error for them.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2008\-2025 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

183
openssl-3.4.2/doc/man/man3/CMS_sign_receipt.3
View File

@@ -1,183 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 "CMS_SIGN_RECEIPT 3ossl"
.TH CMS_SIGN_RECEIPT 3ossl "2025-07-01" "3.4.2" "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_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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBCMS_sign_receipt()\fR creates and returns a \s-1CMS\s0 signed receipt structure. \fBsi\fR is
the \fBCMS_SignerInfo\fR structure containing the signed receipt request.
\&\fBsigncert\fR is the certificate to sign with, \fBpkey\fR is the corresponding
private key. \fBcerts\fR is an optional additional set of certificates to include
in the \s-1CMS\s0 structure (for example any intermediate CAs in the chain).
.PP
\&\fBflags\fR is an optional set of flags.
.SH "NOTES"
.IX Header "NOTES"
This functions behaves in a similar way to \fBCMS_sign()\fR except the flag values
\&\fB\s-1CMS_DETACHED\s0\fR, \fB\s-1CMS_BINARY\s0\fR, \fB\s-1CMS_NOATTR\s0\fR, \fB\s-1CMS_TEXT\s0\fR and \fB\s-1CMS_STREAM\s0\fR
are not supported since they do not make sense in the context of signed
receipts.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBCMS_sign_receipt()\fR returns either a valid CMS_ContentInfo structure or \s-1NULL\s0 if
an error occurred. The error can be obtained from \fBERR_get_error\fR\|(3).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBERR_get_error\fR\|(3),
\&\fBCMS_verify_receipt\fR\|(3),
\&\fBCMS_sign\fR\|(3)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2008\-2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

338
openssl-3.4.2/doc/man/man3/CMS_signed_get_attr.3
View File

@@ -1,338 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 "CMS_SIGNED_GET_ATTR 3ossl"
.TH CMS_SIGNED_GET_ATTR 3ossl "2025-07-01" "3.4.2" "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_signed_get_attr_count,
CMS_signed_get_attr_by_NID, CMS_signed_get_attr_by_OBJ, CMS_signed_get_attr,
CMS_signed_delete_attr,
CMS_signed_add1_attr, CMS_signed_add1_attr_by_OBJ,
CMS_signed_add1_attr_by_NID, CMS_signed_add1_attr_by_txt,
CMS_signed_get0_data_by_OBJ,
CMS_unsigned_get_attr_count,
CMS_unsigned_get_attr_by_NID, CMS_unsigned_get_attr_by_OBJ,
CMS_unsigned_get_attr, CMS_unsigned_delete_attr,
CMS_unsigned_add1_attr, CMS_unsigned_add1_attr_by_OBJ,
CMS_unsigned_add1_attr_by_NID, CMS_unsigned_add1_attr_by_txt,
CMS_unsigned_get0_data_by_OBJ
\&\- CMS signed and unsigned attribute functions
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/cms.h>
\&
\& int CMS_signed_get_attr_count(const CMS_SignerInfo *si);
\& int CMS_signed_get_attr_by_NID(const CMS_SignerInfo *si, int nid,
\& int lastpos);
\& int CMS_signed_get_attr_by_OBJ(const CMS_SignerInfo *si, const ASN1_OBJECT *obj,
\& int lastpos);
\& X509_ATTRIBUTE *CMS_signed_get_attr(const CMS_SignerInfo *si, int loc);
\& X509_ATTRIBUTE *CMS_signed_delete_attr(CMS_SignerInfo *si, int loc);
\& int CMS_signed_add1_attr(CMS_SignerInfo *si, X509_ATTRIBUTE *attr);
\& int CMS_signed_add1_attr_by_OBJ(CMS_SignerInfo *si,
\& const ASN1_OBJECT *obj, int type,
\& const void *bytes, int len);
\& int CMS_signed_add1_attr_by_NID(CMS_SignerInfo *si,
\& int nid, int type,
\& const void *bytes, int len);
\& int CMS_signed_add1_attr_by_txt(CMS_SignerInfo *si,
\& const char *attrname, int type,
\& const void *bytes, int len);
\& void *CMS_signed_get0_data_by_OBJ(const CMS_SignerInfo *si,
\& const ASN1_OBJECT *oid,
\& int lastpos, int type);
\&
\& int CMS_unsigned_get_attr_count(const CMS_SignerInfo *si);
\& int CMS_unsigned_get_attr_by_NID(const CMS_SignerInfo *si, int nid,
\& int lastpos);
\& int CMS_unsigned_get_attr_by_OBJ(const CMS_SignerInfo *si,
\& const ASN1_OBJECT *obj, int lastpos);
\& X509_ATTRIBUTE *CMS_unsigned_get_attr(const CMS_SignerInfo *si, int loc);
\& X509_ATTRIBUTE *CMS_unsigned_delete_attr(CMS_SignerInfo *si, int loc);
\& int CMS_unsigned_add1_attr(CMS_SignerInfo *si, X509_ATTRIBUTE *attr);
\& int CMS_unsigned_add1_attr_by_OBJ(CMS_SignerInfo *si,
\& const ASN1_OBJECT *obj, int type,
\& const void *bytes, int len);
\& int CMS_unsigned_add1_attr_by_NID(CMS_SignerInfo *si,
\& int nid, int type,
\& const void *bytes, int len);
\& int CMS_unsigned_add1_attr_by_txt(CMS_SignerInfo *si,
\& const char *attrname, int type,
\& const void *bytes, int len);
\& void *CMS_unsigned_get0_data_by_OBJ(CMS_SignerInfo *si, ASN1_OBJECT *oid,
\& int lastpos, int type);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
CMS_signerInfo contains separate attribute lists for signed and unsigned
attributes. Each \fBCMS_signed_XXX()\fR function is used for signed attributes, and
each \fBCMS_unsigned_XXX()\fR function is used for unsigned attributes.
Since the \fBCMS_unsigned_XXX()\fR functions work in the same way as the
\&\fBCMS_signed_XXX()\fR equivalents, only the \fBCMS_signed_XXX()\fR functions are
described below.
.PP
\&\fBCMS_signed_get_attr_by_OBJ()\fR finds the location of the first matching object
\&\fIobj\fR in the SignerInfo's \fIsi\fR signed attribute list. The search starts at the
position after \fIlastpos\fR. If the returned value is positive then it can be used
on the next call to \fBCMS_signed_get_attr_by_OBJ()\fR as the value of \fIlastpos\fR in
order to iterate through the remaining attributes. \fIlastpos\fR can be set to any
negative value on the first call, in order to start searching from the start of
the signed attribute list.
.PP
\&\fBCMS_signed_get_attr_by_NID()\fR is similar to \fBCMS_signed_get_attr_by_OBJ()\fR except
that it passes the numerical identifier (\s-1NID\s0) \fInid\fR associated with the object.
See <openssl/obj_mac.h> for a list of NID_*.
.PP
\&\fBCMS_signed_get_attr()\fR returns the \fBX509_ATTRIBUTE\fR object at index \fIloc\fR in the
\&\fIsi\fR signed attribute list. \fIloc\fR should be in the range from 0 to
\&\fBCMS_signed_get_attr_count()\fR \- 1.
.PP
\&\fBCMS_signed_delete_attr()\fR removes the \fBX509_ATTRIBUTE\fR object at index \fIloc\fR in
the \fIsi\fR signed attribute list. An error occurs if the \fIsi\fR attribute list
is \s-1NULL.\s0
.PP
\&\fBCMS_signed_add1_attr()\fR pushes a copy of the passed in \fBX509_ATTRIBUTE\fR object
to the \fIsi\fR signed attribute list. A new signed attribute list is created if
required. An error occurs if \fIattr\fR is \s-1NULL.\s0
.PP
\&\fBCMS_signed_add1_attr_by_OBJ()\fR creates a new signed \fBX509_ATTRIBUTE\fR using
\&\fBX509_ATTRIBUTE_set1_object()\fR and \fBX509_ATTRIBUTE_set1_data()\fR to assign a new
\&\fIobj\fR with type \fItype\fR and data \fIbytes\fR of length \fIlen\fR and then pushes it
to the \fIkey\fR object's attribute list.
.PP
\&\fBCMS_signed_add1_attr_by_NID()\fR is similar to \fBCMS_signed_add1_attr_by_OBJ()\fR except
that it passes the numerical identifier (\s-1NID\s0) \fInid\fR associated with the object.
See <openssl/obj_mac.h> for a list of NID_*.
.PP
\&\fBCMS_signed_add1_attr_by_txt()\fR is similar to \fBCMS_signed_add1_attr_by_OBJ()\fR
except that it passes a name \fIattrname\fR associated with the object.
See <openssl/obj_mac.h> for a list of SN_* names.
.PP
\&\fBCMS_signed_get0_data_by_OBJ()\fR finds the first attribute in a \fIsi\fR signed
attributes list that matches the \fIobj\fR starting at index \fIlastpos\fR
and returns the data retrieved from the found attributes first \fB\s-1ASN1_TYPE\s0\fR
object. An error will occur if the attribute type \fItype\fR does not match the
type of the \fB\s-1ASN1_TYPE\s0\fR object \s-1OR\s0 if \fItype\fR is either \fBV_ASN1_BOOLEAN\fR or
\&\fBV_ASN1_NULL\fR \s-1OR\s0 the attribute is not found.
If \fIlastpos\fR is less than \-1 then an error will occur if there are multiple
objects in the signed attribute list that match \fIobj\fR.
If \fIlastpos\fR is less than \-2 then an error will occur if there is more than
one \fB\s-1ASN1_TYPE\s0\fR object in the found signed attribute.
.PP
Refer to \fBX509_ATTRIBUTE\fR\|(3) for information related to attributes.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
The \fBCMS_unsigned_XXX()\fR functions return values are similar to those of the
equivalent \fBCMS_signed_XXX()\fR functions.
.PP
\&\fBCMS_signed_get_attr_count()\fR returns the number of signed attributes in the
SignerInfo \fIsi\fR, or \-1 if the signed attribute list is \s-1NULL.\s0
.PP
\&\fBCMS_signed_get_attr_by_OBJ()\fR returns \-1 if either the signed attribute list of
\&\fIsi\fR is empty \s-1OR\s0 if \fIobj\fR is not found, otherwise it returns the location of
the \fIobj\fR in the SignerInfo's \fIsi\fR signed attribute list.
.PP
\&\fBCMS_signed_get_attr_by_NID()\fR is similar to \fBCMS_signed_get_attr_by_OBJ()\fR except
that it returns \-2 if the \fInid\fR is not known by OpenSSL.
.PP
\&\fBCMS_signed_get_attr()\fR returns either a signed \fBX509_ATTRIBUTE\fR or \s-1NULL\s0 on error.
.PP
\&\fBCMS_signed_delete_attr()\fR returns either the removed signed \fBX509_ATTRIBUTE\fR or
\&\s-1NULL\s0 if there is a error.
.PP
\&\fBCMS_signed_add1_attr()\fR, \fBCMS_signed_add1_attr_by_OBJ()\fR,
\&\fBCMS_signed_add1_attr_by_NID()\fR, \fBCMS_signed_add1_attr_by_txt()\fR,
return 1 on success or 0 on error.
.PP
\&\fBCMS_signed_get0_data_by_OBJ()\fR returns the data retrieved from the found
signed attributes first \fB\s-1ASN1_TYPE\s0\fR object, or \s-1NULL\s0 if an error occurs.
.SH "NOTES"
.IX Header "NOTES"
Some attributes are added automatically during the signing process.
.PP
Calling \fBCMS_SignerInfo_sign()\fR adds the NID_pkcs9_signingTime signed
attribute.
.PP
Calling \fBCMS_final()\fR, \fBCMS_final_digest()\fR or \fBCMS_dataFinal()\fR adds the
NID_pkcs9_messageDigest signed attribute.
.PP
The NID_pkcs9_contentType signed attribute is always added if the
NID_pkcs9_signingTime attribute is added.
.PP
Calling \fBCMS_sign_ex()\fR, \fBCMS_sign_receipt()\fR or \fBCMS_add1_signer()\fR may add
attributes depending on the flags parameter. See \fBCMS_add1_signer\fR\|(3) for
more information.
.PP
OpenSSL applies special rules for the following attribute NIDs:
.IP "\s-1CMS\s0 Signed Attributes" 4
.IX Item "CMS Signed Attributes"
NID_pkcs9_contentType
NID_pkcs9_messageDigest
NID_pkcs9_signingTime
.IP "\s-1ESS\s0 Signed Attributes" 4
.IX Item "ESS Signed Attributes"
NID_id_smime_aa_signingCertificate
NID_id_smime_aa_signingCertificateV2
NID_id_smime_aa_receiptRequest
.IP "\s-1CMS\s0 Unsigned Attributes" 4
.IX Item "CMS Unsigned Attributes"
NID_pkcs9_countersignature
.PP
\&\fBCMS_signed_add1_attr()\fR, \fBCMS_signed_add1_attr_by_OBJ()\fR,
\&\fBCMS_signed_add1_attr_by_NID()\fR, \fBCMS_signed_add1_attr_by_txt()\fR
and the equivalent \fBCMS_unsigned_add1_attrXXX()\fR functions allow
duplicate attributes to be added. The attribute rules are not checked
during these function calls, and are deferred until the sign or verify process
(i.e. during calls to any of \fBCMS_sign_ex()\fR, \fBCMS_sign()\fR, \fBCMS_sign_receipt()\fR,
\&\fBCMS_add1_signer()\fR, \fBCMS_Final()\fR, \fBCMS_dataFinal()\fR, \fBCMS_final_digest()\fR,
\&\fBCMS_verify()\fR, \fBCMS_verify_receipt()\fR or \fBCMS_SignedData_verify()\fR).
.PP
For \s-1CMS\s0 attribute rules see \s-1RFC 5652\s0 Section 11.
For \s-1ESS\s0 attribute rules see \s-1RFC 2634\s0 Section 1.3.4 and \s-1RFC 5035\s0 Section 5.4.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBX509_ATTRIBUTE\fR\|(3)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2023\-2024 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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>.

189
openssl-3.4.2/doc/man/man3/CMS_uncompress.3
View File

@@ -1,189 +0,0 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 "CMS_UNCOMPRESS 3ossl"
.TH CMS_UNCOMPRESS 3ossl "2025-07-01" "3.4.2" "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_uncompress \- uncompress a CMS CompressedData structure
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/cms.h>
\&
\& int CMS_uncompress(CMS_ContentInfo *cms, BIO *dcont, BIO *out, unsigned int flags);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBCMS_uncompress()\fR extracts and uncompresses the content from a \s-1CMS\s0
CompressedData structure \fBcms\fR. \fBdata\fR is a \s-1BIO\s0 to write the content to and
\&\fBflags\fR is an optional set of flags.
.PP
The \fBdcont\fR parameter is used in the rare case where the compressed content
is detached. It will normally be set to \s-1NULL.\s0
.SH "NOTES"
.IX Header "NOTES"
The only currently supported compression algorithm is zlib: if the structure
indicates the use of any other algorithm an error is returned.
.PP
If zlib support is not compiled into OpenSSL then \fBCMS_uncompress()\fR will always
return an error.
.PP
The following flags can be passed in the \fBflags\fR parameter.
.PP
If the \fB\s-1CMS_TEXT\s0\fR flag is set \s-1MIME\s0 headers for type \fBtext/plain\fR are deleted
from the content. If the content is not of type \fBtext/plain\fR then an error is
returned.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBCMS_uncompress()\fR returns either 1 for success or 0 for failure. The error can
be obtained from \fBERR_get_error\fR\|(3)
.SH "BUGS"
.IX Header "BUGS"
The lack of single pass processing and the need to hold all data in memory as
mentioned in \fBCMS_verify()\fR also applies to \fBCMS_decompress()\fR.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBERR_get_error\fR\|(3), \fBCMS_compress\fR\|(3)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2008\-2016 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (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