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