pal_plat_Crypto.h

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_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  * @param[out] verifyResult: bitmask of errors that cause the failure, this value is 
00141 *                           relevant ONLY in case that the return value of the function is `PAL_ERR_X509_CERT_VERIFY_FAILED`.
00142 *
00143 \note In case platform doesn't support multipule errors for certificate verification, please return `PAL_ERR_X509_CERT_VERIFY_FAILED` and the reason should be specified in the `verifyResult`
00144 \return PAL_SUCCESS on success. In case of failure returns `PAL_ERR_X509_CERT_VERIFY_FAILED`.
00145 */
00146 palStatus_t pal_plat_x509CertVerifyExtended (palX509Handle_t x509Cert, palX509Handle_t x509CertChain, int32_t* verifyResult);
00147 
00148 /*! Deallocate all certificate data.
00149  *
00150  * @param[in,out] x509: The certificate chain to free. 
00151  *
00152  \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00153  */
00154 palStatus_t pal_plat_x509Free (palX509Handle_t* x509);
00155 
00156 /*! Initialize an MD context and set up the required data according to the given algorithm.
00157  *
00158  * @param[in,out] md: The MD context to be initialized.
00159  * @param[in] mdType: The MD algorithm.
00160  *
00161  \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00162  */
00163 palStatus_t pal_plat_mdInit (palMDHandle_t* md, palMDType_t mdType);
00164 
00165 /*! Generic message digest process buffer.
00166  *
00167  * @param[in] md: The MD context.
00168  * @param[in] input: A buffer holding the input data.
00169  * @param[in] inLen: The length of the input data.
00170  *
00171  \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00172  */
00173 palStatus_t pal_plat_mdUpdate (palMDHandle_t md, const unsigned char* input, size_t inLen);
00174 
00175 /*! Generic message digest output buffer size getter.
00176  *
00177  * @param[in] md: The MD context.
00178  * @param[out] bufferSize: A pointer to hold the output size of the` pal_mdFinal()` for the given handle. 
00179  *
00180  \note You SHOULD call this function before calling `pal_mdFinal()`.
00181  \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00182  */
00183 palStatus_t pal_plat_mdGetOutputSize (palMDHandle_t md, size_t* bufferSize);
00184 
00185 /*! Generic message digest final digest.
00186  *
00187  * @param[in] md: The MD context.
00188  * @param[in] output: The generic message digest checksum result.
00189  *
00190  \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00191  */
00192 palStatus_t pal_plat_mdFinal (palMDHandle_t md, unsigned char* output);
00193 
00194 /*! Free and clear the MD context.
00195  *
00196  * @param[in,out] md: The AES context to be freed.
00197  *
00198  \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00199  */
00200 palStatus_t pal_plat_mdFree (palMDHandle_t* md);
00201 
00202 /*! Verify the signature.
00203  *
00204  * @param[in] x509: The certificate context that holds the PK data.
00205  * @param[in] mdType: The MD algorithm used.
00206  * @param[in] hash: The hash of the message to sign.
00207  * @param[in] hashLen: The hash length.
00208  * @param[in] sig: The signature to verify.
00209  * @param[in] sigLen: The signature length.
00210  *
00211  \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00212  */
00213 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 ); 
00214 
00215 /*! Get the tag and its length, check for the requested tag.
00216 *   Updates the pointer to immediately after the tag and length. 
00217  *
00218  * @param[in,out] position: The position in the ASN.1 data.
00219  * @param[in] end: The end of data.
00220  * @param[out] len: The tag length.
00221  * @param[in] tag: The expected tag.
00222  *
00223  \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00224  */
00225 palStatus_t pal_plat_ASN1GetTag (unsigned char **position, const unsigned char *end, size_t *len, uint8_t tag );
00226 
00227 /*! CCM initialization.
00228 *
00229 * @param[in] ctx: The CCM context to be initialized.
00230 *
00231 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00232 */
00233 palStatus_t pal_plat_CCMInit (palCCMHandle_t* ctx);
00234 
00235 /*! CCM destruction.
00236 *
00237 * @param[in] ctx: The CCM context to destroy.
00238 *
00239 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00240 */
00241 palStatus_t pal_plat_CCMFree (palCCMHandle_t* ctx);
00242 
00243 /*! CCM set key.
00244 *
00245 * @param[in] ctx:       The CCM context.
00246 * @param[in] id:        The cipher to use (a 128-bit block cipher).
00247 * @param[in] key:       The encryption key.
00248 * @param[in] keybits:   The key size in bits (must be acceptable by the cipher).
00249 *
00250 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00251 */
00252 palStatus_t pal_plat_CCMSetKey (palCCMHandle_t ctx, palCipherID_t id, const unsigned char *key, unsigned int keybits);
00253 
00254 /*! CCM buffer authenticated decryption.
00255 *
00256 * @param[in] ctx:       The CCM context.
00257 * @param[in] input      A buffer holding the input data.
00258 * @param[in] inLen:     The length of the input data.
00259 * @param[in] iv:        The initialization vector.
00260 * @param[in] ivLen:     The length of the IV.
00261 * @param[in] add:       Additional data.
00262 * @param[in] addLen:    The length of additional data.
00263 * @param[in] tag:       A buffer holding the tag.
00264 * @param[in] tag_len:   The length of the tag.
00265 * @param[out] output:   A buffer for holding the output data.
00266 *
00267 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00268 */
00269 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);
00270 
00271 /*! CCM buffer encryption.
00272 *
00273 * @param[in] ctx:       The CCM context.
00274 * @param[in] input      A buffer holding the input data.
00275 * @param[in] inLen:     The length of the input data.
00276 * @param[in] iv:        The initialization vector.
00277 * @param[in] ivLen:     The length of the IV.
00278 * @param[in] add:       Additional data.
00279 * @param[in] addLen:    The length of additional data.
00280 * @param[out] output:   A buffer for holding the output data, must be at least 'inLen' bytes wide.
00281 * @param[out] tag:      A buffer for holding the tag.
00282 * @param[out] tag_len:  The length of the tag to generate in bytes.
00283 *
00284 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00285 */
00286 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);
00287 
00288 /*! CTR_DRBG initialization.
00289 *
00290 * @param[in] ctx:   The CTR_DRBG context to be initialized.
00291 *
00292 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00293 */
00294 palStatus_t pal_plat_CtrDRBGInit (palCtrDrbgCtxHandle_t* ctx);
00295 
00296 /*! CTR_DRBG destroy.
00297 *
00298 * @param[in] ctx:   The CTR_DRBG context to destroy.
00299 *
00300 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00301 */
00302 palStatus_t pal_plat_CtrDRBGFree (palCtrDrbgCtxHandle_t* ctx);
00303 
00304 /*! CTR_DRBG initial seeding.
00305 *
00306 * @param[in] ctx:   The CTR_DRBG context to be seeded.
00307 * @param[in] seed:  The seed data.
00308 * @param[in] len:   The seed data length.
00309 *
00310 \return PAL_SUCCESS on success, negative value indicating a specific error code in case of failure.
00311 */
00312 palStatus_t pal_plat_CtrDRBGSeed (palCtrDrbgCtxHandle_t ctx, const void* seed, size_t len);
00313 
00314 /*! CTR_DRBG generate random.
00315 *
00316 * @param[in] ctx:   The CTR_DRBG context.
00317 * @param[in] out:   The buffer to fill.
00318 * @param[in] len:   The length of the buffer.
00319 *
00320 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00321 */
00322 palStatus_t pal_plat_CtrDRBGGenerate (palCtrDrbgCtxHandle_t ctx, unsigned char* out, size_t len);
00323 
00324 /*! CTR_DRBG generate random with additional update input.
00325 *
00326 * @param[in] ctx:   The CTR_DRBG context.
00327 * @param[in] out:   The buffer to fill.
00328 * @param[in] len:   The length of the buffer.
00329 * @param[in] additional:    Additional data to update with.
00330 * @param[in] additionalLen: Length of additional data.
00331 *
00332 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00333 */
00334 palStatus_t pal_plat_CtrDRBGGenerateWithAdditional(palCtrDrbgCtxHandle_t ctx, unsigned char* out, size_t len, unsigned char* additional, size_t additionalLen);
00335 
00336 #if PAL_CMAC_SUPPORT
00337 
00338 /*! AES cipher CMAC.
00339 *
00340 * @param[in] ctx:               The CMAC context to initialize.
00341 * @param[in] key:               The encryption key.
00342 * @param[in] keyLenInBits:      The key size in bits.
00343 * @param[in] input:             A buffer for the input data.
00344 * @param[in] inputLenInBytes:   The input data length in bytes.
00345 * @param[out] output:           Generic CMAC result.
00346 *
00347 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00348 */
00349 palStatus_t pal_plat_cipherCMAC (const unsigned char *key, size_t keyLenInBits, const unsigned char *input, size_t inputLenInBytes, unsigned char *output);
00350 
00351 /*! Iterative cipher CMAC start.
00352 *
00353 * @param[in] ctx:        The CMAC context to initialize.
00354 * @param[in] key:        The CMAC key.
00355 * @param[in] keyLenBits: The key size in bits.
00356 * @param[in] cipherID:   A buffer for the input data.
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_CMACStart (palCMACHandle_t *ctx, const unsigned char *key, size_t keyLenBits, palCipherID_t cipherID);
00361 
00362 /*! Iterative cipher CMAC update.
00363 *
00364 * @param[in] ctx:       The CMAC context to initialize.
00365 * @param[in] input:     A buffer for the input data.
00366 * @param[in] inputLen:  The input 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_CMACUpdate (palCMACHandle_t ctx, const unsigned char *input, size_t inLen);
00371 
00372 /*! Iterative cipher CMAC finish.
00373 *
00374 * @param[in] ctx:       The CMAC context to initialize.
00375 * @param[out] output:   A buffer for the output data.
00376 * @param[out] outLen:   The output data length.
00377 *
00378 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00379 */
00380 palStatus_t pal_plat_CMACFinish (palCMACHandle_t *ctx, unsigned char *output, size_t* outLen);
00381 
00382 #endif //PAL_CMAC_SUPPORT
00383 
00384 /*! One shot md HMAC.
00385 *
00386 * @param[in] key:               The encryption key.
00387 * @param[in] keyLenInBytes:     The key size in bytes.
00388 * @param[in] input:             A buffer for the input data.
00389 * @param[in] inputLenInBytes:   The input data length in bytes.
00390 * @param[out] output:           The generic HMAC result.
00391 * @param[out] outputLenInBytes: Size of the HMAC result (optional).
00392 *
00393 \note Expects output to be 32 bytes long
00394 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00395 */
00396 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);
00397 
00398 
00399 /*! Check that the private and/or public key is a valid key and the public key is on this curve.
00400 *
00401 * @param[in] grp:       The curve/group the point should belong to.
00402 * @param[in] key:       A pointer to the struct that holds the keys to check.
00403 * @param[in] type:      PAL_CHECK_PRIVATE_KEY/PAL_CHECK_PUBLIC_KEY/PAL_CHECK_BOTH_KEYS
00404 * @param[out] verified: The result of the verification.
00405 *
00406 \note   The key can contain only private or public key or both.
00407 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00408 */
00409 palStatus_t pal_plat_ECCheckKey (palCurveHandle_t grp, palECKeyHandle_t key, uint32_t type, bool *verified);
00410 
00411 /*! Allocate key context and initialize a key pair (as an invalid one).
00412 *
00413 * @Param[in] key:   The key pair context to initialize
00414 *
00415 \return PAL_SUCCESS on success, negative value indicating a specific error code in case of failure.
00416 */
00417 palStatus_t pal_plat_ECKeyNew (palECKeyHandle_t* key);
00418 
00419 /*! Free the components of a key pair.
00420 *
00421 * @param[in] key:   The key to free.
00422 *
00423 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00424 */
00425 palStatus_t pal_plat_ECKeyFree (palECKeyHandle_t* key);
00426 
00427 /*! Parse a DER encoded private key.
00428 *
00429 * @param[in] prvDERKey: A buffer that holds the DER encoded private key.
00430 * @param[in] keyLen:   The key length.
00431 * @param[out] key:      A handle for the context that holds the parsed key.
00432 *
00433 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00434 */
00435 palStatus_t pal_plat_parseECPrivateKeyFromDER (const unsigned char* prvDERKey, size_t keyLen, palECKeyHandle_t key);
00436 
00437 /*! Parse a DER encoded public key.
00438 *
00439 * @param[in] pubDERKey: A buffer that holds the DER encoded public key.
00440 * @param[in] keyLen:    The key length.
00441 * @param[out] key:      A handle for the context that holds the parsed key.
00442 *
00443 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00444 */
00445 palStatus_t pal_plat_parseECPublicKeyFromDER (const unsigned char* pubDERKey, size_t keyLen, palECKeyHandle_t key);
00446 
00447 /*! Encode the given private key from the key handle to the DER buffer.
00448 *
00449 * @param[in] key:        A handle to the private key.
00450 * @param[out] derBuffer: A buffer to hold the result of the DER encoding.
00451 * @param[in] bufferSize: The size of the allocated buffer.
00452 * @param[out] actualSize: The actual size of the written 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_plat_writePrivateKeyToDer (palECKeyHandle_t key, unsigned char* derBuffer, size_t bufferSize, size_t* actualSize);
00457 
00458 /*! Encode the given public key from the key handle to the DER buffer.
00459 *
00460 * @param[in] key:        A handle to the public key.
00461 * @param[out] derBuffer: A buffer to hold the result of the DER encoding.
00462 * @param[in] bufferSize: The size of the allocated buffer.
00463 * @param[out] actualSize: The actual size of the written data.
00464 *
00465 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00466 */
00467 palStatus_t pal_plat_writePublicKeyToDer (palECKeyHandle_t key, unsigned char* derBuffer, size_t bufferSize, size_t* actualSize);
00468 
00469 /*!  Generate a keypair.
00470 *
00471 * @param[in] grpID: The ECP group identifier.
00472 * @param[in] key:   A handle to the destination keypair.
00473 *
00474 \note The `key` parameter must be first allocated by `pal_ECKeyNew()`.
00475 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00476 */
00477 palStatus_t pal_plat_ECKeyGenerateKey (palGroupIndex_t grpID, palECKeyHandle_t key);
00478 
00479 /*! Retrieve the curve ID if it exists in the given key. 
00480 *
00481 * @param[in] key: The key to retrieve its curve. 
00482 * @param[out] grpID: The curve/group ID for the given key. In case of error, this pointer contains "PAL_ECP_DP_NONE".
00483 *
00484 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00485 */
00486 palStatus_t pal_plat_ECKeyGetCurve (palECKeyHandle_t key, palGroupIndex_t* grpID);
00487 
00488 /*! Allocate and initialize the x509 CSR context.
00489 *
00490 * @param[in] x509CSR:   The CSR context to allocate and initialize. 
00491 *
00492 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00493 */
00494 palStatus_t pal_plat_x509CSRInit (palx509CSRHandle_t *x509CSR);
00495 
00496 /*! Set the subject name for a CSR. The subject names should contain a comma-separated list of OIDs and values.
00497 *
00498 * @param[in] x509CSR:     The CSR context to use.
00499 * @param[in] subjectName: The subject name to set.
00500 *
00501 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00502 */
00503 palStatus_t pal_plat_x509CSRSetSubject (palx509CSRHandle_t x509CSR, const char* subjectName);
00504 
00505 /*! Set the MD algorithm to use for the signature.
00506 *
00507 * @param[in] x509CSR:   The CSR context to use.
00508 * @param[in] mdType:    The MD algorithm to use.
00509 *
00510 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00511 */
00512 palStatus_t pal_plat_x509CSRSetMD (palx509CSRHandle_t x509CSR, palMDType_t mdType);
00513 
00514 /*! Set the key for a CSR.
00515 *
00516 * @param[in] x509CSR:   The CSR context to use.
00517 * @param[in] pubKey:    The public key to include. To use the keypair handle, see the note.
00518 * @param[in] prvKey:    The public key to sign with.
00519 *
00520 \note To use the keypair, please send it as `pubKey` and NULL as `prvKey`.
00521 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00522 */
00523 palStatus_t pal_plat_x509CSRSetKey (palx509CSRHandle_t x509CSR, palECKeyHandle_t pubKey, palECKeyHandle_t prvKey);
00524 
00525 /*! Set the key usage extension flags.
00526 *
00527 * @param[in] x509CSR:   The CSR context to use.
00528 * @param[in] keyUsage:  The key usage flags that should be taken from `palKeyUsage_t`.
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_x509CSRSetKeyUsage (palx509CSRHandle_t x509CSR, uint32_t keyUsage);
00533 
00534 /*! Set the extended key usage extension.
00535 *
00536 * @param[in] x509CSR:   The CSR context to use.
00537 * @param[in] extKeyUsage:  The extended key usage flags, should be taken from `palExtKeyUsage_t`.
00538 *
00539 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00540 */
00541 palStatus_t pal_plat_x509CSRSetExtendedKeyUsage (palx509CSRHandle_t x509CSR, uint32_t extKeyUsage);
00542 
00543 /*! Generic function to add to the CSR.
00544 *
00545 * @param[in] x509CSR:  The CSR context to use.
00546 * @param[in] oid:      The OID of the extension.
00547 * @param[in] oidLen:    The OID length.
00548 * @param[in] value:     The value of the extension OCTET STRING.
00549 * @param[in] valueLen:  The value length.
00550 *
00551 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00552 */
00553 palStatus_t pal_plat_x509CSRSetExtension (palx509CSRHandle_t x509CSR,const char* oid, size_t oidLen, const unsigned char* value, size_t valueLen);
00554 
00555 /*! Write a CSR to a DER structure.
00556 *
00557 * @param[in] x509CSR:      The CSR context to use.
00558 * @param[in] derBuf:        A buffer to write to.
00559 * @param[in] derBufLen:     The buffer length.
00560 * @param[in] actualDerLen:  The actual length of the written data.
00561 *
00562 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00563 */
00564 palStatus_t pal_plat_x509CSRWriteDER (palx509CSRHandle_t x509CSR, unsigned char* derBuf, size_t derBufLen, size_t* actualDerLen);
00565 
00566 /*! Calculate the hash of the To Be Signed part of an X509 certificate.
00567 * 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
00568 *
00569 * @param[in] x509Cert:          Handle to the certificate to hash the TBS (to be signed part). 
00570 * @param[in] hash_type:         The hash type. Currently only PAL_SHA256 supported
00571 * @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. 
00572 * @param[in] outLenBytes:       The size of the buffer pointed to by output. Must be at least the size of the digest
00573 * @param[out] actualOutLenBytes:    Size of the digest copied to output. In case of success, will always be the length of the hash digest
00574 *
00575 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00576 */
00577 palStatus_t pal_plat_x509CertGetHTBS (palX509Handle_t x509Cert, palMDType_t hash_type, unsigned char* output, size_t outLenBytes, size_t* actualOutLenBytes);
00578 
00579 /*! Free the x509 CSR context.
00580 *
00581 * @param[in] x509CSR:   The CSR context to free.
00582 *
00583 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00584 */
00585 palStatus_t pal_plat_x509CSRFree (palx509CSRHandle_t *x509CSR);
00586 
00587 /*! Compute a shared secret.
00588 *
00589 * @param[in] grp:           The ECP group.
00590 * @param[in] peerPublicKey: The public key from a peer.
00591 * @param[in] privateKey:    The private key.
00592 * @param[out] outKey:       The shared secret.
00593 *
00594 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00595 */
00596 palStatus_t pal_plat_ECDHComputeKey (const palCurveHandle_t grp, const palECKeyHandle_t peerPublicKey, const palECKeyHandle_t privateKey, palECKeyHandle_t outKey);
00597 
00598 /*! Compute the ECDSA signature of a previously hashed message.
00599 *
00600 * @param[in] grp:       The ECP group.
00601 * @param[in] prvKey:    The private signing key-
00602 * @param[in] dgst:      The message hash.
00603 * @param[in] dgstLen:   The length of the message buffer.
00604 * @param[out] sig:      A buffer to hold the computed signature.
00605 * @param[out] sigLen:  The length of the computed signature.
00606 *
00607 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00608 */
00609 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);
00610 
00611 /*! Verify the ECDSA signature of a previously hashed message.
00612 *
00613 * @param[in] pubKey:    The public key for verification.
00614 * @param[in] dgst:      The message hash.
00615 * @param[in] dgstLen:   The length of the message buffer.
00616 * @param[in] sign:      The signature.
00617 * @param[in] sig:       A buffer to hold the computed signature.
00618 * @param[in] sigLen:    The length of the computed signature.
00619 * @param[out] verified: The boolean to hold the verification result.
00620 *
00621 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00622 */
00623 palStatus_t pal_plat_ECDSAVerify (palECKeyHandle_t pubKey, unsigned char* dgst, uint32_t dgstLen, unsigned char* sig, size_t sigLen, bool* verified);
00624 
00625 /*! Free the components of an ECP group.
00626 *
00627 * @param[in] grp:   The curve/group to free.
00628 *
00629 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00630 */
00631 palStatus_t pal_plat_ECGroupFree (palCurveHandle_t* grp);
00632 
00633 /*! ECP group initialize and set a group using well-known domain parameters.
00634 *
00635 * @param[in] grp:   The destination group.
00636 * @param[in] index: The index in the list of well-known domain parameters.
00637 *
00638 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00639 */
00640 palStatus_t pal_plat_ECGroupInitAndLoad (palCurveHandle_t* grp, palGroupIndex_t index);
00641 
00642 
00643 #endif //_PAL_PLAT_CRYPTO_H_