xref: /freebsd/contrib/libfido2/man/fido_cred_verify.3 (revision 02e9120893770924227138ba49df1edb3896112a)
1.\" Copyright (c) 2018-2021 Yubico AB. All rights reserved.
2.\"
3.\" Redistribution and use in source and binary forms, with or without
4.\" modification, are permitted provided that the following conditions are
5.\" met:
6.\"
7.\"    1. Redistributions of source code must retain the above copyright
8.\"       notice, this list of conditions and the following disclaimer.
9.\"    2. Redistributions in binary form must reproduce the above copyright
10.\"       notice, this list of conditions and the following disclaimer in
11.\"       the documentation and/or other materials provided with the
12.\"       distribution.
13.\"
14.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
15.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
16.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
17.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
18.\" HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
19.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
20.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
21.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
22.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
23.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
24.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
25.\"
26.\" SPDX-License-Identifier: BSD-2-Clause
27.\"
28.Dd $Mdocdate: May 23 2018 $
29.Dt FIDO_CRED_VERIFY 3
30.Os
31.Sh NAME
32.Nm fido_cred_verify ,
33.Nm fido_cred_verify_self
34.Nd verify the attestation signature of a FIDO2 credential
35.Sh SYNOPSIS
36.In fido.h
37.Ft int
38.Fn fido_cred_verify "const fido_cred_t *cred"
39.Ft int
40.Fn fido_cred_verify_self "const fido_cred_t *cred"
41.Sh DESCRIPTION
42The
43.Fn fido_cred_verify
44and
45.Fn fido_cred_verify_self
46functions verify whether the attestation signature contained in
47.Fa cred
48matches the attributes of the credential.
49Before using
50.Fn fido_cred_verify
51or
52.Fn fido_cred_verify_self
53in a sensitive context, the reader is strongly encouraged to make
54herself familiar with the FIDO2 credential attestation process
55as defined in the Web Authentication (webauthn) standard.
56.Pp
57The
58.Fn fido_cred_verify
59function verifies whether the client data hash, relying party ID,
60credential ID, type, protection policy, minimum PIN length, and
61resident/discoverable key and user verification attributes of
62.Fa cred
63have been attested by the holder of the private counterpart of
64the public key contained in the credential's x509 certificate.
65.Pp
66Please note that the x509 certificate itself is not verified.
67.Pp
68The attestation statement formats supported by
69.Fn fido_cred_verify
70are
71.Em packed ,
72.Em fido-u2f ,
73and
74.Em tpm .
75The attestation type implemented by
76.Fn fido_cred_verify
77is
78.Em Basic Attestation .
79.Pp
80The
81.Fn fido_cred_verify_self
82function verifies whether the client data hash, relying party ID,
83credential ID, type, protection policy, minimum PIN length, and
84resident/discoverable key and user verification attributes of
85.Fa cred
86have been attested by the holder of the credential's private key.
87.Pp
88The attestation statement formats supported by
89.Fn fido_cred_verify_self
90are
91.Em packed
92and
93.Em fido-u2f .
94The attestation type implemented by
95.Fn fido_cred_verify_self
96is
97.Em Self Attestation .
98.Pp
99Other attestation formats and types are not supported.
100.Sh RETURN VALUES
101The error codes returned by
102.Fn fido_cred_verify
103and
104.Fn fido_cred_verify_self
105are defined in
106.In fido/err.h .
107If
108.Fa cred
109passes verification, then
110.Dv FIDO_OK
111is returned.
112.Sh SEE ALSO
113.Xr fido_cred_new 3 ,
114.Xr fido_cred_set_authdata 3
115