.\" 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_prot ,
.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 int
.Fn fido_cred_prot "fido_cred_t *cred"
.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_prot
function returns the protection of
.Fa cred .
See
.Xr fido_cred_set_prot 3
for the values understood by
.Em libfido2 .
.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