1.\" Copyright (c) 2018-2021 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_pin_minlen ,
12.Nm fido_cred_prot ,
13.Nm fido_cred_fmt ,
14.Nm fido_cred_rp_id ,
15.Nm fido_cred_rp_name ,
16.Nm fido_cred_user_name ,
17.Nm fido_cred_display_name ,
18.Nm fido_cred_authdata_ptr ,
19.Nm fido_cred_authdata_raw_ptr ,
20.Nm fido_cred_clientdata_hash_ptr ,
21.Nm fido_cred_id_ptr ,
22.Nm fido_cred_aaguid_ptr ,
23.Nm fido_cred_largeblob_key_ptr ,
24.Nm fido_cred_pubkey_ptr ,
25.Nm fido_cred_sig_ptr ,
26.Nm fido_cred_user_id_ptr ,
27.Nm fido_cred_x5c_ptr ,
28.Nm fido_cred_attstmt_ptr ,
29.Nm fido_cred_authdata_len ,
30.Nm fido_cred_authdata_raw_len ,
31.Nm fido_cred_clientdata_hash_len ,
32.Nm fido_cred_id_len ,
33.Nm fido_cred_aaguid_len ,
34.Nm fido_cred_largeblob_key_len ,
35.Nm fido_cred_pubkey_len ,
36.Nm fido_cred_sig_len ,
37.Nm fido_cred_user_id_len ,
38.Nm fido_cred_x5c_len ,
39.Nm fido_cred_attstmt_len ,
40.Nm fido_cred_type ,
41.Nm fido_cred_flags ,
42.Nm fido_cred_sigcount
43.Nd FIDO2 credential API
44.Sh SYNOPSIS
45.In fido.h
46.Ft fido_cred_t *
47.Fn fido_cred_new "void"
48.Ft void
49.Fn fido_cred_free "fido_cred_t **cred_p"
50.Ft size_t
51.Fn fido_cred_pin_minlen "const fido_cred_t *cred"
52.Ft int
53.Fn fido_cred_prot "const fido_cred_t *cred"
54.Ft const char *
55.Fn fido_cred_fmt "const fido_cred_t *cred"
56.Ft const char *
57.Fn fido_cred_rp_id "const fido_cred_t *cred"
58.Ft const char *
59.Fn fido_cred_rp_name "const fido_cred_t *cred"
60.Ft const char *
61.Fn fido_cred_user_name "const fido_cred_t *cred"
62.Ft const char *
63.Fn fido_cred_display_name "const fido_cred_t *cred"
64.Ft const unsigned char *
65.Fn fido_cred_authdata_ptr "const fido_cred_t *cred"
66.Ft const unsigned char *
67.Fn fido_cred_authdata_raw_ptr "const fido_cred_t *cred"
68.Ft const unsigned char *
69.Fn fido_cred_clientdata_hash_ptr "const fido_cred_t *cred"
70.Ft const unsigned char *
71.Fn fido_cred_id_ptr "const fido_cred_t *cred"
72.Ft const unsigned char *
73.Fn fido_cred_aaguid_ptr "const fido_cred_t *cred"
74.Ft const unsigned char *
75.Fn fido_cred_largeblob_key_ptr "const fido_cred_t *cred"
76.Ft const unsigned char *
77.Fn fido_cred_pubkey_ptr "const fido_cred_t *cred"
78.Ft const unsigned char *
79.Fn fido_cred_sig_ptr "const fido_cred_t *cred"
80.Ft const unsigned char *
81.Fn fido_cred_user_id_ptr "const fido_cred_t *cred"
82.Ft const unsigned char *
83.Fn fido_cred_x5c_ptr "const fido_cred_t *cred"
84.Ft const unsigned char *
85.Fn fido_cred_attstmt_ptr "const fido_cred_t *cred"
86.Ft size_t
87.Fn fido_cred_authdata_len "const fido_cred_t *cred"
88.Ft size_t
89.Fn fido_cred_authdata_raw_len "const fido_cred_t *cred"
90.Ft size_t
91.Fn fido_cred_clientdata_hash_len "const fido_cred_t *cred"
92.Ft size_t
93.Fn fido_cred_id_len "const fido_cred_t *cred"
94.Ft size_t
95.Fn fido_cred_aaguid_len "const fido_cred_t *cred"
96.Ft size_t
97.Fn fido_cred_largeblob_key_len "const fido_cred_t *cred"
98.Ft size_t
99.Fn fido_cred_pubkey_len "const fido_cred_t *cred"
100.Ft size_t
101.Fn fido_cred_sig_len "const fido_cred_t *cred"
102.Ft size_t
103.Fn fido_cred_user_id_len "const fido_cred_t *cred"
104.Ft size_t
105.Fn fido_cred_x5c_len "const fido_cred_t *cred"
106.Ft size_t
107.Fn fido_cred_attstmt_len "const fido_cred_t *cred"
108.Ft int
109.Fn fido_cred_type "const fido_cred_t *cred"
110.Ft uint8_t
111.Fn fido_cred_flags "const fido_cred_t *cred"
112.Ft uint32_t
113.Fn fido_cred_sigcount "const fido_cred_t *cred"
114.Sh DESCRIPTION
115FIDO2 credentials are abstracted in
116.Em libfido2
117by the
118.Vt fido_cred_t
119type.
120The functions described in this page allow a
121.Vt fido_cred_t
122type to be allocated, deallocated, and inspected.
123For other operations on
124.Vt fido_cred_t ,
125please refer to
126.Xr fido_cred_set_authdata 3 ,
127.Xr fido_cred_exclude 3 ,
128.Xr fido_cred_verify 3 ,
129and
130.Xr fido_dev_make_cred 3 .
131.Pp
132The
133.Fn fido_cred_new
134function returns a pointer to a newly allocated, empty
135.Vt fido_cred_t
136type.
137If memory cannot be allocated, NULL is returned.
138.Pp
139The
140.Fn fido_cred_free
141function releases the memory backing
142.Fa *cred_p ,
143where
144.Fa *cred_p
145must have been previously allocated by
146.Fn fido_cred_new .
147On return,
148.Fa *cred_p
149is set to NULL.
150Either
151.Fa cred_p
152or
153.Fa *cred_p
154may be NULL, in which case
155.Fn fido_cred_free
156is a NOP.
157.Pp
158If the CTAP 2.1
159.Dv FIDO_EXT_MINPINLEN
160extension is enabled on
161.Fa cred ,
162then the
163.Fn fido_cred_pin_minlen
164function returns the minimum PIN length of
165.Fa cred .
166Otherwise,
167.Fn fido_cred_pin_minlen
168returns zero.
169See
170.Xr fido_cred_set_pin_minlen 3
171on how to enable this extension.
172.Pp
173If the CTAP 2.1
174.Dv FIDO_EXT_CRED_PROTECT
175extension is enabled on
176.Fa cred ,
177then the
178.Fn fido_cred_prot
179function returns the protection of
180.Fa cred .
181Otherwise,
182.Fn fido_cred_prot
183returns zero.
184See
185.Xr fido_cred_set_prot 3
186for the protection policies understood by
187.Em libfido2 .
188.Pp
189The
190.Fn fido_cred_fmt
191function returns a pointer to a NUL-terminated string containing
192the format of
193.Fa cred ,
194or NULL if
195.Fa cred
196does not have a format set.
197.Pp
198The
199.Fn fido_cred_rp_id ,
200.Fn fido_cred_rp_name ,
201.Fn fido_cred_user_name ,
202and
203.Fn fido_cred_display_name
204functions return pointers to NUL-terminated strings holding the
205relying party ID, relying party name, user name, and user display
206name attributes of
207.Fa cred ,
208or NULL if the respective entry is not set.
209.Pp
210The
211.Fn fido_cred_authdata_ptr ,
212.Fn fido_cred_authdata_raw_ptr ,
213.Fn fido_cred_clientdata_hash_ptr ,
214.Fn fido_cred_id_ptr ,
215.Fn fido_cred_aaguid_ptr ,
216.Fn fido_cred_largeblob_key_ptr ,
217.Fn fido_cred_pubkey_ptr ,
218.Fn fido_cred_sig_ptr ,
219.Fn fido_cred_user_id_ptr ,
220.Fn fido_cred_x5c_ptr ,
221and
222.Fn fido_cred_attstmt_ptr
223functions return pointers to the CBOR-encoded and raw authenticator
224data, client data hash, ID, authenticator attestation GUID,
225.Dq largeBlobKey ,
226public key, signature, user ID, x509 certificate, and attestation
227statement parts of
228.Fa cred ,
229or NULL if the respective entry is not set.
230.Pp
231The corresponding length can be obtained by
232.Fn fido_cred_authdata_len ,
233.Fn fido_cred_authdata_raw_len ,
234.Fn fido_cred_clientdata_hash_len ,
235.Fn fido_cred_id_len ,
236.Fn fido_cred_aaguid_len ,
237.Fn fido_cred_largeblob_key_len ,
238.Fn fido_cred_pubkey_len ,
239.Fn fido_cred_sig_len ,
240.Fn fido_cred_user_id_len ,
241.Fn fido_cred_x5c_len ,
242and
243.Fn fido_cred_attstmt_len .
244.Pp
245The authenticator data, x509 certificate, and signature parts of a
246credential are typically passed to a FIDO2 server for verification.
247.Pp
248The
249.Fn fido_cred_type
250function returns the COSE algorithm of
251.Fa cred .
252.Pp
253The
254.Fn fido_cred_flags
255function returns the authenticator data flags of
256.Fa cred .
257.Pp
258The
259.Fn fido_cred_sigcount
260function returns the authenticator data signature counter of
261.Fa cred .
262.Sh RETURN VALUES
263The authenticator data returned by
264.Fn fido_cred_authdata_ptr
265is a CBOR-encoded byte string, as obtained from the authenticator.
266To obtain the decoded byte string, use
267.Fn fido_cred_authdata_raw_ptr .
268.Pp
269If not NULL, pointers returned by
270.Fn fido_cred_fmt ,
271.Fn fido_cred_authdata_ptr ,
272.Fn fido_cred_clientdata_hash_ptr ,
273.Fn fido_cred_id_ptr ,
274.Fn fido_cred_aaguid_ptr ,
275.Fn fido_cred_largeblob_key_ptr ,
276.Fn fido_cred_pubkey_ptr ,
277.Fn fido_cred_sig_ptr ,
278and
279.Fn fido_cred_x5c_ptr
280are guaranteed to exist until any API function that takes
281.Fa cred
282without the
283.Em const
284qualifier is invoked.
285.Sh SEE ALSO
286.Xr fido_cred_exclude 3 ,
287.Xr fido_cred_set_authdata 3 ,
288.Xr fido_cred_set_pin_minlen 3 ,
289.Xr fido_cred_set_prot 3 ,
290.Xr fido_cred_verify 3 ,
291.Xr fido_credman_metadata_new 3 ,
292.Xr fido_dev_largeblob_get 3 ,
293.Xr fido_dev_make_cred 3
294