1.\" Copyright (c) 2019-2022 Yubico AB. All rights reserved. 2.\" 3.\" Redistribution and use in source and binary forms, with or without 4.\" modification, are permitted provided that the following conditions are 5.\" met: 6.\" 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in 11.\" the documentation and/or other materials provided with the 12.\" distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 15.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 16.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 17.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 18.\" HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 19.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 20.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 21.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 22.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 23.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 24.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25.\" 26.\" SPDX-License-Identifier: BSD-2-Clause 27.\" 28.Dd $Mdocdate: July 15 2022 $ 29.Dt EDDSA_PK_NEW 3 30.Os 31.Sh NAME 32.Nm eddsa_pk_new , 33.Nm eddsa_pk_free , 34.Nm eddsa_pk_from_EVP_PKEY , 35.Nm eddsa_pk_from_ptr , 36.Nm eddsa_pk_to_EVP_PKEY 37.Nd FIDO2 COSE EDDSA API 38.Sh SYNOPSIS 39.In openssl/evp.h 40.In fido/eddsa.h 41.Ft eddsa_pk_t * 42.Fn eddsa_pk_new "void" 43.Ft void 44.Fn eddsa_pk_free "eddsa_pk_t **pkp" 45.Ft int 46.Fn eddsa_pk_from_EVP_PKEY "eddsa_pk_t *pk" "const EVP_PKEY *pkey" 47.Ft int 48.Fn eddsa_pk_from_ptr "eddsa_pk_t *pk" "const void *ptr" "size_t len" 49.Ft EVP_PKEY * 50.Fn eddsa_pk_to_EVP_PKEY "const eddsa_pk_t *pk" 51.Sh DESCRIPTION 52EDDSA is the name given in the CBOR Object Signing and Encryption 53(COSE) RFC to EDDSA over Curve25519 with SHA-512. 54The COSE EDDSA API of 55.Em libfido2 56is an auxiliary API with routines to convert between the different 57EDDSA public key types used in 58.Em libfido2 59and 60.Em OpenSSL . 61.Pp 62In 63.Em libfido2 , 64EDDSA public keys are abstracted by the 65.Vt eddsa_pk_t 66type. 67.Pp 68The 69.Fn eddsa_pk_new 70function returns a pointer to a newly allocated, empty 71.Vt eddsa_pk_t 72type. 73If memory cannot be allocated, NULL is returned. 74.Pp 75The 76.Fn eddsa_pk_free 77function releases the memory backing 78.Fa *pkp , 79where 80.Fa *pkp 81must have been previously allocated by 82.Fn eddsa_pk_new . 83On return, 84.Fa *pkp 85is set to NULL. 86Either 87.Fa pkp 88or 89.Fa *pkp 90may be NULL, in which case 91.Fn eddsa_pk_free 92is a NOP. 93.Pp 94The 95.Fn eddsa_pk_from_EVP_PKEY 96function fills 97.Fa pk 98with the contents of 99.Fa pkey . 100No references to 101.Fa pkey 102are kept. 103.Pp 104The 105.Fn eddsa_pk_from_ptr 106function fills 107.Fa pk 108with the contents of 109.Fa ptr , 110where 111.Fa ptr 112points to 113.Fa len 114bytes. 115No references to 116.Fa ptr 117are kept. 118.Pp 119The 120.Fn eddsa_pk_to_EVP_PKEY 121function converts 122.Fa pk 123to a newly allocated 124.Fa EVP_PKEY 125type with a reference count of 1. 126No internal references to the returned pointer are kept. 127If an error occurs, 128.Fn eddsa_pk_to_EVP_PKEY 129returns NULL. 130.Sh RETURN VALUES 131The 132.Fn eddsa_pk_from_EVP_PKEY 133and 134.Fn eddsa_pk_from_ptr 135functions return 136.Dv FIDO_OK 137on success. 138On error, a different error code defined in 139.In fido/err.h 140is returned. 141.Sh SEE ALSO 142.Xr es256_pk_new 3 , 143.Xr es384_pk_new 3 , 144.Xr fido_assert_verify 3 , 145.Xr fido_cred_pubkey_ptr 3 , 146.Xr rs256_pk_new 3 147