Mayank Gupta
/
pelion-example-frdm
Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
Dependencies: FXAS21002 FXOS8700Q
Embed:
(wiki syntax)
Show/hide line numbers
pal_Crypto.h
Go to the documentation of this file.
00001 // ---------------------------------------------------------------------------- 00002 // Copyright 2016-2019 ARM Ltd. 00003 // 00004 // SPDX-License-Identifier: Apache-2.0 00005 // 00006 // Licensed under the Apache License, Version 2.0 (the "License"); 00007 // you may not use this file except in compliance with the License. 00008 // You may obtain a copy of the License at 00009 // 00010 // http://www.apache.org/licenses/LICENSE-2.0 00011 // 00012 // Unless required by applicable law or agreed to in writing, software 00013 // distributed under the License is distributed on an "AS IS" BASIS, 00014 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00015 // See the License for the specific language governing permissions and 00016 // limitations under the License. 00017 // ---------------------------------------------------------------------------- 00018 00019 #ifndef _PAL_CRYPTO_H_ 00020 #define _PAL_CRYPTO_H_ 00021 00022 #ifndef _PAL_H 00023 #error "Please do not include this file directly, use pal.h instead" 00024 #endif 00025 00026 /*! \file pal_Crypto.h 00027 * \brief PAL cryptographic. 00028 * This file contains cryptographic APIs and is part of the PAL service API. 00029 * 00030 * It contains a variety of cryptographic APIs, such as: 00031 * - AES-CTR 00032 - AES-DRBG 00033 - CMAC 00034 - Message Digest 00035 */ 00036 00037 typedef uintptr_t palAesHandle_t; 00038 typedef uintptr_t palX509Handle_t; 00039 typedef uintptr_t palMDHandle_t; 00040 typedef uintptr_t palCCMHandle_t; 00041 typedef uintptr_t palCMACHandle_t; 00042 typedef uintptr_t palCtrDrbgCtxHandle_t; 00043 typedef uintptr_t palCurveHandle_t; 00044 typedef uintptr_t palGroupIDHandle_t; 00045 typedef uintptr_t palECKeyHandle_t; 00046 typedef uintptr_t palSignatureHandle_t; 00047 typedef uintptr_t palx509CSRHandle_t; 00048 00049 //! Key types to be set to the AES engine. 00050 typedef enum palAesKeyType{ 00051 PAL_KEY_TARGET_ENCRYPTION, 00052 PAL_KEY_TARGET_DECRYPTION 00053 }palAesKeyType_t; 00054 00055 //! Message digest algorithms supported by PAL. 00056 typedef enum palMDType{ 00057 PAL_SHA256 00058 }palMDType_t; 00059 00060 //! AES mode for ECB encryption and decryption. 00061 typedef enum palAesMode{ 00062 PAL_AES_ENCRYPT, 00063 PAL_AES_DECRYPT 00064 }palAesMode_t; 00065 00066 //! The enum tags supported by PAL for ASN.1. 00067 typedef enum palASNTag{ 00068 PAL_ASN1_BOOLEAN = 0x01, 00069 PAL_ASN1_INTEGER = 0x02, 00070 PAL_ASN1_BIT_STRING = 0x03, 00071 PAL_ASN1_OCTET_STRING = 0x04, 00072 PAL_ASN1_NULL = 0x05, 00073 PAL_ASN1_OID = 0x06, 00074 PAL_ASN1_UTF8_STRING = 0x0C, 00075 PAL_ASN1_SEQUENCE = 0x10, 00076 PAL_ASN1_SET = 0x11, 00077 PAL_ASN1_PRINTABLE_STRING = 0x13, 00078 PAL_ASN1_T61_STRING = 0x14, 00079 PAL_ASN1_IA5_STRING = 0x16, 00080 PAL_ASN1_UTC_TIME = 0x17, 00081 PAL_ASN1_GENERALIZED_TIME = 0x18, 00082 PAL_ASN1_UNIVERSAL_STRING = 0x1C, 00083 PAL_ASN1_BMP_STRING = 0x1E, 00084 PAL_ASN1_PRIMITIVE = 0x00, 00085 PAL_ASN1_CONSTRUCTED = 0x20, 00086 PAL_ASN1_CONTEXT_SPECIFIC = 0x80, 00087 }palASNTag_t; 00088 00089 #define PAL_ASN1_CLASS_BITS 0xC0 00090 #define PAL_ASN1_TAG_BITS 0x1F 00091 #define PAL_CRYPT_BLOCK_SIZE 16 00092 #define PAL_SHA256_SIZE 32 00093 00094 typedef enum palFormat{ 00095 PAL_POINT_CONVERSION_UNCOMPRESSED 00096 /*PAL_POINT_CONVERSION_COMPRESSED*/ 00097 }palFormat_t; 00098 00099 typedef enum palCipherID{ 00100 PAL_CIPHER_ID_AES 00101 /*PAL_CIPHER_ID_DES*/ 00102 }palCipherID_t; 00103 00104 //! Supported curves. 00105 typedef enum palGroupIndex{ 00106 PAL_ECP_DP_NONE, 00107 PAL_ECP_DP_SECP256R1 00108 }palGroupIndex_t; 00109 00110 //! Key usage options 00111 typedef enum palKeyUsage{ 00112 PAL_X509_KU_DIGITAL_SIGNATURE = 0x1, 00113 PAL_X509_KU_NON_REPUDIATION = 0x2, 00114 PAL_X509_KU_KEY_CERT_SIGN = 0x4, 00115 PAL_X509_KU_KEY_AGREEMENT = 0x8 00116 }palKeyUsage_t; 00117 00118 //! Extended key usage options 00119 typedef enum palExtKeyUsage { 00120 PAL_X509_EXT_KU_ANY = (1 << 0), 00121 PAL_X509_EXT_KU_SERVER_AUTH = (1 << 1), 00122 PAL_X509_EXT_KU_CLIENT_AUTH = (1 << 2), 00123 PAL_X509_EXT_KU_CODE_SIGNING = (1 << 3), 00124 PAL_X509_EXT_KU_EMAIL_PROTECTION = (1 << 4), 00125 PAL_X509_EXT_KU_TIME_STAMPING = (1 << 8), 00126 PAL_X509_EXT_KU_OCSP_SIGNING = (1 << 9) 00127 }palExtKeyUsage_t; 00128 00129 //! Key check options. 00130 typedef enum palKeyToCheck{ 00131 PAL_CHECK_PRIVATE_KEY = 0x01, 00132 PAL_CHECK_PUBLIC_KEY = 0x10, 00133 PAL_CHECK_BOTH_KEYS = 0x11 00134 }palKeyToCheck_t; 00135 00136 //! Attributes to be retrieved from the X.509 certificate. 00137 typedef enum palX509Attr{ 00138 PAL_X509_ISSUER_ATTR, 00139 PAL_X509_SUBJECT_ATTR, 00140 PAL_X509_CN_ATTR, 00141 PAL_X509_OU_ATTR, 00142 PAL_X509_VALID_FROM, 00143 PAL_X509_VALID_TO, 00144 PAL_X509_CERT_ID_ATTR, 00145 PAL_X509_SIGNATUR_ATTR, 00146 PAL_X509_L_ATTR 00147 }palX509Attr_t; 00148 00149 00150 /***************************************************/ 00151 /**** PAL Crypto Client APIs ***********************/ 00152 /***************************************************/ 00153 00154 /*! \brief Initialize an AES context 00155 * 00156 * @param[in,out] aes: The AES context to be initialized. 00157 * 00158 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00159 */ 00160 palStatus_t pal_initAes(palAesHandle_t *aes); 00161 00162 /*! \brief Free an AES context. 00163 * 00164 * @param[in,out] aes: The AES context to be deallocated. 00165 * 00166 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00167 */ 00168 palStatus_t pal_freeAes(palAesHandle_t *aes); 00169 00170 /*! \brief Set an AES key context for encryption or decryption. 00171 * 00172 * @param[in] aes: The AES context. 00173 * @param[in] key: The AES key. 00174 * @param[in] keybits: The size of the key in bits. 00175 * @param[in] keyTarget: The key target, either encryption or decryption. 00176 * 00177 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00178 */ 00179 palStatus_t pal_setAesKey(palAesHandle_t aes, const unsigned char* key, uint32_t keybits, palAesKeyType_t keyTarget); 00180 00181 /*! \brief Use AES-CTR encryption or decryption on a buffer. 00182 * 00183 * @param[in] aes: The AES context. 00184 * @param[in] input: The input data buffer. 00185 * @param[out] output: The output data buffer. 00186 * @param[in] inLen: The input data buffer length in bytes. 00187 * @param[in] iv: The initialization vector for AES-CTR. 00188 * 00189 \note Due to the nature of CTR, you should use the same key schedule for 00190 * both encryption and decryption. So before calling this function, you *must* set the key 00191 * by calling `pal_setAesKey()` with key target `PAL_KEY_TARGET_ENCRYPTION`. 00192 * 00193 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00194 */ 00195 palStatus_t pal_aesCTR(palAesHandle_t aes, const unsigned char* input, unsigned char* output, size_t inLen, unsigned char iv[16]); 00196 00197 /*! \brief Use AES-CTR encryption or decryption with zero offset on a buffer. 00198 * 00199 * @param[in] aes: The AES context. 00200 * @param[in] input: The input data buffer. 00201 * @param[out] output: The output data buffer. 00202 * @param[in] inLen: The input data length in bytes. 00203 * @param[in] iv: The initialization vector for AES-CTR. 00204 * 00205 \note Due to the nature of CTR, you should use the same key schedule for 00206 * both encryption and decryption. So before calling this function, you *must* set the key 00207 * by calling `pal_setAesKey()` with key target `PAL_KEY_TARGET_ENCRYPTION`. 00208 * 00209 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00210 */ 00211 palStatus_t pal_aesCTRWithZeroOffset(palAesHandle_t aes, const unsigned char* input, unsigned char* output, size_t inLen, unsigned char iv[16]); 00212 00213 /*! \brief Use AES-ECB encryption or decryption on a block. 00214 * 00215 * @param[in] aes: The AES context. 00216 * @param[in] input: A 16-byte input block. 00217 * @param[out] output: A 16-byte output block. 00218 * @param[in] mode: Defines whether to encrypt or decrypt. Set as `PAL_AES_ENCRYPT` for encryption or `PAL_AES_DECRYPT` for decryption. 00219 * 00220 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00221 */ 00222 palStatus_t pal_aesECB(palAesHandle_t aes, const unsigned char input[PAL_CRYPT_BLOCK_SIZE], unsigned char output[PAL_CRYPT_BLOCK_SIZE], palAesMode_t mode); 00223 00224 /*! \brief Run a SHA-256 operation on the input data. 00225 * 00226 * @param[in] input: A buffer for the input data. 00227 * @param[in] inLen: The length of the input data in bytes. 00228 * @param[out] output: The SHA-256 checksum result. 00229 * 00230 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00231 */ 00232 palStatus_t pal_sha256(const unsigned char* input, size_t inLen, unsigned char output[PAL_SHA256_SIZE]); 00233 00234 /*! \brief Initialize a certificate chain context. 00235 * 00236 * @param[in,out] x509Cert: The certificate chain to initialize. 00237 * 00238 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00239 */ 00240 palStatus_t pal_x509Initiate(palX509Handle_t* x509Cert); 00241 00242 /*! \brief Parse one or more certificates and add them to the chained list. 00243 * 00244 * @param[in] x509Cert: The beginning of the chain. 00245 * @param[in] input: A buffer holding the certificate data in PEM or DER format. 00246 * @param[in] inLen: The size of the input buffer in bytes. 00247 * 00248 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00249 */ 00250 palStatus_t pal_x509CertParse(palX509Handle_t x509Cert, const unsigned char* input, size_t inLen); 00251 00252 /*! \brief Get an attribute from the parsed certificate. 00253 * 00254 * @param[in] x509Cert: The parsed certificate. 00255 * @param[in] attr: The required attribute. 00256 * @param[out] output: A buffer to hold the attribute value. 00257 * @param[in] outLenBytes: The size of the allocated buffer in bytes. 00258 * @param[out] actualOutLenBytes: The actual size of the attribute in bytes. 00259 * 00260 \note In case of PAL_ERR_BUFFER_TOO_SMALL, the required size is assigned into the `actualOutLen` parameter. 00261 \note `PAL_X509_CERT_ID_ATTR` requires a 33 bytes buffer size. 00262 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00263 */ 00264 palStatus_t pal_x509CertGetAttribute(palX509Handle_t x509Cert, palX509Attr_t attr, void* output, size_t outLenBytes, size_t* actualOutLenBytes); 00265 00266 /*! \brief Verify one or more DER encoded X.509 certificates. 00267 * 00268 * @param[in] x509Cert: A handle holding the parsed certificate. 00269 * @param[in] x509CertChain: Optional. The beginning of the chain to verify the X.509 DER certificate with. 00270 * 00271 \return PAL_SUCCESS on success. In case of failure: 00272 * - PAL_ERR_X509_BADCERT_EXPIRED 00273 * - PAL_ERR_X509_BADCERT_FUTURE 00274 * - PAL_ERR_X509_BADCERT_BAD_MD 00275 * - PAL_ERR_X509_BADCERT_BAD_PK 00276 * - PAL_ERR_X509_BADCERT_NOT_TRUSTED 00277 * - PAL_ERR_X509_BADCERT_BAD_KEY 00278 */ 00279 palStatus_t pal_x509CertVerify(palX509Handle_t x509Cert, palX509Handle_t x509CertChain); 00280 00281 /*! \brief Verify one or more DER-encoded X.509 certificates. 00282 * 00283 * @param[in] x509Cert: A handle holding the parsed certificate. 00284 * @param[in] x509CertChain: The beginning of the chain to verify the X509 DER certificate with. Optional. 00285 * @param[out] verifyResult: A bitmask of the errors that cause the failure. This value is relevant only in case failure. 00286 * 00287 \return PAL_SUCCESS on success. In case of failure returns `PAL_ERR_X509_CERT_VERIFY_FAILED`. 00288 */ 00289 palStatus_t pal_x509CertVerifyExtended(palX509Handle_t x509Cert, palX509Handle_t x509CertChain, int32_t* verifyResult); 00290 00291 /*! \brief Deallocate all certificate data. 00292 * 00293 * @param[in,out] x509Cert: The certificate chain to free. 00294 * 00295 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00296 */ 00297 palStatus_t pal_x509Free(palX509Handle_t* x509Cert); 00298 00299 /*! \brief Initialize the Message Digest (MD) context and set it up according to the given algorithm. 00300 * 00301 * @param[in,out] md: The MD context to be initialized. 00302 * @param[in] mdType: The MD algorithm to be used. 00303 * 00304 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00305 */ 00306 palStatus_t pal_mdInit(palMDHandle_t* md, palMDType_t mdType); 00307 00308 /*! \brief Apply an Message Digest (MD) process on a buffer. 00309 * 00310 * @param[in] md: The MD context. 00311 * @param[in] input: A buffer holding the input data. 00312 * @param[in] inLen: The length of the input data in bytes. 00313 * 00314 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00315 */ 00316 palStatus_t pal_mdUpdate(palMDHandle_t md, const unsigned char* input, size_t inLen); 00317 00318 /*! \brief Get the length of the Message Digest (MD) output. 00319 * 00320 * @param[in] md: The MD context. 00321 * @param[out] bufferSize: A pointer to hold the output size of the `pal_mdFinal()` for the given handle. 00322 * 00323 \note This function should be called \b before calling `pal_mdFinal()`. 00324 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00325 */ 00326 palStatus_t pal_mdGetOutputSize(palMDHandle_t md, size_t* bufferSize); 00327 00328 /*! \brief Calculate the final Message Digest (MD). 00329 * 00330 * @param[in] md: The MD context. 00331 * @param[out] output: The checksum result of the MD. 00332 * 00333 \note `pal_mdGetOutputSize()` should be called \b before calling `pal_mdFinal()` to get the needed size for the output. 00334 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00335 */ 00336 palStatus_t pal_mdFinal(palMDHandle_t md, unsigned char* output); 00337 00338 /*! \brief Free and clear a Message Digest (MD) context. 00339 * 00340 * @param[in,out] md: The MD context to be freed. 00341 * 00342 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00343 */ 00344 palStatus_t pal_mdFree(palMDHandle_t* md); 00345 00346 /*! \brief Verify the signature. 00347 * 00348 * @param[in] x509: The certificate context that holds the PK data. 00349 * @param[in] mdType: The MD algorithm used. 00350 * @param[in] hash: The hash of the message to sign. 00351 * @param[in] hashLen: The hash length in bytes. 00352 * @param[in] sig: The signature to verify. 00353 * @param[in] sigLen: The signature length. 00354 * 00355 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00356 */ 00357 palStatus_t pal_verifySignature(palX509Handle_t x509, palMDType_t mdType, const unsigned char *hash, size_t hashLen, const unsigned char *sig, size_t sigLen); 00358 00359 /*! \brief Check for a tag in ASN.1 data. 00360 * 00361 * The function updates the pointer position to immediately after the tag and its length. 00362 * 00363 * @param[in,out] position: The position in the ASN.1 data. 00364 * @param[in] end: The end of data. 00365 * @param[out] len: The tag length in bytes. 00366 * @param[in] tag: The expected tag. 00367 * 00368 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00369 */ 00370 palStatus_t pal_ASN1GetTag(unsigned char **position, const unsigned char *end, size_t *len, uint8_t tag); 00371 00372 /*! Initialize the CCM context. 00373 * 00374 * @param[in] ctx: The CCM context to be initialized. 00375 * 00376 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00377 */ 00378 palStatus_t pal_CCMInit(palCCMHandle_t* ctx); 00379 00380 /*! \brief Destroy a CCM context. 00381 * 00382 * @param[in] ctx: The CCM context to destroy. 00383 * 00384 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00385 */ 00386 palStatus_t pal_CCMFree(palCCMHandle_t* ctx); 00387 00388 /*! \brief Encrypt a CCM context using a set key. 00389 * 00390 * @param[in] ctx: The CCM context to be initialized. 00391 * @param[in] id: The 128-bit block cipher to use. 00392 * @param[in] key: The encryption key. 00393 * @param[in] keybits: The key size in bits. The size must be acceptable by the cipher. 00394 * 00395 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00396 */ 00397 palStatus_t pal_CCMSetKey(palCCMHandle_t ctx, const unsigned char *key, uint32_t keybits, palCipherID_t id); 00398 00399 /*! \brief Use authenticated decryption on a CCM buffer . 00400 * 00401 * @param[in] ctx: The CCM context to be initialized. 00402 * @param[in] input A buffer holding the input data. 00403 * @param[in] inLen: The length of the input data in bytes. 00404 * @param[in] iv: The initialization vector. 00405 * @param[in] ivLen: The length of the initialization vector in bytes. 00406 * @param[in] add: Additional data. 00407 * @param[in] addLen: The length of the additional data in bytes. 00408 * @param[in] tag: A buffer holding the tag. 00409 * @param[in] tagLen: The length of the tag. 00410 * @param[out] output: A buffer for holding the output data. 00411 * 00412 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00413 */ 00414 palStatus_t pal_CCMDecrypt(palCCMHandle_t ctx, unsigned char* input, size_t inLen, 00415 unsigned char* iv, size_t ivLen, unsigned char* add, 00416 size_t addLen, unsigned char* tag, size_t tagLen, 00417 unsigned char* output); 00418 00419 /*! \brief Encrypt a CCM buffer. 00420 * 00421 * @param[in] ctx: The CCM context to be initialized. 00422 * @param[in] input A buffer holding the input data. 00423 * @param[in] inLen: The length of the input data. 00424 * @param[in] iv: The initialization vector. 00425 * @param[in] ivLen: The length of the initalization vector in bytes. 00426 * @param[in] add: Additional data. 00427 * @param[in] addLen: The length of additional data. 00428 * @param[out] output: A buffer for holding the output data, must be at least `inLen` bytes wide. 00429 * @param[out] tag: A buffer for holding the tag. 00430 * @param[out] tagLen: The length of the tag to generate in bytes. 00431 * 00432 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00433 */ 00434 palStatus_t pal_CCMEncrypt(palCCMHandle_t ctx, unsigned char* input, 00435 size_t inLen, unsigned char* iv, size_t ivLen, 00436 unsigned char* add, size_t addLen, unsigned char* output, 00437 unsigned char* tag, size_t tagLen); 00438 00439 /*! \brief Initialize a Counter mode Deterministic Random Byte Generator (CTR-DRBG) context with a given seed. 00440 * 00441 * @param[in] ctx: The CTR-DRBG context to be seeded. 00442 * @param[in] seed: The seed data. 00443 * @param[in] len: The length of the seed data in bytes. 00444 * 00445 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00446 */ 00447 palStatus_t pal_CtrDRBGInit(palCtrDrbgCtxHandle_t* ctx, const void* seed, size_t len); 00448 00449 /*! \brief Check whether a Counter mode Deterministic Random Byte Generator (CTR-DRBG) context is seeded. 00450 * 00451 * Calls to `pal_CtrDRBGGenerate()` only succeed when the context is seeded. 00452 * 00453 * @param[in] ctx: The CTR-DRBG context to be checked. 00454 * 00455 * \return PAL_SUCCESS if the CTR-DRBG is seeded. 00456 * \return PAL_ERR_CTR_DRBG_NOT_SEEDED if the CTR-DRBG is not yet seeded, meaning calls to `pal_CtrDRBGGenerate()` will fail. 00457 * \return Any other negative value indicating a specific error code in case of failure. 00458 */ 00459 palStatus_t pal_CtrDRBGIsSeeded(palCtrDrbgCtxHandle_t ctx); 00460 00461 /*! \brief Generate a pseudo random number using the Counter mode Deterministic Random Byte Generator (CTR-DRBG). 00462 * 00463 * @param[in] ctx: The CTR-DRBG context. 00464 * @param[out] out: The buffer to fill. 00465 * @param[in] len: The length of the buffer in bytes. 00466 * 00467 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00468 */ 00469 palStatus_t pal_CtrDRBGGenerate(palCtrDrbgCtxHandle_t ctx, unsigned char* out, size_t len); 00470 00471 /*! \brief Destroy a Counter mode Deterministic Random Byte Generator (CTR-DRBG) context. 00472 * 00473 * @param[in] ctx: The CTR-DRBG context to destroy. 00474 * 00475 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00476 */ 00477 palStatus_t pal_CtrDRBGFree(palCtrDrbgCtxHandle_t* ctx); 00478 00479 00480 /*! \brief Apply a one-shot CMAC cipher. 00481 * 00482 * @param[in] ctx: The CMAC context to initialize. 00483 * @param[in] key: The encryption key. 00484 * @param[in] keyLenInBits: The key size in bits. 00485 * @param[in] input: A buffer for the input data. 00486 * @param[in] inputLenInBytes: The length of the input data in bytes. 00487 * @param[out] output: The generic CMAC result. 00488 * 00489 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00490 */ 00491 palStatus_t pal_cipherCMAC(const unsigned char *key, size_t keyLenInBits, const unsigned char *input, size_t inputLenInBytes, unsigned char *output); 00492 00493 /*! \brief Start an iterative CMAC cipher. 00494 * 00495 * @param[in] ctx: The CMAC context. 00496 * @param[in] key: The CMAC key. 00497 * @param[in] keyLenBits: The key size in bits. 00498 * @param[in] cipherID: A buffer for the input data. 00499 * 00500 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00501 */ 00502 palStatus_t pal_CMACStart(palCMACHandle_t *ctx, const unsigned char *key, size_t keyLenBits, palCipherID_t cipherID); 00503 00504 /*! \brief Update an iterative CMAC cipher. 00505 * 00506 * @param[in] ctx: The CMAC context. 00507 * @param[in] input: A buffer for the input data. 00508 * @param[in] inLen: The length of the input data. 00509 * 00510 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00511 */ 00512 palStatus_t pal_CMACUpdate(palCMACHandle_t ctx, const unsigned char *input, size_t inLen); 00513 00514 /*! \brief Finish an iterative CMAC cipher. 00515 * 00516 * @param[in] ctx: The CMAC context. 00517 * @param[out] output: A buffer for the output data. 00518 * @param[out] outLen: The length of the output data in bytes. 00519 * 00520 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00521 */ 00522 palStatus_t pal_CMACFinish(palCMACHandle_t *ctx, unsigned char *output, size_t* outLen); 00523 00524 /*! \brief Apply a one-shot Message Digest HMAC cipher. 00525 * 00526 * @param[in] key: The encryption key. 00527 * @param[in] keyLenInBytes: The key size in bytes. 00528 * @param[in] input: A buffer for the input data. 00529 * @param[in] inputLenInBytes: The input data length in bytes. 00530 * @param[out] output: The generic HMAC result. 00531 * @param[out] outputLenInBytes: Optional. Size of the HMAC result. If not given, the default is 32 bytes. 00532 * 00533 * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00534 */ 00535 palStatus_t pal_mdHmacSha256(const unsigned char *key, size_t keyLenInBytes, const unsigned char *input, size_t inputLenInBytes, unsigned char *output, size_t* outputLenInBytes); 00536 00537 00538 /*! \brief Check that the private key, public key, or both are valid and that the public key is on the curve. 00539 * 00540 * @param[in] grp: The curve or group that the point should belong to. 00541 * @param[in] key: A pointer to a struct holding the raw data of the keys to check. 00542 * @param[in] type: Determines whether to check the private key, public key or both should be checked. See `palKeyToCheck_t` for values. 00543 * @param[out] verified: The result of verification. 00544 * 00545 \note The key can contain only private or public key or both. 00546 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00547 */ 00548 palStatus_t pal_ECCheckKey(palCurveHandle_t grp, palECKeyHandle_t key, uint32_t type, bool *verified); 00549 00550 /*! \brief Allocate a key context and initialize a key pair as an invalid pair. 00551 * 00552 * @param[in] key: The key to initialize. 00553 * 00554 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00555 */ 00556 palStatus_t pal_ECKeyNew(palECKeyHandle_t* key); 00557 00558 /*! \brief Release a private or public key context from memory. 00559 * 00560 * @param[in] key: A handle for the key context to be freed. 00561 * 00562 \note This function should be called \b before calling `pal_ECKeyGenerateKey()`. 00563 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00564 */ 00565 palStatus_t pal_ECKeyFree(palECKeyHandle_t* key); 00566 00567 /*! \brief Parse a DER-encoded private key. 00568 * 00569 * @param[in] prvDERKey: A buffer that holds the DER-encoded private key. 00570 * @param[in] keyLen: The key length in bytes. 00571 * @param[out] key: A handle for the context that holds the parsed key. 00572 * 00573 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00574 */ 00575 palStatus_t pal_parseECPrivateKeyFromDER(const unsigned char* prvDERKey, size_t keyLen, palECKeyHandle_t key); 00576 00577 /*! \brief Parse a DER-encoded public key. 00578 * 00579 * @param[in] pubDERKey: A buffer that holds the DER encoded public key. 00580 * @param[in] keyLen: The key length in bytes. 00581 * @param[out] key: A handle for the context that holds the parsed key. 00582 * 00583 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00584 */ 00585 palStatus_t pal_parseECPublicKeyFromDER(const unsigned char* pubDERKey, size_t keyLen, palECKeyHandle_t key); 00586 00587 /*! \brief DER encode a private key from a key handle. 00588 * 00589 * @param[in] key: A handle to the private key. 00590 * @param[out] derBuffer: A buffer to hold the result of the DER encoding. 00591 * @param[in] bufferSize: The size of the allocated buffer. 00592 * @param[out] actualSize: The actual size of the written data. 00593 * 00594 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00595 */ 00596 palStatus_t pal_writePrivateKeyToDer(palECKeyHandle_t key, unsigned char* derBuffer, size_t bufferSize, size_t* actualSize); 00597 00598 /*! \brief DER encode a public key from a key handle. 00599 * 00600 * @param[in] key: A handle to the public key. 00601 * @param[out] derBuffer: A buffer to hold the result of the DER encoding. 00602 * @param[in] bufferSize: The size of the allocated buffer in bytes. 00603 * @param[out] actualSize: The actual size of the written data in bytes. 00604 * 00605 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00606 */ 00607 palStatus_t pal_writePublicKeyToDer(palECKeyHandle_t key, unsigned char* derBuffer, size_t bufferSize, size_t* actualSize); 00608 00609 /*! \brief Generate a key pair for a given Elliptic Curve. 00610 * 00611 * @param[in] grpID: The ECP group identifier. 00612 * @param[in,out] key: The destination handle for the key pair . 00613 * 00614 \note `pal_ECKeyNew()` should be called \b before calling `pal_ECKeyGenerateKey()` 00615 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00616 */ 00617 palStatus_t pal_ECKeyGenerateKey(palGroupIndex_t grpID, palECKeyHandle_t key); 00618 00619 /*! \brief Retrieve the curve ID if it exists in the given key. 00620 * 00621 * @param[in] key: The key where the curve is retrieved from. 00622 * @param[out] grpID: The group ID for the given key. In case of error, this pointer contains `PAL_ECP_DP_NONE`. 00623 * 00624 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00625 */ 00626 palStatus_t pal_ECKeyGetCurve(palECKeyHandle_t key, palGroupIndex_t* grpID); 00627 00628 /*! \brief Initialize and set an ECP group using well-known domain parameters. 00629 * 00630 * @param[in] grp: The destination group. 00631 * @param[in] index: The index position in the list of well-known domain parameters. 00632 * 00633 \return PAL_SUCCESS on success, negative value indicating a specific error code in case of failure. 00634 */ 00635 palStatus_t pal_ECGroupInitAndLoad(palCurveHandle_t* grp, palGroupIndex_t index); 00636 00637 /*! \brief Free the ECP group context. 00638 * 00639 * @param[in] grp: The curve or group to free. 00640 * 00641 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00642 */ 00643 palStatus_t pal_ECGroupFree(palCurveHandle_t* grp); 00644 00645 /*! \brief Allocate and initialize X.509 certificate signing request (CSR) context. 00646 * 00647 * @param[in] x509CSR: The CSR context to allocate and initialize. 00648 * 00649 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00650 */ 00651 palStatus_t pal_x509CSRInit(palx509CSRHandle_t *x509CSR); 00652 00653 /*! \brief Set the subject name for a certificate signing request (CSR). Subject names should contain a comma-separated list of OIDs and values. 00654 * 00655 * @param[in] x509CSR: The CSR context to use. 00656 * @param[in] subjectName: The subject name to set 00657 * 00658 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00659 */ 00660 palStatus_t pal_x509CSRSetSubject(palx509CSRHandle_t x509CSR, const char* subjectName); 00661 00662 /*! Set the type of Message Digest (MD) algorithm to use for the signature. 00663 * 00664 * @param[in] x509CSR: The CSR context to use. 00665 * @param[in] mdType: The MD algorithm to use. 00666 * 00667 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00668 */ 00669 palStatus_t pal_x509CSRSetMD(palx509CSRHandle_t x509CSR, palMDType_t mdType); 00670 00671 /*! \brief Set the key for a CSR. 00672 * 00673 * @param[in] x509CSR: The CSR context to use. 00674 * @param[in] pubKey: The public key to include. To use a key pair handle, see the note. 00675 * @param[in] prvKey: The public key to sign with. 00676 * 00677 \note To use a key pair, send the desired key pair as `pubKey` and NULL as `prvKey`. 00678 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00679 */ 00680 palStatus_t pal_x509CSRSetKey(palx509CSRHandle_t x509CSR, palECKeyHandle_t pubKey, palECKeyHandle_t prvKey); 00681 00682 /*! \brief Set the key usage extension flags for a CSR context. 00683 * 00684 * @param[in] x509CSR: The CSR context to configure. 00685 * @param[in] keyUsage: The key usage flags. See `palKeyUsage_t` for options. 00686 * 00687 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00688 */ 00689 palStatus_t pal_x509CSRSetKeyUsage(palx509CSRHandle_t x509CSR, uint32_t keyUsage); 00690 00691 /*! \brief Set the extended key usage flags. 00692 * 00693 * @param[in] x509CSR: The CSR context to configure. 00694 * @param[in] extKeyUsage: The extended key usage flags, should be taken from `palExtKeyUsage_t`. 00695 * 00696 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00697 */ 00698 palStatus_t pal_x509CSRSetExtendedKeyUsage(palx509CSRHandle_t x509CSR, uint32_t extKeyUsage); 00699 00700 /*! \brief Generic function to extend a CSR context. 00701 * 00702 * @param[in] x509CSR: The CSR context to extend. 00703 * @param[in] oid: The OID of the extension. 00704 * @param[in] oidLen: The OID length. 00705 * @param[in] value: The value of the extension OCTET STRING. 00706 * @param[in] valueLen: The value length. 00707 * 00708 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00709 */ 00710 palStatus_t pal_x509CSRSetExtension(palx509CSRHandle_t x509CSR,const char* oid, size_t oidLen, 00711 const unsigned char* value, size_t valueLen); 00712 00713 /*! \brief Write a CSR to a DER structure 00714 * 00715 * @param[in] x509CSR: The CSR context to use. 00716 * @param[in] derBuf: A buffer to write to. 00717 * @param[in] derBufLen: The buffer length. 00718 * @param[in] actualDerLen: The actual length of the written data. 00719 * 00720 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00721 */ 00722 palStatus_t pal_x509CSRWriteDER(palx509CSRHandle_t x509CSR, unsigned char* derBuf, size_t derBufLen, size_t* actualDerLen); 00723 00724 /*! \brief Writes a CSR from a given X.509 Certificate 00725 * 00726 * @param[in] x509Cert: The parsed X.509 certificate on which we generate the CSR from. 00727 * @param[in,out] x509CSR: The X.509 CSR that has been already initialized with a private key. 00728 * @param[out] derBuf: A buffer to write to. 00729 * @param[in] derBufLen: The buffer length. 00730 * @param[out] actualDerBufLen: The actual length of the written data. 00731 * 00732 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00733 */ 00734 palStatus_t pal_x509CSRFromCertWriteDER(palX509Handle_t x509Cert, palx509CSRHandle_t x509CSR, unsigned char* derBuf, size_t derBufLen, size_t* actualDerBufLen); 00735 00736 /*! \brief Free the X.509 CSR context. 00737 * 00738 * @param[in] x509CSR: The CSR context to free. 00739 * 00740 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00741 */ 00742 palStatus_t pal_x509CSRFree(palx509CSRHandle_t *x509CSR); 00743 00744 /*! \brief Compute the shared secret using elliptic curve Diffie–Hellman. 00745 * 00746 * @param[in] grp: The ECP group. 00747 * @param[in] peerPublicKey: The public key from a peer. 00748 * @param[in] privateKey: The private key. 00749 * @param[out] outKey: The shared secret. 00750 * 00751 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00752 */ 00753 palStatus_t pal_ECDHComputeKey(const palCurveHandle_t grp, const palECKeyHandle_t peerPublicKey, 00754 const palECKeyHandle_t privateKey, palECKeyHandle_t outKey); 00755 00756 /*! \brief Compute the Elliptic Curve Digital Signature Algorithm (ECDSA) signature of a previously hashed message. 00757 * 00758 * @param[in] grp: The ECP group. 00759 * @param[in] mdType: The MD algorithm to be used. 00760 * @param[in] prvKey: The private signing key. 00761 * @param[in] dgst: The message hash. 00762 * @param[in] dgstLen: The length ofthe message buffer. 00763 * @param[out] sig: A buffer to hold the computed signature. 00764 * @param[out] sigLen: The length of the computed signature. 00765 * 00766 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00767 */ 00768 palStatus_t pal_ECDSASign(palCurveHandle_t grp, palMDType_t mdType, palECKeyHandle_t prvKey, unsigned char* dgst, 00769 uint32_t dgstLen, unsigned char *sig, size_t *sigLen); 00770 00771 /*! \brief Verify the Elliptic Curve Digital Signature Algorithm (ECDSA) signature of a previously hashed message. 00772 * 00773 * @param[in] pubKey: The public key for verification. 00774 * @param[in] dgst: The message hash. 00775 * @param[in] dgstLen: The length of the message buffer. 00776 * @param[in] sign: The signature. 00777 * @param[in] sig: A buffer to hold the computed signature. 00778 * @param[in] sigLen: The length of the computed signature. 00779 * @param[out] verified: A boolean to hold the verification result. 00780 * 00781 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00782 */ 00783 palStatus_t pal_ECDSAVerify(palECKeyHandle_t pubKey, unsigned char* dgst, uint32_t dgstLen, 00784 unsigned char* sig, size_t sigLen, bool* verified); 00785 00786 00787 /*! \brief Calculate the hash of the part of an X.509 certificate that is to be signed. 00788 * 00789 * This function may be used to validate a certificate signature: Simply retrieve this hash, verify the signature using this hash, the public key and the signature of the X509 00790 * 00791 * @param[in] x509Cert: Handle to the certificate to hash the TBS (to be signed part). 00792 * @param[in] hash_type: The hash type. Currently only PAL_SHA256 supported 00793 * @param[out] output: Pointer to a buffer that will contain the hash digest. This buffer must be at least the size of the digest. If hash_type is PAL_SHA256, then buffer pointed to by output must be at least 32 bytes. 00794 * @param[in] outLenBytes: The size of the buffer pointed to by output. Must be at least the size of the digest 00795 * @param[out] actualOutLenBytes: Size of the digest copied to output. In case of success, will always be the length of the hash digest 00796 * 00797 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00798 */ 00799 00800 palStatus_t pal_x509CertGetHTBS(palX509Handle_t x509Cert, palMDType_t hash_type, unsigned char *output, size_t outLenBytes, size_t* actualOutLenBytes); 00801 00802 #endif //_PAL_CRYPTO_H_
Generated on Tue Jul 12 2022 20:21:01 by
1.7.2