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