1 files changed, 122 insertions, 0 deletions
diff --git a/man/eddsa_pk_new.3 b/man/eddsa_pk_new.3
new file mode 100644
index 0000000..65bf9a9
--- /dev/null
+++ b/man/eddsa_pk_new.3
@@ -0,0 +1,122 @@
+.\" Copyright (c) 2019 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 15 2019 $
+.Dt EDDSA_PK_NEW 3
+.Os
+.Sh NAME
+.Nm eddsa_pk_new ,
+.Nm eddsa_pk_free ,
+.Nm eddsa_pk_from_EVP_PKEY ,
+.Nm eddsa_pk_from_ptr ,
+.Nm eddsa_pk_to_EVP_PKEY
+.Nd FIDO 2 COSE EDDSA API
+.Sh SYNOPSIS
+.In openssl/evp.h
+.In fido/eddsa.h
+.Ft eddsa_pk_t *
+.Fn eddsa_pk_new "void"
+.Ft void
+.Fn eddsa_pk_free "eddsa_pk_t **pkp"
+.Ft int
+.Fn eddsa_pk_from_EVP_PKEY "eddsa_pk_t *pk" "const EVP_PKEY *pkey"
+.Ft int
+.Fn eddsa_pk_from_ptr "eddsa_pk_t *pk" "const void *ptr" "size_t len"
+.Ft EVP_PKEY *
+.Fn eddsa_pk_to_EVP_PKEY "const eddsa_pk_t *pk"
+.Sh DESCRIPTION
+EDDSA is the name given in the CBOR Object Signing and Encryption
+(COSE) RFC to EDDSA over Curve25519 with SHA-512.
+The COSE EDDSA API of
+.Em libfido2
+is an auxiliary API with routines to convert between the different
+EDDSA public key types used in
+.Em libfido2
+and
+.Em OpenSSL .
+.Pp
+In
+.Em libfido2 ,
+EDDSA public keys are abstracted by the
+.Vt eddsa_pk_t
+type.
+.Pp
+The
+.Fn eddsa_pk_new
+function returns a pointer to a newly allocated, empty
+.Vt eddsa_pk_t
+type.
+If memory cannot be allocated, NULL is returned.
+.Pp
+The
+.Fn eddsa_pk_free
+function releases the memory backing
+.Fa *pkp ,
+where
+.Fa *pkp
+must have been previously allocated by
+.Fn eddsa_pk_new .
+On return,
+.Fa *pkp
+is set to NULL.
+Either
+.Fa pkp
+or
+.Fa *pkp
+may be NULL, in which case
+.Fn eddsa_pk_free
+is a NOP.
+.Pp
+The
+.Fn eddsa_pk_from_EVP_PKEY
+function fills
+.Fa pk
+with the contents of
+.Fa pkey .
+No references to
+.Fa pkey
+are kept.
+.Pp
+The
+.Fn eddsa_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 eddsa_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 eddsa_pk_to_EVP_PKEY
+returns NULL.
+.Sh RETURN VALUES
+The
+.Fn eddsa_pk_from_EC_KEY
+and
+.Fn eddsa_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 es256_pk_new 3 ,
+.Xr fido_assert_verify 3 ,
+.Xr fido_cred_pubkey_ptr 3 ,
+.Xr rs256_pk_new 3

diff --git a/man/eddsa_pk_new.3 b/man/eddsa_pk_new.3 new file mode 100644 index 0000000..65bf9a9 --- /dev/null +++ b/man/eddsa_pk_new.3
@@ -0,0 +1,122 @@
	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 FIDO 2 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_EC_KEY
	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