contrib/libfido2/man/eddsa_pk_new.3

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