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