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