1 files changed, 157 insertions, 0 deletions
diff --git a/man/fido_cred_new.3 b/man/fido_cred_new.3
new file mode 100644
index 0000000..47eeba8
--- /dev/null
+++ b/man/fido_cred_new.3
@@ -0,0 +1,157 @@
+.\" 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 23 2018 $
+.Dt FIDO_CRED_NEW 3
+.Os
+.Sh NAME
+.Nm fido_cred_new ,
+.Nm fido_cred_free ,
+.Nm fido_cred_fmt ,
+.Nm fido_cred_authdata_ptr ,
+.Nm fido_cred_clientdata_hash_ptr ,
+.Nm fido_cred_id_ptr ,
+.Nm fido_cred_pubkey_ptr ,
+.Nm fido_cred_sig_ptr ,
+.Nm fido_cred_x5c_ptr ,
+.Nm fido_cred_authdata_len ,
+.Nm fido_cred_clientdata_hash_len ,
+.Nm fido_cred_id_len ,
+.Nm fido_cred_pubkey_len ,
+.Nm fido_cred_sig_len ,
+.Nm fido_cred_x5c_len
+.Nd FIDO 2 credential API
+.Sh SYNOPSIS
+.In fido.h
+.Ft fido_cred_t *
+.Fn fido_cred_new "void"
+.Ft void
+.Fn fido_cred_free "fido_cred_t **cred_p"
+.Ft const char *
+.Fn fido_cred_fmt "const fido_cred_t *cred"
+.Ft const unsigned char *
+.Fn fido_cred_authdata_ptr "const fido_cred_t *cred"
+.Ft const unsigned char *
+.Fn fido_cred_clientdata_hash_ptr "const fido_cred_t *cred"
+.Ft const unsigned char *
+.Fn fido_cred_id_ptr "const fido_cred_t *cred"
+.Ft const unsigned char *
+.Fn fido_cred_pubkey_ptr "const fido_cred_t *cred"
+.Ft const unsigned char *
+.Fn fido_cred_sig_ptr "const fido_cred_t *cred"
+.Ft const unsigned char *
+.Fn fido_cred_x5c_ptr "const fido_cred_t *cred"
+.Ft size_t
+.Fn fido_cred_authdata_len "const fido_cred_t *cred"
+.Ft size_t
+.Fn fido_cred_clientdata_hash_len "const fido_cred_t *cred"
+.Ft size_t
+.Fn fido_cred_id_len "const fido_cred_t *cred"
+.Ft size_t
+.Fn fido_cred_pubkey_len "const fido_cred_t *cred"
+.Ft size_t
+.Fn fido_cred_sig_len "const fido_cred_t *cred"
+.Ft size_t
+.Fn fido_cred_x5c_len "const fido_cred_t *cred"
+.Sh DESCRIPTION
+FIDO 2 credentials are abstracted in
+.Em libfido2
+by the
+.Vt fido_cred_t
+type.
+The functions described in this page allow a
+.Vt fido_cred_t
+type to be allocated, deallocated, and inspected.
+For other operations on
+.Vt fido_cred_t ,
+please refer to
+.Xr fido_cred_set_authdata 3 ,
+.Xr fido_cred_exclude 3 ,
+.Xr fido_cred_verify 3 ,
+and
+.Xr fido_dev_make_cred 3 .
+.Pp
+The
+.Fn fido_cred_new
+function returns a pointer to a newly allocated, empty
+.Vt fido_cred_t
+type.
+If memory cannot be allocated, NULL is returned.
+.Pp
+The
+.Fn fido_cred_free
+function releases the memory backing
+.Fa *cred_p ,
+where
+.Fa *cred_p
+must have been previously allocated by
+.Fn fido_cred_new .
+On return,
+.Fa *cred_p
+is set to NULL.
+Either
+.Fa cred_p
+or
+.Fa *cred_p
+may be NULL, in which case
+.Fn fido_cred_free
+is a NOP.
+.Pp
+The
+.Fn fido_cred_fmt
+function returns a pointer to a NUL-terminated string containing
+the format of
+.Fa cred ,
+or NULL if
+.Fa cred
+does not have a format set.
+.Pp
+The
+.Fn fido_cred_authdata_ptr ,
+.Fn fido_cred_clientdata_hash_ptr ,
+.Fn fido_cred_id_ptr ,
+.Fn fido_cred_pubkey_ptr ,
+.Fn fido_cred_sig_ptr ,
+and
+.Fn fido_cred_x5c_ptr
+functions return pointers to the authenticator data, client data
+hash, ID, public key, signature and x509 certificate parts of
+.Fa cred ,
+or NULL if the respective entry is not set.
+.Pp
+The corresponding length can be obtained by
+.Fn fido_cred_authdata_len ,
+.Fn fido_cred_clientdata_hash_len ,
+.Fn fido_cred_id_len ,
+.Fn fido_cred_pubkey_len ,
+and
+.Fn fido_cred_sig_len .
+.Pp
+The authenticator data, x509 certificate, and signature parts of a
+credential are typically passed to a FIDO 2 server for verification.
+.Sh RETURN VALUES
+The authenticator data returned by
+.Fn fido_cred_authdata_ptr
+is a CBOR-encoded byte string, as obtained from the authenticator.
+.Pp
+If not NULL, pointers returned by
+.Fn fido_cred_fmt ,
+.Fn fido_cred_authdata_ptr ,
+.Fn fido_cred_clientdata_hash_ptr ,
+.Fn fido_cred_id_ptr ,
+.Fn fido_cred_pubkey_ptr ,
+.Fn fido_cred_sig_ptr ,
+and
+.Fn fido_cred_x5c_ptr
+are guaranteed to exist until any API function that takes
+.Fa cred
+without the
+.Em const
+qualifier is invoked.
+.Sh SEE ALSO
+.Xr fido_cred_exclude 3 ,
+.Xr fido_cred_set_authdata 3 ,
+.Xr fido_cred_verify 3 ,
+.Xr fido_credman_metadata_new 3 ,
+.Xr fido_dev_make_cred 3

