diff options
Diffstat (limited to 'secure/lib/libcrypto/man/man3/X509_PUBKEY_new.3')
| -rw-r--r-- | secure/lib/libcrypto/man/man3/X509_PUBKEY_new.3 | 104 |
1 files changed, 67 insertions, 37 deletions
diff --git a/secure/lib/libcrypto/man/man3/X509_PUBKEY_new.3 b/secure/lib/libcrypto/man/man3/X509_PUBKEY_new.3 index 73362aff6153..331c116b1cc7 100644 --- a/secure/lib/libcrypto/man/man3/X509_PUBKEY_new.3 +++ b/secure/lib/libcrypto/man/man3/X509_PUBKEY_new.3 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== @@ -68,8 +68,6 @@ . \} .\} .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 \{\ @@ -132,86 +130,113 @@ .rm #[ #] #H #V #F C .\" ======================================================================== .\" -.IX Title "X509_PUBKEY_NEW 3" -.TH X509_PUBKEY_NEW 3 "2022-05-03" "1.1.1o" "OpenSSL" +.IX Title "X509_PUBKEY_NEW 3ossl" +.TH X509_PUBKEY_NEW 3ossl "2023-09-19" "3.0.11" "OpenSSL" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" -X509_PUBKEY_new, X509_PUBKEY_free, X509_PUBKEY_set, X509_PUBKEY_get0, X509_PUBKEY_get, d2i_PUBKEY, i2d_PUBKEY, d2i_PUBKEY_bio, d2i_PUBKEY_fp, i2d_PUBKEY_fp, i2d_PUBKEY_bio, X509_PUBKEY_set0_param, X509_PUBKEY_get0_param \- SubjectPublicKeyInfo public key functions +X509_PUBKEY_new_ex, X509_PUBKEY_new, X509_PUBKEY_free, X509_PUBKEY_dup, +X509_PUBKEY_set, X509_PUBKEY_get0, X509_PUBKEY_get, +d2i_PUBKEY_ex, d2i_PUBKEY, i2d_PUBKEY, d2i_PUBKEY_bio, d2i_PUBKEY_fp, +i2d_PUBKEY_fp, i2d_PUBKEY_bio, X509_PUBKEY_set0_param, X509_PUBKEY_get0_param, +X509_PUBKEY_eq \- SubjectPublicKeyInfo public key functions .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& #include <openssl/x509.h> \& +\& X509_PUBKEY *X509_PUBKEY_new_ex(OSSL_LIB_CTX *libctx, const char *propq); \& X509_PUBKEY *X509_PUBKEY_new(void); \& void X509_PUBKEY_free(X509_PUBKEY *a); +\& X509_PUBKEY *X509_PUBKEY_dup(const X509_PUBKEY *a); \& \& int X509_PUBKEY_set(X509_PUBKEY **x, EVP_PKEY *pkey); -\& EVP_PKEY *X509_PUBKEY_get0(X509_PUBKEY *key); -\& EVP_PKEY *X509_PUBKEY_get(X509_PUBKEY *key); +\& EVP_PKEY *X509_PUBKEY_get0(const X509_PUBKEY *key); +\& EVP_PKEY *X509_PUBKEY_get(const X509_PUBKEY *key); \& +\& EVP_PKEY *d2i_PUBKEY_ex(EVP_PKEY **a, const unsigned char **pp, long length, +\& OSSL_LIB_CTX *libctx, const char *propq); \& EVP_PKEY *d2i_PUBKEY(EVP_PKEY **a, const unsigned char **pp, long length); -\& int i2d_PUBKEY(EVP_PKEY *a, unsigned char **pp); +\& int i2d_PUBKEY(const EVP_PKEY *a, unsigned char **pp); \& \& EVP_PKEY *d2i_PUBKEY_bio(BIO *bp, EVP_PKEY **a); \& EVP_PKEY *d2i_PUBKEY_fp(FILE *fp, EVP_PKEY **a); \& -\& int i2d_PUBKEY_fp(FILE *fp, EVP_PKEY *pkey); -\& int i2d_PUBKEY_bio(BIO *bp, EVP_PKEY *pkey); +\& int i2d_PUBKEY_fp(const FILE *fp, EVP_PKEY *pkey); +\& int i2d_PUBKEY_bio(BIO *bp, const EVP_PKEY *pkey); \& \& int X509_PUBKEY_set0_param(X509_PUBKEY *pub, ASN1_OBJECT *aobj, \& int ptype, void *pval, \& unsigned char *penc, int penclen); \& int X509_PUBKEY_get0_param(ASN1_OBJECT **ppkalg, \& const unsigned char **pk, int *ppklen, -\& X509_ALGOR **pa, X509_PUBKEY *pub); +\& X509_ALGOR **pa, const X509_PUBKEY *pub); +\& int X509_PUBKEY_eq(X509_PUBKEY *a, X509_PUBKEY *b); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \fBX509_PUBKEY\fR structure represents the \s-1ASN.1\s0 \fBSubjectPublicKeyInfo\fR structure defined in \s-1RFC5280\s0 and used in certificates and certificate requests. .PP -\&\fBX509_PUBKEY_new()\fR allocates and initializes an \fBX509_PUBKEY\fR structure. +\&\fBX509_PUBKEY_new_ex()\fR allocates and initializes an \fBX509_PUBKEY\fR structure +associated with the given \fB\s-1OSSL_LIB_CTX\s0\fR in the \fIlibctx\fR parameter. Any +algorithm fetches associated with using the \fBX509_PUBKEY\fR object will use +the property query string \fIpropq\fR. See \*(L"\s-1ALGORITHM FETCHING\*(R"\s0 in \fBcrypto\fR\|(7) for +further information about algorithm fetching. +.PP +\&\fBX509_PUBKEY_new()\fR is the same as \fBX509_PUBKEY_new_ex()\fR except that the default +(\s-1NULL\s0) \fB\s-1OSSL_LIB_CTX\s0\fR and a \s-1NULL\s0 property query string are used. .PP -\&\fBX509_PUBKEY_free()\fR frees up \fBX509_PUBKEY\fR structure \fBa\fR. If \fBa\fR is \s-1NULL\s0 +\&\fBX509_PUBKEY_dup()\fR creates a duplicate copy of the \fBX509_PUBKEY\fR object +specified by \fIa\fR. +.PP +\&\fBX509_PUBKEY_free()\fR frees up \fBX509_PUBKEY\fR structure \fIa\fR. If \fIa\fR is \s-1NULL\s0 nothing is done. .PP -\&\fBX509_PUBKEY_set()\fR sets the public key in \fB*x\fR to the public key contained -in the \fB\s-1EVP_PKEY\s0\fR structure \fBpkey\fR. If \fB*x\fR is not \s-1NULL\s0 any existing +\&\fBX509_PUBKEY_set()\fR sets the public key in \fI*x\fR to the public key contained +in the \fB\s-1EVP_PKEY\s0\fR structure \fIpkey\fR. If \fI*x\fR is not \s-1NULL\s0 any existing public key structure will be freed. .PP -\&\fBX509_PUBKEY_get0()\fR returns the public key contained in \fBkey\fR. The returned +\&\fBX509_PUBKEY_get0()\fR returns the public key contained in \fIkey\fR. The returned value is an internal pointer which \fB\s-1MUST NOT\s0\fR be freed after use. .PP \&\fBX509_PUBKEY_get()\fR is similar to \fBX509_PUBKEY_get0()\fR except the reference count on the returned key is incremented so it \fB\s-1MUST\s0\fR be freed using \&\fBEVP_PKEY_free()\fR after use. .PP -\&\fBd2i_PUBKEY()\fR and \fBi2d_PUBKEY()\fR decode and encode an \fB\s-1EVP_PKEY\s0\fR structure -using \fBSubjectPublicKeyInfo\fR format. They otherwise follow the conventions of -other \s-1ASN.1\s0 functions such as \fBd2i_X509()\fR. +\&\fBd2i_PUBKEY_ex()\fR decodes an \fB\s-1EVP_PKEY\s0\fR structure using \fBSubjectPublicKeyInfo\fR +format. Some public key decoding implementations may use cryptographic +algorithms. In this case the supplied library context \fIlibctx\fR and property +query string \fIpropq\fR are used. +\&\fBd2i_PUBKEY()\fR does the same as \fBd2i_PUBKEY_ex()\fR except that the default +library context and property query string are used. +.PP +\&\fBi2d_PUBKEY()\fR encodes an \fB\s-1EVP_PKEY\s0\fR structure using \fBSubjectPublicKeyInfo\fR +format. .PP \&\fBd2i_PUBKEY_bio()\fR, \fBd2i_PUBKEY_fp()\fR, \fBi2d_PUBKEY_bio()\fR and \fBi2d_PUBKEY_fp()\fR are similar to \fBd2i_PUBKEY()\fR and \fBi2d_PUBKEY()\fR except they decode or encode using a \&\fB\s-1BIO\s0\fR or \fB\s-1FILE\s0\fR pointer. .PP -\&\fBX509_PUBKEY_set0_param()\fR sets the public key parameters of \fBpub\fR. The -\&\s-1OID\s0 associated with the algorithm is set to \fBaobj\fR. The type of the -algorithm parameters is set to \fBtype\fR using the structure \fBpval\fR. -The encoding of the public key itself is set to the \fBpenclen\fR -bytes contained in buffer \fBpenc\fR. On success ownership of all the supplied -parameters is passed to \fBpub\fR so they must not be freed after the +\&\fBX509_PUBKEY_set0_param()\fR sets the public key parameters of \fIpub\fR. The +\&\s-1OID\s0 associated with the algorithm is set to \fIaobj\fR. The type of the +algorithm parameters is set to \fItype\fR using the structure \fIpval\fR. +The encoding of the public key itself is set to the \fIpenclen\fR +bytes contained in buffer \fIpenc\fR. On success ownership of all the supplied +parameters is passed to \fIpub\fR so they must not be freed after the call. .PP -\&\fBX509_PUBKEY_get0_param()\fR retrieves the public key parameters from \fBpub\fR, -\&\fB*ppkalg\fR is set to the associated \s-1OID\s0 and the encoding consists of -\&\fB*ppklen\fR bytes at \fB*pk\fR, \fB*pa\fR is set to the associated +\&\fBX509_PUBKEY_get0_param()\fR retrieves the public key parameters from \fIpub\fR, +\&\fI*ppkalg\fR is set to the associated \s-1OID\s0 and the encoding consists of +\&\fI*ppklen\fR bytes at \fI*pk\fR, \fI*pa\fR is set to the associated AlgorithmIdentifier for the public key. If the value of any of these -parameters is not required it can be set to \fB\s-1NULL\s0\fR. All of the +parameters is not required it can be set to \s-1NULL.\s0 All of the retrieved pointers are internal and must not be freed after the call. +.PP +\&\fBX509_PUBKEY_eq()\fR compares two \fBX509_PUBKEY\fR values. .SH "NOTES" .IX Header "NOTES" The \fBX509_PUBKEY\fR functions can be used to encode and decode public keys @@ -221,28 +246,33 @@ In many cases applications will not call the \fBX509_PUBKEY\fR functions directly: they will instead call wrapper functions such as \fBX509_get0_pubkey()\fR. .SH "RETURN VALUES" .IX Header "RETURN VALUES" -If the allocation fails, \fBX509_PUBKEY_new()\fR returns \fB\s-1NULL\s0\fR and sets an error -code that can be obtained by \fBERR_get_error\fR\|(3). -.PP -Otherwise it returns a pointer to the newly allocated structure. +If the allocation fails, \fBX509_PUBKEY_new()\fR and \fBX509_PUBKEY_dup()\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. .PP \&\fBX509_PUBKEY_free()\fR does not return a value. .PP \&\fBX509_PUBKEY_get0()\fR and \fBX509_PUBKEY_get()\fR return a pointer to an \fB\s-1EVP_PKEY\s0\fR -structure or \fB\s-1NULL\s0\fR if an error occurs. +structure or \s-1NULL\s0 if an error occurs. .PP \&\fBX509_PUBKEY_set()\fR, \fBX509_PUBKEY_set0_param()\fR and \fBX509_PUBKEY_get0_param()\fR return 1 for success and 0 if an error occurred. +.PP +\&\fBX509_PUBKEY_eq()\fR returns 1 for equal, 0 for different, and < 0 on error. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBd2i_X509\fR\|(3), \&\fBERR_get_error\fR\|(3), \&\fBX509_get_pubkey\fR\|(3), +.SH "HISTORY" +.IX Header "HISTORY" +The \fBX509_PUBKEY_new_ex()\fR and \fBX509_PUBKEY_eq()\fR functions were added in OpenSSL +3.0. .SH "COPYRIGHT" .IX Header "COPYRIGHT" -Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2016\-2021 The OpenSSL Project Authors. All Rights Reserved. .PP -Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +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>. |