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