| blob | 7ed3e68b2ed94434858af93dbb13593f1f547a28 |
1 .\" $OpenBSD: X509_PUBKEY_new.3,v 1.5 2016/12/28 14:06:06 schwarze Exp $
2 .\" OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
3 .\"
4 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
5 .\" Copyright (c) 2016 The OpenSSL Project. All rights reserved.
6 .\"
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
9 .\" are met:
10 .\"
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\"
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in
16 .\" the documentation and/or other materials provided with the
17 .\" distribution.
18 .\"
19 .\" 3. All advertising materials mentioning features or use of this
20 .\" software must display the following acknowledgment:
21 .\" "This product includes software developed by the OpenSSL Project
22 .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
23 .\"
24 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
25 .\" endorse or promote products derived from this software without
26 .\" prior written permission. For written permission, please contact
27 .\" openssl-core@openssl.org.
28 .\"
29 .\" 5. Products derived from this software may not be called "OpenSSL"
30 .\" nor may "OpenSSL" appear in their names without prior written
31 .\" permission of the OpenSSL Project.
32 .\"
33 .\" 6. Redistributions of any form whatsoever must retain the following
34 .\" acknowledgment:
35 .\" "This product includes software developed by the OpenSSL Project
36 .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
37 .\"
38 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
39 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
40 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
41 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
42 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
43 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
44 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
45 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
46 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
47 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
48 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
49 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
50 .\"
51 .Dd $Mdocdate: December 28 2016 $
52 .Dt X509_PUBKEY_NEW 3
53 .Os
54 .Sh NAME
55 .Nm X509_PUBKEY_new ,
56 .Nm X509_PUBKEY_free ,
57 .Nm X509_PUBKEY_set ,
58 .Nm X509_PUBKEY_get ,
59 .Nm d2i_PUBKEY ,
60 .Nm i2d_PUBKEY ,
61 .Nm d2i_PUBKEY_bio ,
62 .Nm d2i_PUBKEY_fp ,
63 .Nm i2d_PUBKEY_fp ,
64 .Nm i2d_PUBKEY_bio ,
65 .Nm X509_PUBKEY_set0_param ,
66 .Nm X509_PUBKEY_get0_param
67 .Nd X.509 SubjectPublicKeyInfo structure
68 .Sh SYNOPSIS
69 .In openssl/x509.h
70 .Ft X509_PUBKEY *
71 .Fn X509_PUBKEY_new void
72 .Ft void
73 .Fo X509_PUBKEY_free
74 .Fa "X509_PUBKEY *a"
75 .Fc
76 .Ft int
77 .Fo X509_PUBKEY_set
78 .Fa "X509_PUBKEY **x"
79 .Fa "EVP_PKEY *pkey"
80 .Fc
81 .Ft EVP_PKEY *
82 .Fo X509_PUBKEY_get
83 .Fa "X509_PUBKEY *key"
84 .Fc
85 .Ft EVP_PKEY *
86 .Fo d2i_PUBKEY
87 .Fa "EVP_PKEY **a"
88 .Fa "const unsigned char **pp"
89 .Fa "long length"
90 .Fc
91 .Ft int
92 .Fo i2d_PUBKEY
93 .Fa "EVP_PKEY *a"
94 .Fa "unsigned char **pp"
95 .Fc
96 .Ft EVP_PKEY *
97 .Fo d2i_PUBKEY_bio
98 .Fa "BIO *bp"
99 .Fa "EVP_PKEY **a"
100 .Fc
101 .Ft EVP_PKEY *
102 .Fo d2i_PUBKEY_fp
103 .Fa "FILE *fp"
104 .Fa "EVP_PKEY **a"
105 .Fc
106 .Ft int
107 .Fo i2d_PUBKEY_fp
108 .Fa "FILE *fp"
109 .Fa "EVP_PKEY *pkey"
110 .Fc
111 .Ft int
112 .Fo i2d_PUBKEY_bio
113 .Fa "BIO *bp"
114 .Fa "EVP_PKEY *pkey"
115 .Fc
116 .Ft int
117 .Fo X509_PUBKEY_set0_param
118 .Fa "X509_PUBKEY *pub"
119 .Fa "ASN1_OBJECT *aobj"
120 .Fa "int ptype"
121 .Fa "void *pval"
122 .Fa "unsigned char *penc"
123 .Fa "int penclen"
124 .Fc
125 .Ft int
126 .Fo X509_PUBKEY_get0_param
127 .Fa "ASN1_OBJECT **ppkalg"
128 .Fa "const unsigned char **pk"
129 .Fa "int *ppklen"
130 .Fa "X509_ALGOR **pa"
131 .Fa "X509_PUBKEY *pub"
132 .Fc
133 .Sh DESCRIPTION
134 The
135 .Vt X509_PUBKEY
136 structure represents the ASN.1
137 .Vt SubjectPublicKeyInfo
138 structure defined in RFC 5280 section 4.1 and used in certificates
139 and certificate requests.
140 .Pp
141 .Fn X509_PUBKEY_new
142 allocates and initializes an
143 .Vt X509_PUBKEY
144 structure.
145 .Pp
146 .Fn X509_PUBKEY_free
147 frees up the
148 .Vt X509_PUBKEY
149 structure
150 .Fa a .
151 If
152 .Fa a
153 is a
154 .Dv NULL
155 pointer, no action occurs.
156 .Pp
157 .Fn X509_PUBKEY_set
158 sets the public key in
159 .Pf * Fa x
160 to the public key contained in the
161 .Vt EVP_PKEY
162 structure
163 .Fa pkey .
164 If
165 .Pf * Fa x
166 is not
167 .Dv NULL ,
168 any existing public key structure will be freed.
169 .Pp
170 .Fn X509_PUBKEY_get
171 returns the public key contained in
172 .Fa key .
173 The reference
174 count on the returned key is incremented so it must be freed using
175 .Xr EVP_PKEY_free 3
176 after use.
177 .Pp
178 .Fn d2i_PUBKEY
179 and
180 .Fn i2d_PUBKEY
181 decode and encode an
182 .Vt EVP_PKEY
183 structure using
184 .Vt SubjectPublicKeyInfo
185 format.
186 For details about the semantics, examples, caveats, and bugs, see
187 .Xr ASN1_item_d2i 3 .
188 .Fn d2i_PUBKEY_bio ,
189 .Fn d2i_PUBKEY_fp ,
190 .Fn i2d_PUBKEY_bio
191 and
192 .Fn i2d_PUBKEY_fp
193 are similar except they decode or encode using a
194 .Vt BIO
195 or
196 .Vt FILE
197 pointer.
198 .Pp
199 .Fn X509_PUBKEY_set0_param
200 sets the public key parameters of
201 .Fa pub .
202 The OID associated with the algorithm is set to
203 .Fa aobj .
204 The type of the algorithm parameters is set to
205 .Fa ptype
206 using the structure
207 .Fa pval .
208 The encoding of the public key itself is set to the
209 .Fa penclen
210 bytes contained in buffer
211 .Fa penc .
212 On success ownership of all the supplied parameters is passed to
213 .Fa pub
214 so they must not be freed after the call.
215 .Pp
216 .Fn X509_PUBKEY_get0_param
217 retrieves the public key parameters from
218 .Fa pub ,
219 .Pf * Fa ppkalg
220 is set to the associated OID and the encoding consists of
221 .Pf * Fa ppklen
222 bytes at
223 .Pf * Fa pk ,
224 and
225 .Pf * Fa pa
226 is set to the associated
227 .Vt AlgorithmIdentifier
228 for the public key.
229 If the value of any of these parameters is not required,
230 it can be set to
231 .Dv NULL .
232 All of the retrieved pointers are internal and must not be freed after
233 the call.
234 .Sh RETURN VALUES
235 If the allocation fails,
236 .Fn X509_PUBKEY_new
237 returns
238 .Dv NULL
239 and sets an error code that can be obtained by
240 .Xr ERR_get_error 3 .
241 Otherwise it returns a pointer to the newly allocated structure.
242 .Pp
243 .Fn X509_PUBKEY_get ,
244 .Fn d2i_PUBKEY ,
245 .Fn d2i_PUBKEY_bio ,
246 and
247 .Fn d2i_PUBKEY_fp
248 return a pointer to an
249 .Vt EVP_PKEY
250 structure or
251 .Dv NULL
252 if an error occurs.
253 .Pp
254 .Fn i2d_PUBKEY
255 returns the number of bytes successfully encoded or a negative value
256 if an error occurs.
257 .Pp
258 .Fn X509_PUBKEY_set ,
259 .Fn X509_PUBKEY_set0_param ,
260 .Fn X509_PUBKEY_get0_param ,
261 .Fn i2d_PUBKEY_fp ,
262 and
263 .Fn i2d_PUBKEY_bio
264 return 1 for success and 0 if an error occurred.
265 .Sh SEE ALSO
266 .Xr d2i_X509 3 ,
267 .Xr ERR_get_error 3 ,
268 .Xr X509_ALGOR_new 3 ,
269 .Xr X509_get_pubkey 3
270 .Sh STANDARDS
271 RFC 5280: Internet X.509 Public Key Infrastructure Certificate and
272 Certificate Revocation List (CRL) Profile