1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
|
.\" 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
|
