contrib/libfido2/man/rs256_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 RS256_PK_NEW 3
  30 .Os
  31 .Sh NAME
  32 .Nm rs256_pk_new ,
  33 .Nm rs256_pk_free ,
  34 .Nm rs256_pk_from_RSA ,
  35 .Nm rs256_pk_from_EVP_PKEY ,
  36 .Nm rs256_pk_from_ptr ,
  37 .Nm rs256_pk_to_EVP_PKEY
  38 .Nd FIDO2 COSE RS256 API
  39 .Sh SYNOPSIS
  40 .In openssl/rsa.h
  41 .In fido/rs256.h
  42 .Ft rs256_pk_t *
  43 .Fn rs256_pk_new "void"
  44 .Ft void
  45 .Fn rs256_pk_free "rs256_pk_t **pkp"
  46 .Ft int
  47 .Fn rs256_pk_from_EVP_PKEY "rs256_pk_t *pk" "const EVP_PKEY *pkey"
  48 .Ft int
  49 .Fn rs256_pk_from_RSA "rs256_pk_t *pk" "const RSA *rsa"
  50 .Ft int
  51 .Fn rs256_pk_from_ptr "rs256_pk_t *pk" "const void *ptr" "size_t len"
  52 .Ft EVP_PKEY *
  53 .Fn rs256_pk_to_EVP_PKEY "const rs256_pk_t *pk"
  54 .Sh DESCRIPTION
  55 RS256 is the name given in the CBOR Object Signing and Encryption
  56 (COSE) RFC to PKCS#1.5 2048-bit RSA with SHA-256.
  57 The COSE RS256 API of
  58 .Em libfido2
  59 is an auxiliary API with routines to convert between the different
  60 RSA public key types used in
  61 .Em libfido2
  62 and
  63 .Em OpenSSL .
  64 .Pp
  65 In
  66 .Em libfido2 ,
  67 RS256 public keys are abstracted by the
  68 .Vt rs256_pk_t
  69 type.
  70 .Pp
  71 The
  72 .Fn rs256_pk_new
  73 function returns a pointer to a newly allocated, empty
  74 .Vt rs256_pk_t
  75 type.
  76 If memory cannot be allocated, NULL is returned.
  77 .Pp
  78 The
  79 .Fn rs256_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 rs256_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 rs256_pk_free
  95 is a NOP.
  96 .Pp
  97 The
  98 .Fn rs256_pk_from_EVP_PKEY
  99 function fills
 100 .Fa pk
 101 with the contents of
 102 .Fa pkey .
 103 No references to
 104 .Fa pkey
 105 are kept.
 106 .Pp
 107 The
 108 .Fn rs256_pk_from_RSA
 109 function fills
 110 .Fa pk
 111 with the contents of
 112 .Fa rsa .
 113 No references to
 114 .Fa rsa
 115 are kept.
 116 .Pp
 117 The
 118 .Fn rs256_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 No references to
 129 .Fa ptr
 130 are kept.
 131 .Pp
 132 The
 133 .Fn rs256_pk_to_EVP_PKEY
 134 function converts
 135 .Fa pk
 136 to a newly allocated
 137 .Fa EVP_PKEY
 138 type with a reference count of 1.
 139 No internal references to the returned pointer are kept.
 140 If an error occurs,
 141 .Fn rs256_pk_to_EVP_PKEY
 142 returns NULL.
 143 .Sh RETURN VALUES
 144 The
 145 .Fn rs256_pk_from_EVP_PKEY ,
 146 .Fn rs256_pk_from_RSA ,
 147 and
 148 .Fn rs256_pk_from_ptr
 149 functions return
 150 .Dv FIDO_OK
 151 on success.
 152 On error, a different error code defined in
 153 .In fido/err.h
 154 is returned.
 155 .Sh SEE ALSO
 156 .Xr eddsa_pk_new 3 ,
 157 .Xr es256_pk_new 3 ,
 158 .Xr es384_pk_new 3 ,
 159 .Xr fido_assert_verify 3 ,
 160 .Xr fido_cred_pubkey_ptr 3