TrustedFirmware Git Browser
Code Review Sign In
review.trustedfirmware.org / mirror / mbed-tls / 79f4e0e91d4d94dadc3713d9f3a73b544d47a14c / . / include / mbedtls / pkcs11_client.h
blob: 83aed5157f606353c5e55805ecd51308570957c3 [file] [log] [blame]
Andrzej Kurek753b86c2018-01-23 08:56:17 -0500[diff] [blame]1/**
2 * \file pkcs11_client.h
3 *
4 * \brief Generic wrapper for Cryptoki (PKCS#11) support
5 *
6 * Copyright (C) 2017, ARM Limited, All Rights Reserved
7 * SPDX-License-Identifier: Apache-2.0
8 *
9 * Licensed under the Apache License, Version 2.0 (the "License"); you may
10 * not use this file except in compliance with the License.
11 * You may obtain a copy of the License at
12 *
13 * http://www.apache.org/licenses/LICENSE-2.0
14 *
15 * Unless required by applicable law or agreed to in writing, software
16 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
17 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
18 * See the License for the specific language governing permissions and
19 * limitations under the License.
20 *
21 * This file is part of mbed TLS (https://tls.mbed.org)
22 */
23#ifndef MBEDTLS_PKCS11_CLIENT_H
24#define MBEDTLS_PKCS11_CLIENT_H
25
26#if !defined(MBEDTLS_CONFIG_FILE)
27#include "config.h"
28#else
29#include MBEDTLS_CONFIG_FILE
30#endif
31
32#if defined(MBEDTLS_PKCS11_CLIENT_C)
33
34#include <pkcs11.h>
35
36#if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \
37 !defined(inline) && !defined(__cplusplus)
38#define inline __inline
39#endif
40
41#ifdef __cplusplus
42extern "C" {
43#endif
44
45#define MBEDTLS_PKCS11_FLAG_TOKEN ( (uint32_t) 0x80000000 )
46
47#if defined(MBEDTLS_PK_C)
48
49#define MBEDTLS_PK_FLAG_SENSITIVE ( (uint32_t) 0x00000001 )
50#define MBEDTLS_PK_FLAG_EXTRACTABLE ( (uint32_t) 0x00000002 )
51#define MBEDTLS_PK_FLAG_SIGN ( (uint32_t) 0x00000010 )
52#define MBEDTLS_PK_FLAG_VERIFY ( (uint32_t) 0x00000020 )
53#define MBEDTLS_PK_FLAG_DECRYPT ( (uint32_t) 0x00000040 )
54#define MBEDTLS_PK_FLAG_ENCRYPT ( (uint32_t) 0x00000080 )
55
56#include "pk.h"
57
58/**
59 * \brief Set up a PK context for a key pair in a PKCS#11 token
60 *
61 * \param ctx PK context to fill, which must have been initialized
62 * with mbedtls_pk_init().
63 * \param hSession Cryptoki session.
64 * \param hPublicKey Cryptoki handle of the public key.
65 * \param hPrivateKey Cryptoki handle of the private key, or
66 * CK_INVALID_HANDLE for a public key rather than a key
67 * pair.
68 *
69 * \return 0 on success,
70 * or MBEDTLS_ERR_PK_XXX error code.
71 *
72 * \note The session and the key(s) must remain valid until the
73 * PK context is closed with mbedtls_pk_free(). As an
74 * exception, it's ok to call mbedtls_pk_free() itself
75 * even if the Cryptoki handles have become invalid.
76 */
77int mbedtls_pk_setup_pkcs11( mbedtls_pk_context *ctx,
78 CK_SESSION_HANDLE hSession,
79 CK_OBJECT_HANDLE hPublicKey,
80 CK_OBJECT_HANDLE hPrivateKey );
81
82/**
83 * \brief Import a transparent key into a PKCS#11 token
84 *
85 * This function imports a PK object containing a
86 * public key or a private-public key pair into a
87 * PKCS#11 token.
88 *
89 * \param ctx PK context, which must contain a transparent pk
90 * object (type \c MBEDTLS_PK_RSA,
91 * \c MBEDTLS_PK_RSASSA_PSS, \c MBEDTLS_PK_ECKEY or
92 * \c MBEDTLS_PK_ECDSA).
93 * \param flags Mask of \c MBEDTLS_PKCS11_FLAG_XXX and
94 * \c MBEDTLS_PK_FLAG_XXX, applying as follows:
95 * - \c MBEDTLS_PKCS11_FLAG_TOKEN: PKCS#11 \c CKA_TOKEN
96 * flag: if set, import as token object; if clear,
97 * import as session object.
98 * - \c MBEDTLS_PK_FLAG_EXTRACTABLE: PKCS#11
99 * \c CKA_EXTRACTABLE flag: if set, the key will be
100 * extractable at least in wrapped form; if clear,
101 * the key will not be extractable at all.
102 * - \c MBEDTLS_PK_FLAG_SENSITIVE: PKCS#11
103 * \c CKA_SENSITIVE flag: if set, the key will be
104 * not be extractable in plain form; if clear, the
105 * key will be extractable at least in wrapped form.
106 * - \c MBEDTLS_PK_FLAG_SIGN: if set, the private key
107 * will be authorized for signing.
108 * - \c MBEDTLS_PK_FLAG_VERIFY: if set, the public key
109 * will be authorized for verification.
110 * - \c MBEDTLS_PK_FLAG_DECRYPT: if set, the private key
111 * will be authorized for signing.
112 * - \c MBEDTLS_PK_FLAG_ENCRYPT: if set, the public key
113 * will be authorized for encryption.
114 *
115 * \param hSession Cryptoki session.
116 * \param hPublicKey If non-null, on output, Cryptoki handle of the public
117 * key. If null, the public key is not imported.
118 * \param hPrivateKey If non-null, on output, Cryptoki handle of the private
119 * key. If null, the private key is not imported.
120 *
121 * \return 0 on success,
122 * or MBEDTLS_ERR_PK_XXX error code.
123 *
124 * \note If \c hPrivateKey is non-null then \c ctx must contain
125 * a full key pair. If \c hPrivateKey is null then \c ctx
126 * may contain a full key pair or just a public key.
127 *
128 * \note On failure, the values returned in \c hPublicKey and
129 * \c hPrivateKey will normally be \c CK_HANDLE_INVALID.
130 * One of them may be a valid handle in the unlikely case
131 * where the creation of one key object succeeded but
132 * the second one failed and destroying the first one
133 * also failed, for example because the token was
134 * disconnected.
135 */
136int mbedtls_pk_import_to_pkcs11( const mbedtls_pk_context *ctx,
137 uint32_t flags,
138 CK_SESSION_HANDLE hSession,
139 CK_OBJECT_HANDLE *hPublicKey,
140 CK_OBJECT_HANDLE *hPrivateKey );
141
142#endif /* MBEDTLS_PK_C */
143
144#ifdef __cplusplus
145}
146#endif
147
148#endif /* MBEDTLS_PKCS11_CLIENT_C */
149
150#endif /* MBEDTLS_PKCS11_H */