pal_plat_Crypto.h

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_PLAT_CRYPTO_H_
00018 #define _PAL_PLAT_CRYPTO_H_
00019 
00020 #include "pal_Crypto.h"
00021 
00022 /*! \file pal_plat_Crypto.h
00023 *  \brief PAL cryptographic - platform.
00024 *   This file contains cryptographic APIs that need to be implemented in the platform layer.
00025 */
00026 
00027 /*! Initiate the Crypto library. Initialization may not be required for some crypto libraries. In such
00028  * cases, the implementation may be empty.
00029  *
00030 \note This function must be called in the general PAL initializtion function.
00031 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00032 */
00033 palStatus_t pal_plat_initCrypto (void);
00034 
00035 /*! Free resources for the Crypto library.
00036 *
00037 \note This function must be called in the general PAL cleanup function.
00038 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00039 */
00040 palStatus_t pal_plat_cleanupCrypto (void);
00041 
00042 /*! Initialize AES context.
00043  *
00044  * @param[in,out] aes: AES context to be initialized.
00045  *
00046  \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00047  */
00048 palStatus_t pal_plat_initAes (palAesHandle_t *aes);
00049 
00050 /*! Free AES context.
00051  *
00052  * @param[in,out] aes: AES context to be deallocated.
00053  *
00054  \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00055  */
00056 palStatus_t pal_plat_freeAes (palAesHandle_t *aes);
00057 
00058 /*! Set AES key context for encryption or decryption.
00059  *
00060  * @param[in] aes: AES context.
00061  * @param[in] key: AES key.
00062  * @param[in] keybits: The size of the key in bits.
00063  * @param[in] keyTarget: The key target (encryption/decryption).
00064  *
00065  \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00066  */
00067 palStatus_t pal_plat_setAesKey (palAesHandle_t aes, const unsigned char* key, uint32_t keybits, palAesKeyType_t keyTarget);
00068 
00069 /*! AES-CTR buffer encryption/decryption.
00070  *
00071  * @param[in] aes: AES context.
00072  * @param[in] input: The input data buffer.
00073  * @param[out] output: The output data buffer.
00074  * @param[in] inLen: The length of the input data.
00075  * @param[in] iv: The initialization vector for AES-CTR.
00076  * @param[in] zeroOffset: Send offset value zero to platform function.
00077  *
00078  \note Due to the nature of CTR you should use the same key schedule for both encryption and decryption. 
00079  * So before calling this function you MUST call `pal_setAesKey()` with the key target PAL_KEY_TARGET_ENCRYPTION to set the key.
00080  * 
00081  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00082  */
00083 palStatus_t pal_plat_aesCTR (palAesHandle_t aes, const unsigned char* input, unsigned char* output, size_t inLen, unsigned char iv[16], bool zeroOffset);
00084 
00085 /*! AES-ECB block encryption/decryption.
00086  *
00087  * @param[in] aes: AES context.
00088  * @param[in] input: A 16-byte input block.
00089  * @param[out] output: A 16-byte output block.
00090  * @param[in] mode: PAL_AES_ENCRYPT or PAL_AES_DECRYPT
00091  *
00092  \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00093  */
00094 palStatus_t pal_plat_aesECB (palAesHandle_t aes, const unsigned char input[PAL_CRYPT_BLOCK_SIZE], unsigned char output[PAL_CRYPT_BLOCK_SIZE], palAesMode_t mode);
00095 
00096 /*! Process SHA256 over the input buffer.
00097  *
00098  * @param[in] input: A buffer for the input data.
00099  * @param[in] inLen: The length of the input data.
00100  * @param[out] output: SHA256 checksum result.
00101  *
00102  \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00103  */
00104 palStatus_t pal_plat_sha256 (const unsigned char* input, size_t inLen, unsigned char* output);
00105 
00106 /*! Initialize a certificate (chain) context.
00107  *
00108  * @param[in,out] x509Cert: The certificate chain to initialize.
00109  *
00110  \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00111  */
00112 palStatus_t pal_plat_x509Initiate (palX509Handle_t* x509);
00113 
00114 /*! Parse one or more certificates and add them to the chained list.
00115  *
00116  * @param[in] x509Cert: The start of the chain.
00117  * @param[in] input: A buffer holding the certificate data in PEM or DER format.
00118  * @param[in] inLen: The size of the input buffer.
00119  *
00120  \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00121  */
00122 palStatus_t pal_plat_x509CertParse (palX509Handle_t x509, const unsigned char* input, size_t inLen);
00123 
00124 /*! Get attributes from the parsed certificate.
00125 *
00126 * @param[in] x509Cert: The parsed certificate.
00127 * @param[in] attr: The required attribute.
00128 * @param[out] output: A buffer to hold the attribute value.
00129 * @param[in] outLenBytes: The size of the allocated buffer.
00130 * @param[out] actualOutLenBytes: The actual size of the attribute.
00131 *
00132 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00133 */
00134 palStatus_t pal_plat_x509CertGetAttribute (palX509Handle_t x509Cert, palX509Attr_t attr, void* output, size_t outLenBytes, size_t* actualOutLenBytes);
00135 
00136 /*! Verify one or more X509 DER formatted certificates.
00137  *
00138  * @param[in] x509Cert: A handle holding the parsed certificate.
00139  * @param[in] x509CertChain: The start of the chain to verify the X509 DER certificate with. (Optional) 
00140  *
00141  \return PAL_SUCCESS on success. In case of failure, one of the following:
00142 * 
00143 *       - PAL_ERR_X509_BADCERT_EXPIRED
00144 *       - PAL_ERR_X509_BADCERT_FUTURE
00145 *       - PAL_ERR_X509_BADCERT_BAD_MD
00146 *       - PAL_ERR_X509_BADCERT_BAD_PK
00147 *       - PAL_ERR_X509_BADCERT_NOT_TRUSTED
00148 *       - PAL_ERR_X509_BADCERT_BAD_KEY
00149 */
00150 palStatus_t pal_plat_x509CertVerify (palX509Handle_t x509Cert, palX509Handle_t x509CertChain);
00151 
00152 /*! Deallocate all certificate data.
00153  *
00154  * @param[in,out] x509: The certificate chain to free. 
00155  *
00156  \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00157  */
00158 palStatus_t pal_plat_x509Free (palX509Handle_t* x509);
00159 
00160 /*! Initialize an MD context and set up the required data according to the given algorithm.
00161  *
00162  * @param[in,out] md: The MD context to be initialized.
00163  * @param[in] mdType: The MD algorithm.
00164  *
00165  \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00166  */
00167 palStatus_t pal_plat_mdInit (palMDHandle_t* md, palMDType_t mdType);
00168 
00169 /*! Generic message digest process buffer.
00170  *
00171  * @param[in] md: The MD context.
00172  * @param[in] input: A buffer holding the input data.
00173  * @param[in] inLen: The length of the input data.
00174  *
00175  \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00176  */
00177 palStatus_t pal_plat_mdUpdate (palMDHandle_t md, const unsigned char* input, size_t inLen);
00178 
00179 /*! Generic message digest output buffer size getter.
00180  *
00181  * @param[in] md: The MD context.
00182  * @param[out] bufferSize: A pointer to hold the output size of the` pal_mdFinal()` for the given handle. 
00183  *
00184  \note You SHOULD call this function before calling `pal_mdFinal()`.
00185  \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00186  */
00187 palStatus_t pal_plat_mdGetOutputSize (palMDHandle_t md, size_t* bufferSize);
00188 
00189 /*! Generic message digest final digest.
00190  *
00191  * @param[in] md: The MD context.
00192  * @param[in] output: The generic message digest checksum result.
00193  *
00194  \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00195  */
00196 palStatus_t pal_plat_mdFinal (palMDHandle_t md, unsigned char* output);
00197 
00198 /*! Free and clear the MD context.
00199  *
00200  * @param[in,out] md: The AES context to be freed.
00201  *
00202  \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00203  */
00204 palStatus_t pal_plat_mdFree (palMDHandle_t* md);
00205 
00206 /*! Verify the signature.
00207  *
00208  * @param[in] x509: The certificate context that holds the PK data.
00209  * @param[in] mdType: The MD algorithm used.
00210  * @param[in] hash: The hash of the message to sign.
00211  * @param[in] hashLen: The hash length.
00212  * @param[in] sig: The signature to verify.
00213  * @param[in] sigLen: The signature length.
00214  *
00215  \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00216  */
00217 palStatus_t pal_plat_verifySignature (palX509Handle_t x509, palMDType_t mdType, const unsigned char *hash, size_t hashLen, const unsigned char *sig, size_t sigLen ); 
00218 
00219 /*! Get the tag and its length, check for the requested tag.
00220 *   Updates the pointer to immediately after the tag and length. 
00221  *
00222  * @param[in,out] position: The position in the ASN.1 data.
00223  * @param[in] end: The end of data.
00224  * @param[out] len: The tag length.
00225  * @param[in] tag: The expected tag.
00226  *
00227  \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00228  */
00229 palStatus_t pal_plat_ASN1GetTag (unsigned char **position, const unsigned char *end, size_t *len, uint8_t tag );
00230 
00231 /*! CCM initialization.
00232 *
00233 * @param[in] ctx: The CCM context to be initialized.
00234 *
00235 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00236 */
00237 palStatus_t pal_plat_CCMInit (palCCMHandle_t* ctx);
00238 
00239 /*! CCM destruction.
00240 *
00241 * @param[in] ctx: The CCM context to destroy.
00242 *
00243 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00244 */
00245 palStatus_t pal_plat_CCMFree (palCCMHandle_t* ctx);
00246 
00247 /*! CCM set key.
00248 *
00249 * @param[in] ctx:       The CCM context.
00250 * @param[in] id:        The cipher to use (a 128-bit block cipher).
00251 * @param[in] key:       The encryption key.
00252 * @param[in] keybits:   The key size in bits (must be acceptable by the cipher).
00253 *
00254 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00255 */
00256 palStatus_t pal_plat_CCMSetKey (palCCMHandle_t ctx, palCipherID_t id, const unsigned char *key, unsigned int keybits);
00257 
00258 /*! CCM buffer authenticated decryption.
00259 *
00260 * @param[in] ctx:       The CCM context.
00261 * @param[in] input      A buffer holding the input data.
00262 * @param[in] inLen:     The length of the input data.
00263 * @param[in] iv:        The initialization vector.
00264 * @param[in] ivLen:     The length of the IV.
00265 * @param[in] add:       Additional data.
00266 * @param[in] addLen:    The length of additional data.
00267 * @param[in] tag:       A buffer holding the tag.
00268 * @param[in] tag_len:   The length of the tag.
00269 * @param[out] output:   A buffer for holding the output data.
00270 *
00271 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00272 */
00273 palStatus_t pal_plat_CCMDecrypt (palCCMHandle_t ctx, unsigned char* input, size_t inLen, unsigned char* iv, size_t ivLen, unsigned char* add, size_t addLen, unsigned char* tag, size_t tagLen, unsigned char* output);
00274 
00275 /*! CCM buffer encryption.
00276 *
00277 * @param[in] ctx:       The CCM context.
00278 * @param[in] input      A buffer holding the input data.
00279 * @param[in] inLen:     The length of the input data.
00280 * @param[in] iv:        The initialization vector.
00281 * @param[in] ivLen:     The length of the IV.
00282 * @param[in] add:       Additional data.
00283 * @param[in] addLen:    The length of additional data.
00284 * @param[out] output:   A buffer for holding the output data, must be at least 'inLen' bytes wide.
00285 * @param[out] tag:      A buffer for holding the tag.
00286 * @param[out] tag_len:  The length of the tag to generate in bytes.
00287 *
00288 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00289 */
00290 palStatus_t pal_plat_CCMEncrypt (palCCMHandle_t ctx, unsigned char* input, size_t inLen, unsigned char* iv, size_t ivLen, unsigned char* add, size_t addLen, unsigned char* output, unsigned char* tag, size_t tagLen);
00291 
00292 /*! CTR_DRBG initialization.
00293 *
00294 * @param[in] ctx:   The CTR_DRBG context to be initialized.
00295 *
00296 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00297 */
00298 palStatus_t pal_plat_CtrDRBGInit (palCtrDrbgCtxHandle_t* ctx);
00299 
00300 /*! CTR_DRBG destroy.
00301 *
00302 * @param[in] ctx:   The CTR_DRBG context to destroy.
00303 *
00304 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00305 */
00306 palStatus_t pal_plat_CtrDRBGFree (palCtrDrbgCtxHandle_t* ctx);
00307 
00308 /*! CTR_DRBG initial seeding.
00309 *
00310 * @param[in] ctx:   The CTR_DRBG context to be seeded.
00311 * @param[in] seed:  The seed data.
00312 * @param[in] len:   The seed data length.
00313 *
00314 \return PAL_SUCCESS on success, negative value indicating a specific error code in case of failure.
00315 */
00316 palStatus_t pal_plat_CtrDRBGSeed (palCtrDrbgCtxHandle_t ctx, const void* seed, size_t len);
00317 
00318 /*! CTR_DRBG generate random.
00319 *
00320 * @param[in] ctx:   The CTR_DRBG context.
00321 * @param[in] out:   The buffer to fill.
00322 * @param[in] len:   The length of the buffer.
00323 *
00324 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00325 */
00326 palStatus_t pal_plat_CtrDRBGGenerate (palCtrDrbgCtxHandle_t ctx, unsigned char* out, size_t len);
00327 
00328 /*! AES cipher CMAC.
00329 *
00330 * @param[in] ctx:               The CMAC context to initialize.
00331 * @param[in] key:               The encryption key.
00332 * @param[in] keyLenInBits:      The key size in bits.
00333 * @param[in] input:             A buffer for the input data.
00334 * @param[in] inputLenInBytes:   The input data length in bytes.
00335 * @param[out] output:           Generic CMAC result.
00336 *
00337 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00338 */
00339 palStatus_t pal_plat_cipherCMAC (const unsigned char *key, size_t keyLenInBits, const unsigned char *input, size_t inputLenInBytes, unsigned char *output);
00340 
00341 /*! Iterative cipher CMAC start.
00342 *
00343 * @param[in] ctx:        The CMAC context to initialize.
00344 * @param[in] key:        The CMAC key.
00345 * @param[in] keyLenBits: The key size in bits.
00346 * @param[in] cipherID:   A buffer for the input data.
00347 *
00348 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00349 */
00350 palStatus_t pal_plat_CMACStart (palCMACHandle_t *ctx, const unsigned char *key, size_t keyLenBits, palCipherID_t cipherID);
00351 
00352 /*! Iterative cipher CMAC update.
00353 *
00354 * @param[in] ctx:       The CMAC context to initialize.
00355 * @param[in] input:     A buffer for the input data.
00356 * @param[in] inputLen:  The input data length.
00357 *
00358 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00359 */
00360 palStatus_t pal_plat_CMACUpdate (palCMACHandle_t ctx, const unsigned char *input, size_t inLen);
00361 
00362 /*! Iterative cipher CMAC finish.
00363 *
00364 * @param[in] ctx:       The CMAC context to initialize.
00365 * @param[out] output:   A buffer for the output data.
00366 * @param[out] outLen:   The output data length.
00367 *
00368 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00369 */
00370 palStatus_t pal_plat_CMACFinish (palCMACHandle_t *ctx, unsigned char *output, size_t* outLen);
00371 
00372 /*! One shot md HMAC.
00373 *
00374 * @param[in] key:               The encryption key.
00375 * @param[in] keyLenInBytes:     The key size in bytes.
00376 * @param[in] input:             A buffer for the input data.
00377 * @param[in] inputLenInBytes:   The input data length in bytes.
00378 * @param[out] output:           The generic HMAC result.
00379 * @param[out] outputLenInBytes: Size of the HMAC result (optional).
00380 *
00381 \note Expects output to be 32 bytes long
00382 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00383 */
00384 palStatus_t pal_plat_mdHmacSha256 (const unsigned char *key, size_t keyLenInBytes, const unsigned char *input, size_t inputLenInBytes, unsigned char *output, size_t* outputLenInBytes);
00385 
00386 
00387 /*! Check that the private and/or public key is a valid key and the public key is on this curve.
00388 *
00389 * @param[in] grp:       The curve/group the point should belong to.
00390 * @param[in] key:       A pointer to the struct that holds the keys to check.
00391 * @param[in] type:      PAL_CHECK_PRIVATE_KEY/PAL_CHECK_PUBLIC_KEY/PAL_CHECK_BOTH_KEYS
00392 * @param[out] verified: The result of the verification.
00393 *
00394 \note   The key can contain only private or public key or both.
00395 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00396 */
00397 palStatus_t pal_plat_ECCheckKey (palCurveHandle_t grp, palECKeyHandle_t key, uint32_t type, bool *verified);
00398 
00399 /*! Allocate key context and initialize a key pair (as an invalid one).
00400 *
00401 * @Param[in] key:   The key pair context to initialize
00402 *
00403 \return PAL_SUCCESS on success, negative value indicating a specific error code in case of failure.
00404 */
00405 palStatus_t pal_plat_ECKeyNew (palECKeyHandle_t* key);
00406 
00407 /*! Free the components of a key pair.
00408 *
00409 * @param[in] key:   The key to free.
00410 *
00411 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00412 */
00413 palStatus_t pal_plat_ECKeyFree (palECKeyHandle_t* key);
00414 
00415 /*! Parse a DER encoded private key.
00416 *
00417 * @param[in] prvDERKey: A buffer that holds the DER encoded private key.
00418 * @param[in] keyLen:   The key length.
00419 * @param[out] key:      A handle for the context that holds the parsed key.
00420 *
00421 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00422 */
00423 palStatus_t pal_plat_parseECPrivateKeyFromDER (const unsigned char* prvDERKey, size_t keyLen, palECKeyHandle_t key);
00424 
00425 /*! Parse a DER encoded public key.
00426 *
00427 * @param[in] pubDERKey: A buffer that holds the DER encoded public key.
00428 * @param[in] keyLen:    The key length.
00429 * @param[out] key:      A handle for the context that holds the parsed key.
00430 *
00431 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00432 */
00433 palStatus_t pal_plat_parseECPublicKeyFromDER (const unsigned char* pubDERKey, size_t keyLen, palECKeyHandle_t key);
00434 
00435 /*! Encode the given private key from the key handle to the DER buffer.
00436 *
00437 * @param[in] key:        A handle to the private key.
00438 * @param[out] derBuffer: A buffer to hold the result of the DER encoding.
00439 * @param[in] bufferSize: The size of the allocated buffer.
00440 * @param[out] actualSize: The actual size of the written data.
00441 *
00442 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00443 */
00444 palStatus_t pal_plat_writePrivateKeyToDer (palECKeyHandle_t key, unsigned char* derBuffer, size_t bufferSize, size_t* actualSize);
00445 
00446 /*! Encode the given public key from the key handle to the DER buffer.
00447 *
00448 * @param[in] key:        A handle to the public key.
00449 * @param[out] derBuffer: A buffer to hold the result of the DER encoding.
00450 * @param[in] bufferSize: The size of the allocated buffer.
00451 * @param[out] actualSize: The actual size of the written data.
00452 *
00453 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00454 */
00455 palStatus_t pal_plat_writePublicKeyToDer (palECKeyHandle_t key, unsigned char* derBuffer, size_t bufferSize, size_t* actualSize);
00456 
00457 /*!  Generate a keypair.
00458 *
00459 * @param[in] grpID: The ECP group identifier.
00460 * @param[in] key:   A handle to the destination keypair.
00461 *
00462 \note The `key` parameter must be first allocated by `pal_ECKeyNew()`.
00463 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00464 */
00465 palStatus_t pal_plat_ECKeyGenerateKey (palGroupIndex_t grpID, palECKeyHandle_t key);
00466 
00467 /*! Retrieve the curve ID if it exists in the given key. 
00468 *
00469 * @param[in] key: The key to retrieve its curve. 
00470 * @param[out] grpID: The curve/group ID for the given key. In case of error, this pointer contains "PAL_ECP_DP_NONE".
00471 *
00472 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00473 */
00474 palStatus_t pal_plat_ECKeyGetCurve (palECKeyHandle_t key, palGroupIndex_t* grpID);
00475 
00476 /*! Allocate and initialize the x509 CSR context.
00477 *
00478 * @param[in] x509CSR:   The CSR context to allocate and initialize. 
00479 *
00480 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00481 */
00482 palStatus_t pal_plat_x509CSRInit (palx509CSRHandle_t *x509CSR);
00483 
00484 /*! Set the subject name for a CSR. The subject names should contain a comma-separated list of OIDs and values.
00485 *
00486 * @param[in] x509CSR:     The CSR context to use.
00487 * @param[in] subjectName: The subject name to set.
00488 *
00489 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00490 */
00491 palStatus_t pal_plat_x509CSRSetSubject (palx509CSRHandle_t x509CSR, const char* subjectName);
00492 
00493 /*! Set the MD algorithm to use for the signature.
00494 *
00495 * @param[in] x509CSR:   The CSR context to use.
00496 * @param[in] mdType:    The MD algorithm to use.
00497 *
00498 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00499 */
00500 palStatus_t pal_plat_x509CSRSetMD (palx509CSRHandle_t x509CSR, palMDType_t mdType);
00501 
00502 /*! Set the key for a CSR.
00503 *
00504 * @param[in] x509CSR:   The CSR context to use.
00505 * @param[in] pubKey:    The public key to include. To use the keypair handle, see the note.
00506 * @param[in] prvKey:    The public key to sign with.
00507 *
00508 \note To use the keypair, please send it as `pubKey` and NULL as `prvKey`.
00509 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00510 */
00511 palStatus_t pal_plat_x509CSRSetKey (palx509CSRHandle_t x509CSR, palECKeyHandle_t pubKey, palECKeyHandle_t prvKey);
00512 
00513 /*! Set the key usage extension flags.
00514 *
00515 * @param[in] x509CSR:   The CSR context to use.
00516 * @param[in] keyUsage:  The key usage flags that should be taken from `palKeyUsage_t`.
00517 *
00518 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00519 */
00520 palStatus_t pal_plat_x509CSRSetKeyUsage (palx509CSRHandle_t x509CSR, uint32_t keyUsage);
00521 
00522 /*! Generic function to add to the CSR.
00523 *
00524 * @param[in] x509CSR:  The CSR context to use.
00525 * @param[in] oid:      The OID of the extension.
00526 * @param[in] oidLen:    The OID length.
00527 * @param[in] value:     The value of the extension OCTET STRING.
00528 * @param[in] valueLen:  The value length.
00529 *
00530 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00531 */
00532 palStatus_t pal_plat_x509CSRSetExtension (palx509CSRHandle_t x509CSR,const char* oid, size_t oidLen, const unsigned char* value, size_t valueLen);
00533 
00534 /*! Write a CSR to a DER structure.
00535 *
00536 * @param[in] x509CSR:      The CSR context to use.
00537 * @param[in] derBuf:        A buffer to write to.
00538 * @param[in] derBufLen:     The buffer length.
00539 * @param[in] actualDerLen:  The actual length of the written data.
00540 *
00541 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00542 */
00543 palStatus_t pal_plat_x509CSRWriteDER (palx509CSRHandle_t x509CSR, unsigned char* derBuf, size_t derBufLen, size_t* actualDerLen);
00544 
00545 /*! Free the x509 CSR context.
00546 *
00547 * @param[in] x509CSR:   The CSR context to free.
00548 *
00549 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00550 */
00551 palStatus_t pal_plat_x509CSRFree (palx509CSRHandle_t *x509CSR);
00552 
00553 /*! Compute a shared secret.
00554 *
00555 * @param[in] grp:           The ECP group.
00556 * @param[in] peerPublicKey: The public key from a peer.
00557 * @param[in] privateKey:    The private key.
00558 * @param[out] outKey:       The shared secret.
00559 *
00560 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00561 */
00562 palStatus_t pal_plat_ECDHComputeKey (const palCurveHandle_t grp, const palECKeyHandle_t peerPublicKey, const palECKeyHandle_t privateKey, palECKeyHandle_t outKey);
00563 
00564 /*! Compute the ECDSA signature of a previously hashed message.
00565 *
00566 * @param[in] grp:       The ECP group.
00567 * @param[in] prvKey:    The private signing key-
00568 * @param[in] dgst:      The message hash.
00569 * @param[in] dgstLen:   The length of the message buffer.
00570 * @param[out] sig:      A buffer to hold the computed signature.
00571 * @param[out] sigLen:  The length of the computed signature.
00572 *
00573 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00574 */
00575 palStatus_t pal_plat_ECDSASign (palCurveHandle_t grp, palMDType_t mdType, palECKeyHandle_t prvKey, unsigned char* dgst, uint32_t dgstLen, unsigned char *sig, size_t *sigLen);
00576 
00577 /*! Verify the ECDSA signature of a previously hashed message.
00578 *
00579 * @param[in] pubKey:    The public key for verification.
00580 * @param[in] dgst:      The message hash.
00581 * @param[in] dgstLen:   The length of the message buffer.
00582 * @param[in] sign:      The signature.
00583 * @param[in] sig:       A buffer to hold the computed signature.
00584 * @param[in] sigLen:    The length of the computed signature.
00585 * @param[out] verified: The boolean to hold the verification result.
00586 *
00587 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00588 */
00589 palStatus_t pal_plat_ECDSAVerify (palECKeyHandle_t pubKey, unsigned char* dgst, uint32_t dgstLen, unsigned char* sig, size_t sigLen, bool* verified);
00590 
00591 /*! Free the components of an ECP group.
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_plat_ECGroupFree (palCurveHandle_t* grp);
00598 
00599 /*! ECP group initialize and set a group using well-known domain parameters.
00600 *
00601 * @param[in] grp:   The destination group.
00602 * @param[in] index: The index in the list of well-known domain parameters.
00603 *
00604 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00605 */
00606 palStatus_t pal_plat_ECGroupInitAndLoad (palCurveHandle_t* grp, palGroupIndex_t index);
00607 
00608 #endif //_PAL_PLAT_CRYPTO_H_