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