Debian Codegraph @

upstream/debian-unstable/man3/OSSL_CMP_ITAV_set0.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "OSSL_CMP_ITAV_SET0 3SSL"
58 .TH OSSL_CMP_ITAV_SET0 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 OSSL_CMP_ITAV_create,
65 OSSL_CMP_ITAV_set0,
66 OSSL_CMP_ITAV_get0_type,
67 OSSL_CMP_ITAV_get0_value,
68 OSSL_CMP_ITAV_push0_stack_item,
69 OSSL_CMP_ITAV_new0_certProfile,
70 OSSL_CMP_ITAV_get0_certProfile
71 \&\- OSSL_CMP_ITAV utility functions
72 .SH SYNOPSIS
73 .IX Header "SYNOPSIS"
74 .Vb 1
75 \& #include <openssl/cmp.h>
76 \&
77 \& OSSL_CMP_ITAV *OSSL_CMP_ITAV_create(ASN1_OBJECT *type, ASN1_TYPE *value);
78 \& void OSSL_CMP_ITAV_set0(OSSL_CMP_ITAV *itav, ASN1_OBJECT *type,
79 \& ASN1_TYPE *value);
80 \& ASN1_OBJECT *OSSL_CMP_ITAV_get0_type(const OSSL_CMP_ITAV *itav);
81 \& ASN1_TYPE *OSSL_CMP_ITAV_get0_value(const OSSL_CMP_ITAV *itav);
82 \& int OSSL_CMP_ITAV_push0_stack_item(STACK_OF(OSSL_CMP_ITAV) **itav_sk_p,
83 \& OSSL_CMP_ITAV *itav);
84 \& OSSL_CMP_ITAV
85 \& *OSSL_CMP_ITAV_new0_certProfile(STACK_OF(ASN1_UTF8STRING) *certProfile);
86 \& int OSSL_CMP_ITAV_get0_certProfile(const OSSL_CMP_ITAV *itav,
87 \& STACK_OF(ASN1_UTF8STRING) **out);
88 .Ve
89 .SH DESCRIPTION
90 .IX Header "DESCRIPTION"
91 ITAV is short for InfoTypeAndValue. This type is defined in RFC 9810
92 section 5.3.19 and Appendix F. It is used at various places in CMP messages,
93 e.g., in the generalInfo PKIHeader field, to hold a key-value pair.
94 .PP
95 \&\fBOSSL_CMP_ITAV_create()\fR creates a new \fBOSSL_CMP_ITAV\fR structure and fills it in.
96 It combines \fBOSSL_CMP_ITAV_new()\fR and \fBOSSL_CMP_ITAV_set0()\fR.
97 .PP
98 \&\fBOSSL_CMP_ITAV_set0()\fR sets the \fIitav\fR with an infoType of \fItype\fR and an
99 infoValue of \fIvalue\fR. This function uses the pointers \fItype\fR and \fIvalue\fR
100 internally, so they must \fBnot\fR be freed up after the call.
101 .PP
102 \&\fBOSSL_CMP_ITAV_get0_type()\fR returns a direct pointer to the infoType in the
103 \&\fIitav\fR.
104 .PP
105 \&\fBOSSL_CMP_ITAV_get0_value()\fR returns a direct pointer to the infoValue in
106 the \fIitav\fR as generic \fBASN1_TYPE\fR pointer.
107 .PP
108 \&\fBOSSL_CMP_ITAV_push0_stack_item()\fR pushes \fIitav\fR to the stack pointed to
109 by \fI*itav_sk_p\fR. It creates a new stack if \fI*itav_sk_p\fR points to NULL.
110 .PP
111 \&\fBOSSL_CMP_ITAV_new0_certProfile()\fR creates a new \fBOSSL_CMP_ITAV\fR structure
112 of type \fBcertProfile\fR that includes the optionally given list of profile names.
113 On success, ownership of the list is with the new \fBOSSL_CMP_ITAV\fR structure.
114 .PP
115 \&\fBOSSL_CMP_ITAV_get0_certProfile()\fR on success assigns to \fI*out\fR
116 an internal pointer to the
117 list of certificate profile names contained in the infoValue field of \fIitav\fR.
118 The pointer may be NULL if no profile name is included.
119 It is an error if the infoType of \fIitav\fR is not \fBcertProfile\fR.
120 .SH NOTES
121 .IX Header "NOTES"
122 CMP is defined in RFC 9810.
123 .PP
124 OIDs to use as types in \fBOSSL_CMP_ITAV\fR can be found at
125 <https://datatracker.ietf.org/doc/html/rfc9480#section\-4.2.2>.
126 The respective OpenSSL NIDs, such as \fBNID_id_it_certProfile\fR,
127 are defined in the \fI<openssl/obj_mac.h>\fR header file.
128 .SH "RETURN VALUES"
129 .IX Header "RETURN VALUES"
130 \&\fBOSSL_CMP_ITAV_create()\fR and \fBOSSL_CMP_ITAV_new0_certProfile()\fR
131 return a pointer to an ITAV structure on success, or NULL on error.
132 .PP
133 \&\fBOSSL_CMP_ITAV_set0()\fR does not return a value.
134 .PP
135 \&\fBOSSL_CMP_ITAV_get0_type()\fR and \fBOSSL_CMP_ITAV_get0_value()\fR
136 return the respective pointer or NULL if their input is NULL.
137 .PP
138 \&\fBOSSL_CMP_ITAV_push0_stack_item()\fR and \fBOSSL_CMP_ITAV_get0_certProfile()\fR
139 return 1 on success, 0 on error.
140 .SH EXAMPLES
141 .IX Header "EXAMPLES"
142 The following code creates and sets a structure representing a generic
143 InfoTypeAndValue sequence, using an OID created from text as type, and an
144 integer as value. Afterwards, it is pushed to the \fBOSSL_CMP_CTX\fR to be later
145 included in the requests' PKIHeader's genInfo field.
146 .PP
147 .Vb 2
148 \& ASN1_OBJECT *type = OBJ_txt2obj("1.2.3.4.5", 1);
149 \& if (type == NULL) ...
150 \&
151 \& ASN1_INTEGER *asn1int = ASN1_INTEGER_new();
152 \& if (asn1int == NULL || !ASN1_INTEGER_set(asn1int, 12345)) ...
153 \&
154 \& ASN1_TYPE *val = ASN1_TYPE_new();
155 \& if (val == NULL) ...
156 \& ASN1_TYPE_set(val, V_ASN1_INTEGER, asn1int);
157 \&
158 \& OSSL_CMP_ITAV *itav = OSSL_CMP_ITAV_create(type, val);
159 \& if (itav == NULL) ...
160 \&
161 \& if (!OSSL_CMP_CTX_push0_geninfo_ITAV(ctx, itav)) {
162 \& OSSL_CMP_ITAV_free(itav); /* also frees type and val */
163 \& ...
164 \& }
165 \&
166 \& ...
167 \&
168 \& OSSL_CMP_CTX_free(ctx); /* also frees itav */
169 .Ve
170 .SH "SEE ALSO"
171 .IX Header "SEE ALSO"
172 \&\fBOSSL_CMP_CTX_new\fR\|(3), \fBOSSL_CMP_CTX_free\fR\|(3), \fBASN1_TYPE_set\fR\|(3)
173 .SH HISTORY
174 .IX Header "HISTORY"
175 The OpenSSL CMP support was added in OpenSSL 3.0.
176 .PP
177 \&\fBOSSL_CMP_ITAV_new0_certProfile()\fR and \fBOSSL_CMP_ITAV_get0_certProfile()\fR
178 were added in OpenSSL 3.3.
179 .SH COPYRIGHT
180 .IX Header "COPYRIGHT"
181 Copyright 2007\-2021 The OpenSSL Project Authors. All Rights Reserved.
182 .PP
183 Licensed under the Apache License 2.0 (the "License"). You may not use
184 this file except in compliance with the License. You can obtain a copy
185 in the file LICENSE in the source distribution or at
186 <https://www.openssl.org/source/license.html>.