1 files changed, 122 insertions, 0 deletions
diff --git a/man/rs256_pk_new.3 b/man/rs256_pk_new.3
new file mode 100644
index 0000000..4ad0ebe
--- /dev/null
+++ b/man/rs256_pk_new.3
@@ -0,0 +1,122 @@
+.\" Copyright (c) 2018 Yubico AB. All rights reserved.
+.\" Use of this source code is governed by a BSD-style
+.\" license that can be found in the LICENSE file.
+.\"
+.Dd $Mdocdate: May 24 2018 $
+.Dt RS256_PK_NEW 3
+.Os
+.Sh NAME
+.Nm rs256_pk_new ,
+.Nm rs256_pk_free ,
+.Nm rs256_pk_from_RSA ,
+.Nm rs256_pk_from_ptr ,
+.Nm rs256_pk_to_EVP_PKEY
+.Nd FIDO 2 COSE RS256 API
+.Sh SYNOPSIS
+.In openssl/rsa.h
+.In fido/rs256.h
+.Ft rs256_pk_t *
+.Fn rs256_pk_new "void"
+.Ft void
+.Fn rs256_pk_free "rs256_pk_t **pkp"
+.Ft int
+.Fn rs256_pk_from_RSA "rs256_pk_t *pk" "const RSA *rsa"
+.Ft int
+.Fn rs256_pk_from_ptr "rs256_pk_t *pk" "const void *ptr" "size_t len"
+.Ft EVP_PKEY *
+.Fn rs256_pk_to_EVP_PKEY "const rs256_pk_t *pk"
+.Sh DESCRIPTION
+RS256 is the name given in the CBOR Object Signing and Encryption
+(COSE) RFC to PKCS#1.5 2048-bit RSA with SHA-256.
+The COSE RS256 API of
+.Em libfido2
+is an auxiliary API with routines to convert between the different
+RSA public key types used in
+.Em libfido2
+and
+.Em OpenSSL .
+.Pp
+In
+.Em libfido2 ,
+RS256 public keys are abstracted by the
+.Vt rs256_pk_t
+type.
+.Pp
+The
+.Fn rs256_pk_new
+function returns a pointer to a newly allocated, empty
+.Vt rs256_pk_t
+type.
+If memory cannot be allocated, NULL is returned.
+.Pp
+The
+.Fn rs256_pk_free
+function releases the memory backing
+.Fa *pkp ,
+where
+.Fa *pkp
+must have been previously allocated by
+.Fn rs256_pk_new .
+On return,
+.Fa *pkp
+is set to NULL.
+Either
+.Fa pkp
+or
+.Fa *pkp
+may be NULL, in which case
+.Fn rs256_pk_free
+is a NOP.
+.Pp
+The
+.Fn rs256_pk_from_RSA
+function fills
+.Fa pk
+with the contents of
+.Fa rsa .
+No references to
+.Fa rsa
+are kept.
+.Pp
+The
+.Fn rs256_pk_from_ptr
+function fills
+.Fa pk
+with the contents of
+.Fa ptr ,
+where
+.Fa ptr
+points to
+.Fa len
+bytes.
+No references to
+.Fa ptr
+are kept.
+.Pp
+The
+.Fn rs256_pk_to_EVP_PKEY
+function converts
+.Fa pk
+to a newly allocated
+.Fa EVP_PKEY
+type with a reference count of 1.
+No internal references to the returned pointer are kept.
+If an error occurs,
+.Fn rs256_pk_to_EVP_PKEY
+returns NULL.
+.Sh RETURN VALUES
+The
+.Fn rs256_pk_from_RSA
+and
+.Fn rs256_pk_from_ptr
+functions return
+.Dv FIDO_OK
+on success.
+On error, a different error code defined in
+.In fido/err.h
+is returned.
+.Sh SEE ALSO
+.Xr eddsa_pk_new 3 ,
+.Xr es256_pk_new 3 ,
+.Xr fido_assert_verify 3 ,
+.Xr fido_cred_pubkey_ptr 3

diff --git a/man/rs256_pk_new.3 b/man/rs256_pk_new.3 new file mode 100644 index 0000000..4ad0ebe --- /dev/null +++ b/man/rs256_pk_new.3
@@ -0,0 +1,122 @@
	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
	29	RS256 is the name given in the CBOR Object Signing and Encryption
	30	(COSE) RFC to PKCS#1.5 2048-bit RSA with SHA-256.
	31	The COSE RS256 API of
	32	.Em libfido2
	33	is an auxiliary API with routines to convert between the different
	34	RSA public key types used in
	35	.Em libfido2
	36	and
	37	.Em OpenSSL .
	38	.Pp
	39	In
	40	.Em libfido2 ,
	41	RS256 public keys are abstracted by the
	42	.Vt rs256_pk_t
	43	type.
	44	.Pp
	45	The
	46	.Fn rs256_pk_new
	47	function returns a pointer to a newly allocated, empty
	48	.Vt rs256_pk_t
	49	type.
	50	If memory cannot be allocated, NULL is returned.
	51	.Pp
	52	The
	53	.Fn rs256_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 rs256_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 rs256_pk_free
	69	is a NOP.
	70	.Pp
	71	The
	72	.Fn rs256_pk_from_RSA
	73	function fills
	74	.Fa pk
	75	with the contents of
	76	.Fa rsa .
	77	No references to
	78	.Fa rsa
	79	are kept.
	80	.Pp
	81	The
	82	.Fn rs256_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 rs256_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 rs256_pk_to_EVP_PKEY
	106	returns NULL.
	107	.Sh RETURN VALUES
	108	The
	109	.Fn rs256_pk_from_RSA
	110	and
	111	.Fn rs256_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 eddsa_pk_new 3 ,
	120	.Xr es256_pk_new 3 ,
	121	.Xr fido_assert_verify 3 ,
	122	.Xr fido_cred_pubkey_ptr 3