diff --git a/man/fido_cred_new.3 b/man/fido_cred_new.3 new file mode 100644 index 0000000..47eeba8 --- /dev/null +++ b/man/fido_cred_new.3
@@ -0,0 +1,157 @@
	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 23 2018 $
	6	.Dt FIDO_CRED_NEW 3
	7	.Os
	8	.Sh NAME
	9	.Nm fido_cred_new ,
	10	.Nm fido_cred_free ,
	11	.Nm fido_cred_fmt ,
	12	.Nm fido_cred_authdata_ptr ,
	13	.Nm fido_cred_clientdata_hash_ptr ,
	14	.Nm fido_cred_id_ptr ,
	15	.Nm fido_cred_pubkey_ptr ,
	16	.Nm fido_cred_sig_ptr ,
	17	.Nm fido_cred_x5c_ptr ,
	18	.Nm fido_cred_authdata_len ,
	19	.Nm fido_cred_clientdata_hash_len ,
	20	.Nm fido_cred_id_len ,
	21	.Nm fido_cred_pubkey_len ,
	22	.Nm fido_cred_sig_len ,
	23	.Nm fido_cred_x5c_len
	24	.Nd FIDO 2 credential API
	25	.Sh SYNOPSIS
	26	.In fido.h
	27	.Ft fido_cred_t *
	28	.Fn fido_cred_new "void"
	29	.Ft void
	30	.Fn fido_cred_free "fido_cred_t **cred_p"
	31	.Ft const char *
	32	.Fn fido_cred_fmt "const fido_cred_t *cred"
	33	.Ft const unsigned char *
	34	.Fn fido_cred_authdata_ptr "const fido_cred_t *cred"
	35	.Ft const unsigned char *
	36	.Fn fido_cred_clientdata_hash_ptr "const fido_cred_t *cred"
	37	.Ft const unsigned char *
	38	.Fn fido_cred_id_ptr "const fido_cred_t *cred"
	39	.Ft const unsigned char *
	40	.Fn fido_cred_pubkey_ptr "const fido_cred_t *cred"
	41	.Ft const unsigned char *
	42	.Fn fido_cred_sig_ptr "const fido_cred_t *cred"
	43	.Ft const unsigned char *
	44	.Fn fido_cred_x5c_ptr "const fido_cred_t *cred"
	45	.Ft size_t
	46	.Fn fido_cred_authdata_len "const fido_cred_t *cred"
	47	.Ft size_t
	48	.Fn fido_cred_clientdata_hash_len "const fido_cred_t *cred"
	49	.Ft size_t
	50	.Fn fido_cred_id_len "const fido_cred_t *cred"
	51	.Ft size_t
	52	.Fn fido_cred_pubkey_len "const fido_cred_t *cred"
	53	.Ft size_t
	54	.Fn fido_cred_sig_len "const fido_cred_t *cred"
	55	.Ft size_t
	56	.Fn fido_cred_x5c_len "const fido_cred_t *cred"
	57	.Sh DESCRIPTION
	58	FIDO 2 credentials are abstracted in
	59	.Em libfido2
	60	by the
	61	.Vt fido_cred_t
	62	type.
	63	The functions described in this page allow a
	64	.Vt fido_cred_t
	65	type to be allocated, deallocated, and inspected.
	66	For other operations on
	67	.Vt fido_cred_t ,
	68	please refer to
	69	.Xr fido_cred_set_authdata 3 ,
	70	.Xr fido_cred_exclude 3 ,
	71	.Xr fido_cred_verify 3 ,
	72	and
	73	.Xr fido_dev_make_cred 3 .
	74	.Pp
	75	The
	76	.Fn fido_cred_new
	77	function returns a pointer to a newly allocated, empty
	78	.Vt fido_cred_t
	79	type.
	80	If memory cannot be allocated, NULL is returned.
	81	.Pp
	82	The
	83	.Fn fido_cred_free
	84	function releases the memory backing
	85	.Fa *cred_p ,
	86	where
	87	.Fa *cred_p
	88	must have been previously allocated by
	89	.Fn fido_cred_new .
	90	On return,
	91	.Fa *cred_p
	92	is set to NULL.
	93	Either
	94	.Fa cred_p
	95	or
	96	.Fa *cred_p
	97	may be NULL, in which case
	98	.Fn fido_cred_free
	99	is a NOP.
	100	.Pp
	101	The
	102	.Fn fido_cred_fmt
	103	function returns a pointer to a NUL-terminated string containing
	104	the format of
	105	.Fa cred ,
	106	or NULL if
	107	.Fa cred
	108	does not have a format set.
	109	.Pp
	110	The
	111	.Fn fido_cred_authdata_ptr ,
	112	.Fn fido_cred_clientdata_hash_ptr ,
	113	.Fn fido_cred_id_ptr ,
	114	.Fn fido_cred_pubkey_ptr ,
	115	.Fn fido_cred_sig_ptr ,
	116	and
	117	.Fn fido_cred_x5c_ptr
	118	functions return pointers to the authenticator data, client data
	119	hash, ID, public key, signature and x509 certificate parts of
	120	.Fa cred ,
	121	or NULL if the respective entry is not set.
	122	.Pp
	123	The corresponding length can be obtained by
	124	.Fn fido_cred_authdata_len ,
	125	.Fn fido_cred_clientdata_hash_len ,
	126	.Fn fido_cred_id_len ,
	127	.Fn fido_cred_pubkey_len ,
	128	and
	129	.Fn fido_cred_sig_len .
	130	.Pp
	131	The authenticator data, x509 certificate, and signature parts of a
	132	credential are typically passed to a FIDO 2 server for verification.
	133	.Sh RETURN VALUES
	134	The authenticator data returned by
	135	.Fn fido_cred_authdata_ptr
	136	is a CBOR-encoded byte string, as obtained from the authenticator.
	137	.Pp
	138	If not NULL, pointers returned by
	139	.Fn fido_cred_fmt ,
	140	.Fn fido_cred_authdata_ptr ,
	141	.Fn fido_cred_clientdata_hash_ptr ,
	142	.Fn fido_cred_id_ptr ,
	143	.Fn fido_cred_pubkey_ptr ,
	144	.Fn fido_cred_sig_ptr ,
	145	and
	146	.Fn fido_cred_x5c_ptr
	147	are guaranteed to exist until any API function that takes
	148	.Fa cred
	149	without the
	150	.Em const
	151	qualifier is invoked.
	152	.Sh SEE ALSO
	153	.Xr fido_cred_exclude 3 ,
	154	.Xr fido_cred_set_authdata 3 ,
	155	.Xr fido_cred_verify 3 ,
	156	.Xr fido_credman_metadata_new 3 ,
	157	.Xr fido_dev_make_cred 3