1.\" Copyright (c) 2018-2021 Yubico AB. All rights reserved. 2.\" Use of this source code is governed by a BSD-style 3.\" license that can be found in the LICENSE file. 4.\" 5.Dd $Mdocdate: May 24 2018 $ 6.Dt ES256_PK_NEW 3 7.Os 8.Sh NAME 9.Nm es256_pk_new , 10.Nm es256_pk_free , 11.Nm es256_pk_from_EC_KEY , 12.Nm es256_pk_from_EVP_PKEY , 13.Nm es256_pk_from_ptr , 14.Nm es256_pk_to_EVP_PKEY 15.Nd FIDO2 COSE ES256 API 16.Sh SYNOPSIS 17.In openssl/ec.h 18.In fido/es256.h 19.Ft es256_pk_t * 20.Fn es256_pk_new "void" 21.Ft void 22.Fn es256_pk_free "es256_pk_t **pkp" 23.Ft int 24.Fn es256_pk_from_EC_KEY "es256_pk_t *pk" "const EC_KEY *ec" 25.Ft int 26.Fn es256_pk_from_EVP_PKEY "es256_pk_t *pk" "const EVP_PKEY *pkey" 27.Ft int 28.Fn es256_pk_from_ptr "es256_pk_t *pk" "const void *ptr" "size_t len" 29.Ft EVP_PKEY * 30.Fn es256_pk_to_EVP_PKEY "const es256_pk_t *pk" 31.Sh DESCRIPTION 32ES256 is the name given in the CBOR Object Signing and Encryption 33(COSE) RFC to ECDSA over P-256 with SHA-256. 34The COSE ES256 API of 35.Em libfido2 36is an auxiliary API with routines to convert between the different 37ECDSA public key types used in 38.Em libfido2 39and 40.Em OpenSSL . 41.Pp 42In 43.Em libfido2 , 44ES256 public keys are abstracted by the 45.Vt es256_pk_t 46type. 47.Pp 48The 49.Fn es256_pk_new 50function returns a pointer to a newly allocated, empty 51.Vt es256_pk_t 52type. 53If memory cannot be allocated, NULL is returned. 54.Pp 55The 56.Fn es256_pk_free 57function releases the memory backing 58.Fa *pkp , 59where 60.Fa *pkp 61must have been previously allocated by 62.Fn es256_pk_new . 63On return, 64.Fa *pkp 65is set to NULL. 66Either 67.Fa pkp 68or 69.Fa *pkp 70may be NULL, in which case 71.Fn es256_pk_free 72is a NOP. 73.Pp 74The 75.Fn es256_pk_from_EC_KEY 76function fills 77.Fa pk 78with the contents of 79.Fa ec . 80No references to 81.Fa ec 82are kept. 83.Pp 84The 85.Fn es256_pk_from_EVP_PKEY 86function fills 87.Fa pk 88with the contents of 89.Fa pkey . 90No references to 91.Fa pkey 92are kept. 93.Pp 94The 95.Fn es256_pk_from_ptr 96function fills 97.Fa pk 98with the contents of 99.Fa ptr , 100where 101.Fa ptr 102points to 103.Fa len 104bytes. 105The 106.Fa ptr 107pointer may point to an uncompressed point, or to the 108concatenation of the x and y coordinates. 109No references to 110.Fa ptr 111are kept. 112.Pp 113The 114.Fn es256_pk_to_EVP_PKEY 115function converts 116.Fa pk 117to a newly allocated 118.Fa EVP_PKEY 119type with a reference count of 1. 120No internal references to the returned pointer are kept. 121If an error occurs, 122.Fn es256_pk_to_EVP_PKEY 123returns NULL. 124.Sh RETURN VALUES 125The 126.Fn es256_pk_from_EC_KEY , 127.Fn es256_pk_from_EVP_PKEY , 128and 129.Fn es256_pk_from_ptr 130functions return 131.Dv FIDO_OK 132on success. 133On error, a different error code defined in 134.In fido/err.h 135is returned. 136.Sh SEE ALSO 137.Xr eddsa_pk_new 3 , 138.Xr fido_assert_verify 3 , 139.Xr fido_cred_pubkey_ptr 3 , 140.Xr rs256_pk_new 3 141