diff options
Diffstat (limited to 'doc/man3/EVP_PKEY_set1_encoded_public_key.pod')
-rw-r--r-- | doc/man3/EVP_PKEY_set1_encoded_public_key.pod | 125 |
1 files changed, 125 insertions, 0 deletions
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 0000000000..7d43e66c31 --- /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 + |