xref: /freebsd/crypto/openssl/doc/man3/X509_PUBKEY_new.pod (revision e71b70530d95c4f34d8bdbd78d1242df1ba4a945)
1*e71b7053SJung-uk Kim=pod
2*e71b7053SJung-uk Kim
3*e71b7053SJung-uk Kim=head1 NAME
4*e71b7053SJung-uk Kim
5*e71b7053SJung-uk KimX509_PUBKEY_new, X509_PUBKEY_free, X509_PUBKEY_set, X509_PUBKEY_get0,
6*e71b7053SJung-uk KimX509_PUBKEY_get, d2i_PUBKEY, i2d_PUBKEY, d2i_PUBKEY_bio, d2i_PUBKEY_fp,
7*e71b7053SJung-uk Kimi2d_PUBKEY_fp, i2d_PUBKEY_bio, X509_PUBKEY_set0_param,
8*e71b7053SJung-uk KimX509_PUBKEY_get0_param - SubjectPublicKeyInfo public key functions
9*e71b7053SJung-uk Kim
10*e71b7053SJung-uk Kim=head1 SYNOPSIS
11*e71b7053SJung-uk Kim
12*e71b7053SJung-uk Kim #include <openssl/x509.h>
13*e71b7053SJung-uk Kim
14*e71b7053SJung-uk Kim X509_PUBKEY *X509_PUBKEY_new(void);
15*e71b7053SJung-uk Kim void X509_PUBKEY_free(X509_PUBKEY *a);
16*e71b7053SJung-uk Kim
17*e71b7053SJung-uk Kim int X509_PUBKEY_set(X509_PUBKEY **x, EVP_PKEY *pkey);
18*e71b7053SJung-uk Kim EVP_PKEY *X509_PUBKEY_get0(X509_PUBKEY *key);
19*e71b7053SJung-uk Kim EVP_PKEY *X509_PUBKEY_get(X509_PUBKEY *key);
20*e71b7053SJung-uk Kim
21*e71b7053SJung-uk Kim EVP_PKEY *d2i_PUBKEY(EVP_PKEY **a, const unsigned char **pp, long length);
22*e71b7053SJung-uk Kim int i2d_PUBKEY(EVP_PKEY *a, unsigned char **pp);
23*e71b7053SJung-uk Kim
24*e71b7053SJung-uk Kim EVP_PKEY *d2i_PUBKEY_bio(BIO *bp, EVP_PKEY **a);
25*e71b7053SJung-uk Kim EVP_PKEY *d2i_PUBKEY_fp(FILE *fp, EVP_PKEY **a);
26*e71b7053SJung-uk Kim
27*e71b7053SJung-uk Kim int i2d_PUBKEY_fp(FILE *fp, EVP_PKEY *pkey);
28*e71b7053SJung-uk Kim int i2d_PUBKEY_bio(BIO *bp, EVP_PKEY *pkey);
29*e71b7053SJung-uk Kim
30*e71b7053SJung-uk Kim int X509_PUBKEY_set0_param(X509_PUBKEY *pub, ASN1_OBJECT *aobj,
31*e71b7053SJung-uk Kim                            int ptype, void *pval,
32*e71b7053SJung-uk Kim                            unsigned char *penc, int penclen);
33*e71b7053SJung-uk Kim int X509_PUBKEY_get0_param(ASN1_OBJECT **ppkalg,
34*e71b7053SJung-uk Kim                            const unsigned char **pk, int *ppklen,
35*e71b7053SJung-uk Kim                            X509_ALGOR **pa, X509_PUBKEY *pub);
36*e71b7053SJung-uk Kim
37*e71b7053SJung-uk Kim=head1 DESCRIPTION
38*e71b7053SJung-uk Kim
39*e71b7053SJung-uk KimThe B<X509_PUBKEY> structure represents the ASN.1 B<SubjectPublicKeyInfo>
40*e71b7053SJung-uk Kimstructure defined in RFC5280 and used in certificates and certificate requests.
41*e71b7053SJung-uk Kim
42*e71b7053SJung-uk KimX509_PUBKEY_new() allocates and initializes an B<X509_PUBKEY> structure.
43*e71b7053SJung-uk Kim
44*e71b7053SJung-uk KimX509_PUBKEY_free() frees up B<X509_PUBKEY> structure B<a>. If B<a> is NULL
45*e71b7053SJung-uk Kimnothing is done.
46*e71b7053SJung-uk Kim
47*e71b7053SJung-uk KimX509_PUBKEY_set() sets the public key in B<*x> to the public key contained
48*e71b7053SJung-uk Kimin the B<EVP_PKEY> structure B<pkey>. If B<*x> is not NULL any existing
49*e71b7053SJung-uk Kimpublic key structure will be freed.
50*e71b7053SJung-uk Kim
51*e71b7053SJung-uk KimX509_PUBKEY_get0() returns the public key contained in B<key>. The returned
52*e71b7053SJung-uk Kimvalue is an internal pointer which B<MUST NOT> be freed after use.
53*e71b7053SJung-uk Kim
54*e71b7053SJung-uk KimX509_PUBKEY_get() is similar to X509_PUBKEY_get0() except the reference
55*e71b7053SJung-uk Kimcount on the returned key is incremented so it B<MUST> be freed using
56*e71b7053SJung-uk KimEVP_PKEY_free() after use.
57*e71b7053SJung-uk Kim
58*e71b7053SJung-uk Kimd2i_PUBKEY() and i2d_PUBKEY() decode and encode an B<EVP_PKEY> structure
59*e71b7053SJung-uk Kimusing B<SubjectPublicKeyInfo> format. They otherwise follow the conventions of
60*e71b7053SJung-uk Kimother ASN.1 functions such as d2i_X509().
61*e71b7053SJung-uk Kim
62*e71b7053SJung-uk Kimd2i_PUBKEY_bio(), d2i_PUBKEY_fp(), i2d_PUBKEY_bio() and i2d_PUBKEY_fp() are
63*e71b7053SJung-uk Kimsimilar to d2i_PUBKEY() and i2d_PUBKEY() except they decode or encode using a
64*e71b7053SJung-uk KimB<BIO> or B<FILE> pointer.
65*e71b7053SJung-uk Kim
66*e71b7053SJung-uk KimX509_PUBKEY_set0_param() sets the public key parameters of B<pub>. The
67*e71b7053SJung-uk KimOID associated with the algorithm is set to B<aobj>. The type of the
68*e71b7053SJung-uk Kimalgorithm parameters is set to B<type> using the structure B<pval>.
69*e71b7053SJung-uk KimThe encoding of the public key itself is set to the B<penclen>
70*e71b7053SJung-uk Kimbytes contained in buffer B<penc>. On success ownership of all the supplied
71*e71b7053SJung-uk Kimparameters is passed to B<pub> so they must not be freed after the
72*e71b7053SJung-uk Kimcall.
73*e71b7053SJung-uk Kim
74*e71b7053SJung-uk KimX509_PUBKEY_get0_param() retrieves the public key parameters from B<pub>,
75*e71b7053SJung-uk KimB<*ppkalg> is set to the associated OID and the encoding consists of
76*e71b7053SJung-uk KimB<*ppklen> bytes at B<*pk>, B<*pa> is set to the associated
77*e71b7053SJung-uk KimAlgorithmIdentifier for the public key. If the value of any of these
78*e71b7053SJung-uk Kimparameters is not required it can be set to B<NULL>. All of the
79*e71b7053SJung-uk Kimretrieved pointers are internal and must not be freed after the
80*e71b7053SJung-uk Kimcall.
81*e71b7053SJung-uk Kim
82*e71b7053SJung-uk Kim=head1 NOTES
83*e71b7053SJung-uk Kim
84*e71b7053SJung-uk KimThe B<X509_PUBKEY> functions can be used to encode and decode public keys
85*e71b7053SJung-uk Kimin a standard format.
86*e71b7053SJung-uk Kim
87*e71b7053SJung-uk KimIn many cases applications will not call the B<X509_PUBKEY> functions
88*e71b7053SJung-uk Kimdirectly: they will instead call wrapper functions such as X509_get0_pubkey().
89*e71b7053SJung-uk Kim
90*e71b7053SJung-uk Kim=head1 RETURN VALUES
91*e71b7053SJung-uk Kim
92*e71b7053SJung-uk KimIf the allocation fails, X509_PUBKEY_new() returns B<NULL> and sets an error
93*e71b7053SJung-uk Kimcode that can be obtained by L<ERR_get_error(3)>.
94*e71b7053SJung-uk Kim
95*e71b7053SJung-uk KimOtherwise it returns a pointer to the newly allocated structure.
96*e71b7053SJung-uk Kim
97*e71b7053SJung-uk KimX509_PUBKEY_free() does not return a value.
98*e71b7053SJung-uk Kim
99*e71b7053SJung-uk KimX509_PUBKEY_get0() and X509_PUBKEY_get() return a pointer to an B<EVP_PKEY>
100*e71b7053SJung-uk Kimstructure or B<NULL> if an error occurs.
101*e71b7053SJung-uk Kim
102*e71b7053SJung-uk KimX509_PUBKEY_set(), X509_PUBKEY_set0_param() and X509_PUBKEY_get0_param()
103*e71b7053SJung-uk Kimreturn 1 for success and 0 if an error occurred.
104*e71b7053SJung-uk Kim
105*e71b7053SJung-uk Kim=head1 SEE ALSO
106*e71b7053SJung-uk Kim
107*e71b7053SJung-uk KimL<d2i_X509(3)>,
108*e71b7053SJung-uk KimL<ERR_get_error(3)>,
109*e71b7053SJung-uk KimL<X509_get_pubkey(3)>,
110*e71b7053SJung-uk Kim
111*e71b7053SJung-uk Kim=head1 COPYRIGHT
112*e71b7053SJung-uk Kim
113*e71b7053SJung-uk KimCopyright 2016 The OpenSSL Project Authors. All Rights Reserved.
114*e71b7053SJung-uk Kim
115*e71b7053SJung-uk KimLicensed under the OpenSSL license (the "License").  You may not use
116*e71b7053SJung-uk Kimthis file except in compliance with the License.  You can obtain a copy
117*e71b7053SJung-uk Kimin the file LICENSE in the source distribution or at
118*e71b7053SJung-uk KimL<https://www.openssl.org/source/license.html>.
119*e71b7053SJung-uk Kim
120*e71b7053SJung-uk Kim=cut
121