Jim Carver
Simulated product dispenser
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