xref: /freebsd/contrib/libfido2/man/es256_pk_new.3 (revision e6bfd18d21b225af6a0ed67ceeaf1293b7b9eba5)
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 24 2018 $
6.Dt ES256_PK_NEW 3
7.Os
8.Sh NAME
9.Nm es256_pk_new ,
10.Nm es256_pk_free ,
11.Nm es256_pk_from_EC_KEY ,
12.Nm es256_pk_from_EVP_PKEY ,
13.Nm es256_pk_from_ptr ,
14.Nm es256_pk_to_EVP_PKEY
15.Nd FIDO2 COSE ES256 API
16.Sh SYNOPSIS
17.In openssl/ec.h
18.In fido/es256.h
19.Ft es256_pk_t *
20.Fn es256_pk_new "void"
21.Ft void
22.Fn es256_pk_free "es256_pk_t **pkp"
23.Ft int
24.Fn es256_pk_from_EC_KEY "es256_pk_t *pk" "const EC_KEY *ec"
25.Ft int
26.Fn es256_pk_from_EVP_PKEY "es256_pk_t *pk" "const EVP_PKEY *pkey"
27.Ft int
28.Fn es256_pk_from_ptr "es256_pk_t *pk" "const void *ptr" "size_t len"
29.Ft EVP_PKEY *
30.Fn es256_pk_to_EVP_PKEY "const es256_pk_t *pk"
31.Sh DESCRIPTION
32ES256 is the name given in the CBOR Object Signing and Encryption
33(COSE) RFC to ECDSA over P-256 with SHA-256.
34The COSE ES256 API of
35.Em libfido2
36is an auxiliary API with routines to convert between the different
37ECDSA public key types used in
38.Em libfido2
39and
40.Em OpenSSL .
41.Pp
42In
43.Em libfido2 ,
44ES256 public keys are abstracted by the
45.Vt es256_pk_t
46type.
47.Pp
48The
49.Fn es256_pk_new
50function returns a pointer to a newly allocated, empty
51.Vt es256_pk_t
52type.
53If memory cannot be allocated, NULL is returned.
54.Pp
55The
56.Fn es256_pk_free
57function releases the memory backing
58.Fa *pkp ,
59where
60.Fa *pkp
61must have been previously allocated by
62.Fn es256_pk_new .
63On return,
64.Fa *pkp
65is set to NULL.
66Either
67.Fa pkp
68or
69.Fa *pkp
70may be NULL, in which case
71.Fn es256_pk_free
72is a NOP.
73.Pp
74The
75.Fn es256_pk_from_EC_KEY
76function fills
77.Fa pk
78with the contents of
79.Fa ec .
80No references to
81.Fa ec
82are kept.
83.Pp
84The
85.Fn es256_pk_from_EVP_PKEY
86function fills
87.Fa pk
88with the contents of
89.Fa pkey .
90No references to
91.Fa pkey
92are kept.
93.Pp
94The
95.Fn es256_pk_from_ptr
96function fills
97.Fa pk
98with the contents of
99.Fa ptr ,
100where
101.Fa ptr
102points to
103.Fa len
104bytes.
105The
106.Fa ptr
107pointer may point to an uncompressed point, or to the
108concatenation of the x and y coordinates.
109No references to
110.Fa ptr
111are kept.
112.Pp
113The
114.Fn es256_pk_to_EVP_PKEY
115function converts
116.Fa pk
117to a newly allocated
118.Fa EVP_PKEY
119type with a reference count of 1.
120No internal references to the returned pointer are kept.
121If an error occurs,
122.Fn es256_pk_to_EVP_PKEY
123returns NULL.
124.Sh RETURN VALUES
125The
126.Fn es256_pk_from_EC_KEY ,
127.Fn es256_pk_from_EVP_PKEY ,
128and
129.Fn es256_pk_from_ptr
130functions return
131.Dv FIDO_OK
132on success.
133On error, a different error code defined in
134.In fido/err.h
135is returned.
136.Sh SEE ALSO
137.Xr eddsa_pk_new 3 ,
138.Xr fido_assert_verify 3 ,
139.Xr fido_cred_pubkey_ptr 3 ,
140.Xr rs256_pk_new 3
141