1 files changed, 122 insertions, 0 deletions
diff --git a/man/es256_pk_new.3 b/man/es256_pk_new.3
new file mode 100644
index 0000000..48eda0b
--- /dev/null
+++ b/man/es256_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 ES256_PK_NEW 3
+.Os
+.Sh NAME
+.Nm es256_pk_new ,
+.Nm es256_pk_free ,
+.Nm es256_pk_from_EC_KEY ,
+.Nm es256_pk_from_ptr ,
+.Nm es256_pk_to_EVP_PKEY
+.Nd FIDO 2 COSE ES256 API
+.Sh SYNOPSIS
+.In openssl/ec.h
+.In fido/es256.h
+.Ft es256_pk_t *
+.Fn es256_pk_new "void"
+.Ft void
+.Fn es256_pk_free "es256_pk_t **pkp"
+.Ft int
+.Fn es256_pk_from_EC_KEY "es256_pk_t *pk" "const EC_KEY *ec"
+.Ft int
+.Fn es256_pk_from_ptr "es256_pk_t *pk" "const void *ptr" "size_t len"
+.Ft EVP_PKEY *
+.Fn es256_pk_to_EVP_PKEY "const es256_pk_t *pk"
+.Sh DESCRIPTION
+ES256 is the name given in the CBOR Object Signing and Encryption
+(COSE) RFC to ECDSA over P-256 with SHA-256.
+The COSE ES256 API of
+.Em libfido2
+is an auxiliary API with routines to convert between the different
+ECDSA public key types used in
+.Em libfido2
+and
+.Em OpenSSL .
+.Pp
+In
+.Em libfido2 ,
+ES256 public keys are abstracted by the
+.Vt es256_pk_t
+type.
+.Pp
+The
+.Fn es256_pk_new
+function returns a pointer to a newly allocated, empty
+.Vt es256_pk_t
+type.
+If memory cannot be allocated, NULL is returned.
+.Pp
+The
+.Fn es256_pk_free
+function releases the memory backing
+.Fa *pkp ,
+where
+.Fa *pkp
+must have been previously allocated by
+.Fn es256_pk_new .
+On return,
+.Fa *pkp
+is set to NULL.
+Either
+.Fa pkp
+or
+.Fa *pkp
+may be NULL, in which case
+.Fn es256_pk_free
+is a NOP.
+.Pp
+The
+.Fn es256_pk_from_EC_KEY
+function fills
+.Fa pk
+with the contents of
+.Fa ec .
+No references to
+.Fa ec
+are kept.
+.Pp
+The
+.Fn es256_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 es256_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 es256_pk_to_EVP_PKEY
+returns NULL.
+.Sh RETURN VALUES
+The
+.Fn es256_pk_from_EC_KEY
+and
+.Fn es256_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 fido_assert_verify 3 ,
+.Xr fido_cred_pubkey_ptr 3 ,
+.Xr rs256_pk_new 3

diff --git a/man/es256_pk_new.3 b/man/es256_pk_new.3 new file mode 100644 index 0000000..48eda0b --- /dev/null +++ b/man/es256_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 ES256_PK_NEW 3
	7	.Os
	8	.Sh NAME
	9	.Nm es256_pk_new ,
	10	.Nm es256_pk_free ,
	11	.Nm es256_pk_from_EC_KEY ,
	12	.Nm es256_pk_from_ptr ,
	13	.Nm es256_pk_to_EVP_PKEY
	14	.Nd FIDO 2 COSE ES256 API
	15	.Sh SYNOPSIS
	16	.In openssl/ec.h
	17	.In fido/es256.h
	18	.Ft es256_pk_t *
	19	.Fn es256_pk_new "void"
	20	.Ft void
	21	.Fn es256_pk_free "es256_pk_t **pkp"
	22	.Ft int
	23	.Fn es256_pk_from_EC_KEY "es256_pk_t pk" "const EC_KEY ec"
	24	.Ft int
	25	.Fn es256_pk_from_ptr "es256_pk_t pk" "const void ptr" "size_t len"
	26	.Ft EVP_PKEY *
	27	.Fn es256_pk_to_EVP_PKEY "const es256_pk_t *pk"
	28	.Sh DESCRIPTION
	29	ES256 is the name given in the CBOR Object Signing and Encryption
	30	(COSE) RFC to ECDSA over P-256 with SHA-256.
	31	The COSE ES256 API of
	32	.Em libfido2
	33	is an auxiliary API with routines to convert between the different
	34	ECDSA public key types used in
	35	.Em libfido2
	36	and
	37	.Em OpenSSL .
	38	.Pp
	39	In
	40	.Em libfido2 ,
	41	ES256 public keys are abstracted by the
	42	.Vt es256_pk_t
	43	type.
	44	.Pp
	45	The
	46	.Fn es256_pk_new
	47	function returns a pointer to a newly allocated, empty
	48	.Vt es256_pk_t
	49	type.
	50	If memory cannot be allocated, NULL is returned.
	51	.Pp
	52	The
	53	.Fn es256_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 es256_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 es256_pk_free
	69	is a NOP.
	70	.Pp
	71	The
	72	.Fn es256_pk_from_EC_KEY
	73	function fills
	74	.Fa pk
	75	with the contents of
	76	.Fa ec .
	77	No references to
	78	.Fa ec
	79	are kept.
	80	.Pp
	81	The
	82	.Fn es256_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 es256_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 es256_pk_to_EVP_PKEY
	106	returns NULL.
	107	.Sh RETURN VALUES
	108	The
	109	.Fn es256_pk_from_EC_KEY
	110	and
	111	.Fn es256_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 fido_assert_verify 3 ,
	121	.Xr fido_cred_pubkey_ptr 3 ,
	122	.Xr rs256_pk_new 3