From: Matt Caswell <matt@openssl.org>
Date: Fri, 9 Oct 2020 14:43:24 +0000 (+0100)
Subject: Document EVP_PKEY_set1_encoded_public_key()
X-Git-Tag: openssl-3.0.0-alpha8~46
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=3795b2a302fe0bd49118605f8692591e971c4608;p=thirdparty%2Fopenssl.git

Document EVP_PKEY_set1_encoded_public_key()

Also documented EVP_PKEY_get1_encoded_public_key

Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/13105)
---

diff --git a/doc/man3/EVP_PKEY_set1_encoded_public_key.pod b/doc/man3/EVP_PKEY_set1_encoded_public_key.pod
new file mode 100644
index 00000000000..7d43e66c314
--- /dev/null
+++ b/doc/man3/EVP_PKEY_set1_encoded_public_key.pod
@@ -0,0 +1,125 @@
+=pod
+
+=head1 NAME
+
+EVP_PKEY_set1_encoded_public_key, EVP_PKEY_get1_encoded_public_key
+- functions to set and get public key data within an EVP_PKEY
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ int EVP_PKEY_set1_encoded_public_key(EVP_PKEY *pkey,
+                                      const unsigned char *pub, size_t publen);
+
+ size_t EVP_PKEY_get1_encoded_public_key(EVP_PKEY *pkey, unsigned char **ppub);
+
+ #define EVP_PKEY_set1_tls_encodedpoint(pkey, pt, ptlen) \
+         EVP_PKEY_set1_encoded_public_key((pkey), (pt), (ptlen))
+
+ #define EVP_PKEY_get1_tls_encodedpoint(pkey, ppt) \
+         EVP_PKEY_get1_encoded_public_key((pkey), (ppt))
+
+=head1 DESCRIPTION
+
+EVP_PKEY_set1_encoded_public_key() can be used to set the public key value
+within an existing EVP_PKEY object. For the built-in OpenSSL algorithms this
+currently only works for those that support key exchange. Parameters are not
+set as part of this operation, so typically an application will create an
+EVP_PKEY first, set the parameters on it, and then call this function.
+For example setting the parameters might be done using
+L<EVP_PKEY_copy_parameters(3)>.
+
+The format for the encoded public key will depend on the algorithm in use. For
+DH it should be encoded as a positive integer in big-endian form. For EC is
+should be a point conforming to Sec. 2.3.4 of the SECG SEC 1 ("Elliptic
+Curve Cryptography") standard. For X25519 and X448 it should be encoded in a
+format as defined by RFC7748.
+
+The key to be updated is supplied in B<pkey>. The buffer containing the encoded
+key is pointed to be B<pub>. The length of the buffer is supplied in B<publen>.
+
+EVP_PKEY_get1_encoded_public_key() does the equivalent operation except that
+the encoded public key is returned to the application. The key containing the
+public key data is supplied in B<pkey>. A buffer containing the encoded key will
+be allocated and stored in B<*ppub>. The length of the encoded public key is
+returned by the function. The application is responsible for freeing the
+allocated buffer.
+
+=head1 RETURN VALUES
+
+EVP_PKEY_set1_encoded_public_key() returns 1 for success and 0 or a negative
+value for failure.
+
+EVP_PKEY_get1_encoded_public_key() return 1
+
+=head1 EXAMPLES
+
+See L<EVP_PKEY_derive_init(3)> and L<EVP_PKEY_derive(3)> for information about
+performing a key exchange operation.
+
+=head2 Set up a peer's EVP_PKEY ready for a key exchange operation
+
+ #include <openssl/evp.h>
+ 
+ int exchange(EVP_PKEY *ourkey, unsigned char *peer_pub, size_t peer_pub_len)
+ {
+     EVP_PKEY *peerkey = EVP_PKEY_new();
+
+     if (peerkey == NULL || EVP_PKEY_copy_parameters(peerkey, ourkey) <= 0)
+         return 0;
+
+     if (EVP_PKEY_set1_encoded_public_key(peerkey, peer_pub,
+                                          peer_pub_len) <= 0)
+         return 0;
+ 
+     /* Do the key exchange here */
+ 
+     EVP_PKEY_free(peerkey);
+ 
+     return 1;
+ }
+
+=head2 Get an encoded public key to send to a peer
+
+ #include <openssl/evp.h>
+
+ int get_encoded_pub_key(EVP_PKEY *ourkey)
+ {
+     unsigned char *pubkey;
+     size_t pubkey_len;
+
+    pubkey_len = EVP_PKEY_get1_encoded_public_key(ourkey, &pubkey);
+    if (pubkey_len == 0)
+        return 0;
+
+    /*
+     * Send the encoded public key stored in the buffer at "pubkey" and of
+     * length pubkey_len, to the peer.
+     */
+
+    OPENSSL_free(pubkey);
+    return 1;
+ }
+
+=head1 SEE ALSO
+
+L<EVP_PKEY_new(3)>, L<EVP_PKEY_copy_parameters(7)>,
+L<EVP_PKEY_derive_init(3)>, L<EVP_PKEY_derive(3)>,
+L<EVP_PKEY-DH(7)>, L<EVP_PKEY-EC(7)>, L<EVP_PKEY-X25519(7)>, L<EVP_PKEY-X448(7)>
+
+=head1 HISTORY
+
+These functions were added in OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
+
diff --git a/util/missingcrypto.txt b/util/missingcrypto.txt
index 481331e261c..f2b91e25877 100644
--- a/util/missingcrypto.txt
+++ b/util/missingcrypto.txt
@@ -692,13 +692,11 @@ EVP_PKEY_decrypt_old(3)
 EVP_PKEY_delete_attr(3)
 EVP_PKEY_encrypt_old(3)
 EVP_PKEY_get0(3)
-EVP_PKEY_get1_tls_encodedpoint(3)
 EVP_PKEY_get_attr(3)
 EVP_PKEY_get_attr_by_NID(3)
 EVP_PKEY_get_attr_by_OBJ(3)
 EVP_PKEY_get_attr_count(3)
 EVP_PKEY_save_parameters(3)
-EVP_PKEY_set1_tls_encodedpoint(3)
 EVP_add_alg_module(3)
 EVP_add_cipher(3)
 EVP_add_digest(3)
diff --git a/util/missingcrypto111.txt b/util/missingcrypto111.txt
index 77a72952469..a232ed2af0f 100644
--- a/util/missingcrypto111.txt
+++ b/util/missingcrypto111.txt
@@ -691,13 +691,11 @@ EVP_PKEY_encrypt_old(3)
 EVP_PKEY_get0(3)
 EVP_PKEY_get0_poly1305(3)
 EVP_PKEY_get0_siphash(3)
-EVP_PKEY_get1_tls_encodedpoint(3)
 EVP_PKEY_get_attr(3)
 EVP_PKEY_get_attr_by_NID(3)
 EVP_PKEY_get_attr_by_OBJ(3)
 EVP_PKEY_get_attr_count(3)
 EVP_PKEY_save_parameters(3)
-EVP_PKEY_set1_tls_encodedpoint(3)
 EVP_PKEY_set_type(3)
 EVP_PKEY_set_type_str(3)
 EVP_add_alg_module(3)