contrib/libfido2/man/es256_pk_new.3

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