contrib/libfido2/man/eddsa_pk_new.3

   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
  52 EDDSA is the name given in the CBOR Object Signing and Encryption
  53 (COSE) RFC to EDDSA over Curve25519 with SHA-512.
  54 The COSE EDDSA API of
  55 .Em libfido2
  56 is an auxiliary API with routines to convert between the different
  57 EDDSA public key types used in
  58 .Em libfido2
  59 and
  60 .Em OpenSSL .
  61 .Pp
  62 In
  63 .Em libfido2 ,
  64 EDDSA public keys are abstracted by the
  65 .Vt eddsa_pk_t
  66 type.
  67 .Pp
  68 The
  69 .Fn eddsa_pk_new
  70 function returns a pointer to a newly allocated, empty
  71 .Vt eddsa_pk_t
  72 type.
  73 If memory cannot be allocated, NULL is returned.
  74 .Pp
  75 The
  76 .Fn eddsa_pk_free
  77 function releases the memory backing
  78 .Fa *pkp ,
  79 where
  80 .Fa *pkp
  81 must have been previously allocated by
  82 .Fn eddsa_pk_new .
  83 On return,
  84 .Fa *pkp
  85 is set to NULL.
  86 Either
  87 .Fa pkp
  88 or
  89 .Fa *pkp
  90 may be NULL, in which case
  91 .Fn eddsa_pk_free
  92 is a NOP.
  93 .Pp
  94 The
  95 .Fn eddsa_pk_from_EVP_PKEY
  96 function fills
  97 .Fa pk
  98 with the contents of
  99 .Fa pkey .
 100 No references to
 101 .Fa pkey
 102 are kept.
 103 .Pp
 104 The
 105 .Fn eddsa_pk_from_ptr
 106 function fills
 107 .Fa pk
 108 with the contents of
 109 .Fa ptr ,
 110 where
 111 .Fa ptr
 112 points to
 113 .Fa len
 114 bytes.
 115 No references to
 116 .Fa ptr
 117 are kept.
 118 .Pp
 119 The
 120 .Fn eddsa_pk_to_EVP_PKEY
 121 function converts
 122 .Fa pk
 123 to a newly allocated
 124 .Fa EVP_PKEY
 125 type with a reference count of 1.
 126 No internal references to the returned pointer are kept.
 127 If an error occurs,
 128 .Fn eddsa_pk_to_EVP_PKEY
 129 returns NULL.
 130 .Sh RETURN VALUES
 131 The
 132 .Fn eddsa_pk_from_EVP_PKEY
 133 and
 134 .Fn eddsa_pk_from_ptr
 135 functions return
 136 .Dv FIDO_OK
 137 on success.
 138 On error, a different error code defined in
 139 .In fido/err.h
 140 is 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