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
|
#ifndef AWS_IO_PKCS11_H
#define AWS_IO_PKCS11_H
/**
* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: Apache-2.0.
*/
#include <aws/io/io.h>
AWS_PUSH_SANE_WARNING_LEVEL
struct aws_allocator;
/**
* Handle to a loaded PKCS#11 library.
*/
struct aws_pkcs11_lib;
/**
* Controls how aws_pkcs11_lib calls C_Initialize() and C_Finalize() on the PKCS#11 library.
*/
enum aws_pkcs11_lib_behavior {
/**
* Default behavior that accommodates most use cases.
* C_Initialize() is called on creation, and "already-initialized" errors are ignored.
* C_Finalize() is never called, just in case another part of your
* application is still using the PKCS#11 library.
*/
AWS_PKCS11_LIB_DEFAULT_BEHAVIOR,
/**
* Skip calling C_Initialize() and C_Finalize().
* Use this if your application has already initialized the PKCS#11 library,
* and you do not want C_Initialize() called again.
*/
AWS_PKCS11_LIB_OMIT_INITIALIZE,
/**
* C_Initialize() is called on creation and C_Finalize() is called on cleanup.
* If C_Initialize() reports that's it's already initialized, this is treated as an error.
* Use this if you need perfect cleanup (ex: running valgrind with --leak-check).
*/
AWS_PKCS11_LIB_STRICT_INITIALIZE_FINALIZE,
};
/* The enum above was misspelled, and later got fixed (pcks11 -> pkcs11).
* This macro maintain backwards compatibility with the old spelling */
#define aws_pcks11_lib_behavior aws_pkcs11_lib_behavior
/**
* Options for aws_pkcs11_lib_new()
*/
struct aws_pkcs11_lib_options {
/**
* Name of PKCS#11 library file to load (UTF-8).
* Zero out if your application is compiled with PKCS#11 symbols linked in.
*/
struct aws_byte_cursor filename;
/**
* Behavior for calling C_Initialize() and C_Finalize() on the PKCS#11 library.
*/
enum aws_pkcs11_lib_behavior initialize_finalize_behavior;
};
AWS_EXTERN_C_BEGIN
/**
* Load and initialize a PKCS#11 library.
* See `aws_pkcs11_lib_options` for options.
*
* If successful a valid pointer is returned. You must call aws_pkcs11_lib_release() when you are done with it.
* If unsuccessful, NULL is returned and an error is set.
*/
AWS_IO_API
struct aws_pkcs11_lib *aws_pkcs11_lib_new(
struct aws_allocator *allocator,
const struct aws_pkcs11_lib_options *options);
/**
* Acquire a reference to a PKCS#11 library, preventing it from being cleaned up.
* You must call aws_pkcs11_lib_release() when you are done with it.
* This function returns whatever was passed in. It cannot fail.
*/
AWS_IO_API
struct aws_pkcs11_lib *aws_pkcs11_lib_acquire(struct aws_pkcs11_lib *pkcs11_lib);
/**
* Release a reference to the PKCS#11 library.
* When the last reference is released, the library is cleaned up.
*/
AWS_IO_API
void aws_pkcs11_lib_release(struct aws_pkcs11_lib *pkcs11_lib);
AWS_EXTERN_C_END
AWS_POP_SANE_WARNING_LEVEL
#endif /* AWS_IO_PKCS11_H */
|
