.\" 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: February 7 2020 $
.Dt FIDO_CRED_SET_AUTHDATA 3
.Os
.Sh NAME
.Nm fido_cred_set_authdata ,
.Nm fido_cred_set_authdata_raw ,
.Nm fido_cred_set_x509 ,
.Nm fido_cred_set_sig ,
.Nm fido_cred_set_clientdata_hash ,
.Nm fido_cred_set_rp ,
.Nm fido_cred_set_user ,
.Nm fido_cred_set_extensions ,
.Nm fido_cred_set_prot ,
.Nm fido_cred_set_rk ,
.Nm fido_cred_set_uv ,
.Nm fido_cred_set_fmt ,
.Nm fido_cred_set_type
.Nd set parameters of a FIDO 2 credential
.Sh SYNOPSIS
.In fido.h
.Bd -literal
typedef enum {
	FIDO_OPT_OMIT = 0, /* use authenticator's default */
	FIDO_OPT_FALSE,    /* explicitly set option to false */
        FIDO_OPT_TRUE,     /* explicitly set option to true */
} fido_opt_t;
.Ed
.Ft int
.Fn fido_cred_set_authdata "fido_cred_t *cred" "const unsigned char *ptr" "size_t len"
.Ft int
.Fn fido_cred_set_authdata_raw "fido_cred_t *cred" "const unsigned char *ptr" "size_t len"
.Ft int
.Fn fido_cred_set_x509 "fido_cred_t *cred" "const unsigned char *ptr" "size_t len"
.Ft int
.Fn fido_cred_set_sig "fido_cred_t *cred" "const unsigned char *ptr" "size_t len"
.Ft int
.Fn fido_cred_set_clientdata_hash "fido_cred_t *cred" "const unsigned char *ptr" "size_t len"
.Ft int
.Fn fido_cred_set_rp "fido_cred_t *cred" "const char *id" "const char *name"
.Ft int
.Fn fido_cred_set_user "fido_cred_t *cred" "const unsigned char *user_id" "size_t user_id_len" "const char *name" "const char *display_name" "const char *icon"
.Ft int
.Fn fido_cred_set_extensions "fido_cred_t *cred" "int flags"
.Ft int
.Fn fido_cred_set_prot "fido_cred_t *cred" "int prot"
.Ft int
.Fn fido_cred_set_rk "fido_cred_t *cred" "fido_opt_t rk"
.Ft int
.Fn fido_cred_set_uv "fido_cred_t *cred" "fido_opt_t uv"
.Ft int
.Fn fido_cred_set_fmt "fido_cred_t *cred" "const char *ptr"
.Ft int
.Fn fido_cred_set_type "fido_cred_t *cred" "int cose_alg"
.Sh DESCRIPTION
The
.Nm
set of functions define the various parameters of a FIDO 2
credential, allowing a
.Fa fido_cred_t
type to be prepared for a subsequent call to
.Xr fido_dev_make_cred 3
or
.Xr fido_cred_verify 3 .
For the complete specification of a FIDO 2 credential and the format
of its constituent parts, please refer to the Web Authentication
(webauthn) standard.
.Pp
The
.Fn fido_cred_set_authdata ,
.Fn fido_cred_set_x509 ,
.Fn fido_cred_set_sig ,
and
.Fn fido_cred_set_clientdata_hash
functions set the authenticator data, attestation certificate,
signature and client data hash parts of
.Fa cred
to
.Fa ptr ,
where
.Fa ptr
points to
.Fa len
bytes.
A copy of
.Fa ptr
is made, and no references to the passed pointer are kept.
The authenticator data passed to
.Fn fido_cred_set_authdata
must be a CBOR-encoded byte string, as obtained from
.Fn fido_cred_authdata_ptr .
Alternatively, a raw binary blob may be passed to
.Fn fido_cred_set_authdata_raw .
.Pp
The
.Fn fido_cred_set_rp
function sets the relying party
.Fa id
and
.Fa name
parameters of
.Fa cred ,
where
.Fa id
and
.Fa name
are NUL-terminated UTF-8 strings.
The contents of
.Fa id
and
.Fa name
are copied, and no references to the passed pointers are kept.
.Pp
The
.Fn fido_cred_set_user
function sets the user attributes of
.Fa cred ,
where
.Fa user_id
points to
.Fa user_id_len
bytes and
.Fa name ,
.Fa display_name ,
and
.Fa icon
are NUL-terminated UTF-8 strings.
The contents of
.Fa user_id ,
.Fa name ,
.Fa display_name ,
and
.Fa icon
are copied, and no references to the passed pointers are kept.
Previously set user attributes are flushed.
The
.Fa user_id ,
.Fa name ,
.Fa display_name ,
and
.Fa icon
parameters may be NULL.
.Pp
The
.Fn fido_cred_set_extensions
function sets the extensions of
.Fa cred
to the bitmask
.Fa flags .
At the moment, only the
.Dv FIDO_EXT_HMAC_SECRET
and
.Dv FIDO_EXT_CRED_PROTECT
extensions are supported.
If
.Fa flags
is zero, the extensions of
.Fa cred
are cleared.
.Pp
The
.Fn fido_cred_set_prot
function sets the protection of
.Fa cred
to the scalar
.Fa prot .
At the moment, only the
.Dv FIDO_CRED_PROT_UV_OPTIONAL ,
.Dv FIDO_CRED_PROT_UV_OPTIONAL_WITH_ID ,
and
.Dv FIDO_CRED_PROT_UV_REQUIRED
protections are supported.
If
.Fa prot
is zero, the protection of
.Fa cred
is cleared.
.Pp
The
.Fn fido_cred_set_rk
and
.Fn fido_cred_set_uv
functions set the
.Em rk
(resident key)
and
.Em uv
(user verification)
attributes of
.Fa cred .
Both are
.Dv FIDO_OPT_OMIT
by default, allowing the authenticator to use its default settings.
.Pp
The
.Fn fido_cred_set_fmt
function sets the format of
.Fa cred
to
.Fa fmt ,
where
.Fa fmt
must be either
.Vt "packed"
(the format used in FIDO 2)
or
.Vt "fido-u2f"
(the format used by U2F).
A copy of
.Fa fmt
is made, and no references to the passed pointer are kept.
Note that not all authenticators support FIDO2 and therefore may not
be able to generate
.Vt "packed" .
.Pp
The
.Fn fido_cred_set_type
function sets the type of
.Fa cred to
.Fa cose_alg ,
where
.Fa cose_alg
is
.Dv COSE_ES256 ,
.Dv COSE_RS256 ,
or
.Dv COSE_EDDSA .
The type of a credential may only be set once.
Note that not all authenticators support COSE_RS256 or COSE_EDDSA.
.Pp
Use of the
.Nm
set of functions may happen in two distinct situations:
when generating a new credential on a FIDO device, prior to
.Xr fido_dev_make_cred 3
(i.e, in the context of a FIDO client), or when validating
a generated credential using
.Xr fido_cred_verify 3
(i.e, in the context of a FIDO server).
.Pp
For a complete description of the generation of a FIDO 2 credential
and its verification, please refer to the FIDO 2 specification.
A concrete utilisation example of the
.Nm
set of functions can be found in the
.Pa cred.c
example shipped with
.Em libfido2 .
.Sh RETURN VALUES
The error codes returned by the
.Nm
set of functions are defined in
.In fido/err.h .
On success,
.Dv FIDO_OK
is returned.
.Sh SEE ALSO
.Xr fido_cred_exclude 3 ,
.Xr fido_cred_verify 3 ,
.Xr fido_dev_make_cred 3