diff options
Diffstat (limited to 'man/es256_pk_new.3')
-rw-r--r-- | man/es256_pk_new.3 | 122 |
1 files changed, 122 insertions, 0 deletions
diff --git a/man/es256_pk_new.3 b/man/es256_pk_new.3 new file mode 100644 index 0000000..48eda0b --- /dev/null +++ b/man/es256_pk_new.3 | |||
@@ -0,0 +1,122 @@ | |||
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 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_ptr , | ||
13 | .Nm es256_pk_to_EVP_PKEY | ||
14 | .Nd FIDO 2 COSE ES256 API | ||
15 | .Sh SYNOPSIS | ||
16 | .In openssl/ec.h | ||
17 | .In fido/es256.h | ||
18 | .Ft es256_pk_t * | ||
19 | .Fn es256_pk_new "void" | ||
20 | .Ft void | ||
21 | .Fn es256_pk_free "es256_pk_t **pkp" | ||
22 | .Ft int | ||
23 | .Fn es256_pk_from_EC_KEY "es256_pk_t *pk" "const EC_KEY *ec" | ||
24 | .Ft int | ||
25 | .Fn es256_pk_from_ptr "es256_pk_t *pk" "const void *ptr" "size_t len" | ||
26 | .Ft EVP_PKEY * | ||
27 | .Fn es256_pk_to_EVP_PKEY "const es256_pk_t *pk" | ||
28 | .Sh DESCRIPTION | ||
29 | ES256 is the name given in the CBOR Object Signing and Encryption | ||
30 | (COSE) RFC to ECDSA over P-256 with SHA-256. | ||
31 | The COSE ES256 API of | ||
32 | .Em libfido2 | ||
33 | is an auxiliary API with routines to convert between the different | ||
34 | ECDSA public key types used in | ||
35 | .Em libfido2 | ||
36 | and | ||
37 | .Em OpenSSL . | ||
38 | .Pp | ||
39 | In | ||
40 | .Em libfido2 , | ||
41 | ES256 public keys are abstracted by the | ||
42 | .Vt es256_pk_t | ||
43 | type. | ||
44 | .Pp | ||
45 | The | ||
46 | .Fn es256_pk_new | ||
47 | function returns a pointer to a newly allocated, empty | ||
48 | .Vt es256_pk_t | ||
49 | type. | ||
50 | If memory cannot be allocated, NULL is returned. | ||
51 | .Pp | ||
52 | The | ||
53 | .Fn es256_pk_free | ||
54 | function releases the memory backing | ||
55 | .Fa *pkp , | ||
56 | where | ||
57 | .Fa *pkp | ||
58 | must have been previously allocated by | ||
59 | .Fn es256_pk_new . | ||
60 | On return, | ||
61 | .Fa *pkp | ||
62 | is set to NULL. | ||
63 | Either | ||
64 | .Fa pkp | ||
65 | or | ||
66 | .Fa *pkp | ||
67 | may be NULL, in which case | ||
68 | .Fn es256_pk_free | ||
69 | is a NOP. | ||
70 | .Pp | ||
71 | The | ||
72 | .Fn es256_pk_from_EC_KEY | ||
73 | function fills | ||
74 | .Fa pk | ||
75 | with the contents of | ||
76 | .Fa ec . | ||
77 | No references to | ||
78 | .Fa ec | ||
79 | are kept. | ||
80 | .Pp | ||
81 | The | ||
82 | .Fn es256_pk_from_ptr | ||
83 | function fills | ||
84 | .Fa pk | ||
85 | with the contents of | ||
86 | .Fa ptr , | ||
87 | where | ||
88 | .Fa ptr | ||
89 | points to | ||
90 | .Fa len | ||
91 | bytes. | ||
92 | No references to | ||
93 | .Fa ptr | ||
94 | are kept. | ||
95 | .Pp | ||
96 | The | ||
97 | .Fn es256_pk_to_EVP_PKEY | ||
98 | function converts | ||
99 | .Fa pk | ||
100 | to a newly allocated | ||
101 | .Fa EVP_PKEY | ||
102 | type with a reference count of 1. | ||
103 | No internal references to the returned pointer are kept. | ||
104 | If an error occurs, | ||
105 | .Fn es256_pk_to_EVP_PKEY | ||
106 | returns NULL. | ||
107 | .Sh RETURN VALUES | ||
108 | The | ||
109 | .Fn es256_pk_from_EC_KEY | ||
110 | and | ||
111 | .Fn es256_pk_from_ptr | ||
112 | functions return | ||
113 | .Dv FIDO_OK | ||
114 | on success. | ||
115 | On error, a different error code defined in | ||
116 | .In fido/err.h | ||
117 | is returned. | ||
118 | .Sh SEE ALSO | ||
119 | .Xr eddsa_pk_new 3 , | ||
120 | .Xr fido_assert_verify 3 , | ||
121 | .Xr fido_cred_pubkey_ptr 3 , | ||
122 | .Xr rs256_pk_new 3 | ||