1 /* 2 * This file is part of the openHiTLS project. 3 * 4 * openHiTLS is licensed under the Mulan PSL v2. 5 * You can use this software according to the terms and conditions of the Mulan PSL v2. 6 * You may obtain a copy of Mulan PSL v2 at: 7 * 8 * http://license.coscl.org.cn/MulanPSL2 9 * 10 * THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, 11 * EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, 12 * MERCHANTABILITY OR FIT FOR A PARTICULAR PURPOSE. 13 * See the Mulan PSL v2 for more details. 14 */ 15 16 #ifndef AUTH_PRIVPASS_TOKEN_H 17 #define AUTH_PRIVPASS_TOKEN_H 18 19 #include <stdint.h> 20 #include "bsl_params.h" 21 #include "bsl_obj.h" 22 23 #ifdef __cplusplus 24 extern "C" { 25 #endif 26 27 /** 28 * @ingroup auth_privpass 29 * 30 * priv pass context structure. 31 */ 32 typedef struct PrivPass_Ctx HITLS_AUTH_PrivPassCtx; 33 34 /** 35 * @ingroup auth_privpass 36 * 37 * priv pass token structure. 38 */ 39 typedef struct PrivPass_Token HITLS_AUTH_PrivPassToken; 40 41 /* Token types for different stages of the Private Pass protocol */ 42 typedef enum { 43 HITLS_AUTH_PRIVPASS_TOKEN_CHALLENGE_REQUEST = 1, // Initial request for challenge 44 HITLS_AUTH_PRIVPASS_TOKEN_CHALLENGE = 2, // Challenge from server 45 HITLS_AUTH_PRIVPASS_TOKEN_REQUEST = 3, // Token request with blinded message 46 HITLS_AUTH_PRIVPASS_TOKEN_RESPONSE = 4, // Server's response with blind signature 47 HITLS_AUTH_PRIVPASS_TOKEN_INSTANCE = 5, // Final token instance 48 } HITLS_AUTH_PrivPassTokenType; 49 50 /* Token types for different stages of the Private Pass protocol */ 51 typedef enum { 52 HITLS_AUTH_PRIVPASS_PRV_VERIFY_TOKENS = 1, // Private key verification tokens 53 HITLS_AUTH_PRIVPASS_PUB_VERIFY_TOKENS = 2, // Public key verification tokens 54 } HITLS_AUTH_PrivPassType; 55 56 /* Commands for token operations and parameter retrieval */ 57 typedef enum { 58 HITLS_AUTH_PRIVPASS_GET_TOKENCHALLENGEREQUEST_INFO = 1, /** Get the challenge request information from token */ 59 HITLS_AUTH_PRIVPASS_GET_TOKENCHALLENGE_TYPE = 2, /** Get the type of token challenge */ 60 HITLS_AUTH_PRIVPASS_GET_TOKENCHALLENGE_ISSUERNAME = 3, /** Get the issuer name from token challenge */ 61 HITLS_AUTH_PRIVPASS_GET_TOKENCHALLENGE_REDEMPTION = 4, /** Get the redemption information from token challenge */ 62 HITLS_AUTH_PRIVPASS_GET_TOKENCHALLENGE_ORIGININFO = 5, /** Get the origin information from token challenge */ 63 HITLS_AUTH_PRIVPASS_GET_TOKENREQUEST_TYPE = 6, /** Get the type of token request */ 64 HITLS_AUTH_PRIVPASS_GET_TOKENREQUEST_TRUNCATEDTOKENKEYID = 7, /** Get the truncated tokenKey id from tokenRequest */ 65 HITLS_AUTH_PRIVPASS_GET_TOKENREQUEST_BLINDEDMSG = 8, /** Get the blinded message from token request */ 66 HITLS_AUTH_PRIVPASS_GET_TOKENRESPONSE_INFO = 9, /** Get the origin information from token response */ 67 HITLS_AUTH_PRIVPASS_GET_TOKEN_TYPE = 10, /** Get the nonce value from token */ 68 HITLS_AUTH_PRIVPASS_GET_TOKEN_NONCE = 11, /** Get the nonce value from token */ 69 HITLS_AUTH_PRIVPASS_GET_TOKEN_CHALLENGEDIGEST = 12, /** Get the challenge digest from token */ 70 HITLS_AUTH_PRIVPASS_GET_TOKEN_TOKENKEYID = 13, /** Get the token key id from token */ 71 HITLS_AUTH_PRIVPASS_GET_TOKEN_AUTHENTICATOR = 14, /** Get the authenticator from token */ 72 HITLS_AUTH_PRIVPASS_GET_CTX_TOKENKEYID = 15, /** Get the token key id from ctx */ 73 HITLS_AUTH_PRIVPASS_GET_CTX_TRUNCATEDTOKENKEYID = 16, /** Get the truncated token key id from ctx */ 74 HITLS_AUTH_PRIVPASS_GET_CTX_NONCE = 17, /** Get the nonce from ctx */ 75 } HITLS_AUTH_PrivPassCmd; 76 77 typedef enum { 78 HITLS_AUTH_PRIVPASS_CRYPTO_RSA = BSL_CID_RSA, 79 HITLS_AUTH_PRIVPASS_CRYPTO_SHA256 = BSL_CID_SHA256, 80 HITLS_AUTH_PRIVPASS_CRYPTO_SHA384 = BSL_CID_SHA384, 81 } HITLS_AUTH_PrivPassCryptAlgId; 82 83 typedef enum { 84 HITLS_AUTH_PRIVPASS_NEW_PKEY_CTX_CB = 1, 85 HITLS_AUTH_PRIVPASS_FREE_PKEY_CTX_CB = 2, 86 HITLS_AUTH_PRIVPASS_DIGEST_CB = 3, 87 HITLS_AUTH_PRIVPASS_BLIND_CB = 4, 88 HITLS_AUTH_PRIVPASS_UNBLIND_CB = 5, 89 HITLS_AUTH_PRIVPASS_SIGNDATA_CB = 6, 90 HITLS_AUTH_PRIVPASS_VERIFY_CB = 7, 91 HITLS_AUTH_PRIVPASS_DECODE_PUBKEY_CB = 8, 92 HITLS_AUTH_PRIVPASS_DECODE_PRVKEY_CB = 9, 93 HITLS_AUTH_PRIVPASS_CHECK_KEYPAIR_CB = 10, 94 HITLS_AUTH_PRIVPASS_RANDOM_CB = 11, 95 } HITLS_AUTH_PrivPassCryptCbType; 96 97 /** 98 * @ingroup auth_privpass 99 * @brief Creates a new public/private key context for the specified algorithm. 100 * 101 * @param libCtx [IN] Library context 102 * @param attrName [IN] Specify expected attribute values 103 * @param algId [IN] Algorithm identifier, defined in HITLS_AUTH_PrivPassCryptAlgId. 104 * 105 * @retval Pointer to the created key context. 106 * NULL, if the operation fails. 107 */ 108 typedef void *(*HITLS_AUTH_PrivPassNewPkeyCtx)(void *libCtx, const char *attrName, int32_t algId); 109 110 /** 111 * @ingroup auth_privpass 112 * @brief Frees a previously allocated key context. 113 * 114 * @param pkeyCtx [IN] Key context to be freed 115 */ 116 typedef void (*HITLS_AUTH_PrivPassFreePkeyCtx)(void *pkeyCtx); 117 118 /** 119 * @ingroup auth_privpass 120 * @brief Computes a cryptographic digest of the input data. 121 * @param libCtx [IN] Library context 122 * @param attrName [IN] Specify expected attribute values 123 * @param algId [IN] Algorithm identifier, defined in HITLS_AUTH_PrivPassCryptAlgId. 124 * @param input [IN] Input data to be hashed 125 * @param inputLen [IN] Length of input data 126 * @param digest [OUT] Buffer to store the computed digest 127 * @param digestLen [IN/OUT] Size of digest buffer/Length of computed digest 128 * 129 * @retval #0, if successful. 130 * other error codes, failed. 131 */ 132 typedef int32_t (*HITLS_AUTH_PrivPassDigest)(void *libCtx, const char *attrName, int32_t algId, const uint8_t *input, 133 uint32_t inputLen, uint8_t *digest, uint32_t *digestLen); 134 135 /** 136 * @ingroup auth_privpass 137 * @brief Blinds data using the key context and hash algorithm for blind signature protocol. The default algorithm 138 * callback implementation is supported only from RSASSA-PSS. 139 * 140 * @param pkeyCtx [IN] Key context 141 * @param algId [IN] hash algorithm identifier 142 * @param data [IN] Data to be blinded 143 * @param dataLen [IN] Length of input data 144 * @param blindedData [OUT] Buffer to store blinded data 145 * @param blindedDataLen [IN/OUT] Size of buffer/Length of blinded data 146 * 147 * @retval #0, if successful. 148 * other error codes, failed. 149 */ 150 typedef int32_t (*HITLS_AUTH_PrivPassBlind)(void *pkeyCtx, int32_t algId, const uint8_t *data, 151 uint32_t dataLen, uint8_t *blindedData, uint32_t *blindedDataLen); 152 153 /** 154 * @ingroup auth_privpass 155 * @brief Unblinds previously blinded data to reveal the actual signature. The default algorithm callback 156 * implementation is supported only from RSASSA-PSS. 157 * 158 * @param pkeyCtx [IN] Key context 159 * @param blindedData [IN] Blinded data to be unblinded 160 * @param blindedDataLen [IN] Length of blinded data 161 * @param data [OUT] Buffer to store unblinded data 162 * @param dataLen [IN/OUT] Size of buffer/Length of unblinded data 163 * 164 * @retval #0, if successful. 165 * other error codes, failed. 166 */ 167 typedef int32_t (*HITLS_AUTH_PrivPassUnblind)(void *pkeyCtx, const uint8_t *blindedData, 168 uint32_t blindedDataLen, uint8_t *data, uint32_t *dataLen); 169 170 /** 171 * @ingroup auth_privpass 172 * @brief Signs data using the private key context. 173 * 174 * @param pkeyCtx [IN] Private key context 175 * @param data [IN] Data to be signed 176 * @param dataLen [IN] Length of input data 177 * @param sign [OUT] Buffer to store signature 178 * @param signLen [IN/OUT] Size of buffer/Length of signature 179 * 180 * @retval #0, if successful. 181 * other error codes, failed. 182 */ 183 typedef int32_t (*HITLS_AUTH_PrivPassSignData)(void *pkeyCtx, const uint8_t *data, uint32_t dataLen, 184 uint8_t *sign, uint32_t *signLen); 185 186 /** 187 * @ingroup auth_privpass 188 * @brief Verifies a signature using the public key context. 189 * 190 * @param pkeyCtx [IN] Public key context 191 * @param algId [IN] hash algorithm identifier 192 * @param data [IN] Original data 193 * @param dataLen [IN] Length of data 194 * @param sign [IN] Signature to verify 195 * @param signLen [IN] Length of signature 196 * 197 * @retval #0, if successful. 198 * other error codes, failed. 199 */ 200 typedef int32_t (*HITLS_AUTH_PrivPassVerify)(void *pkeyCtx, int32_t algId, const uint8_t *data, uint32_t dataLen, 201 const uint8_t *sign, uint32_t signLen); 202 203 /** 204 * @ingroup auth_privpass 205 * @brief Decodes a public key and gen a key ctx. The default algorithm callback implementation is supported only from 206 * a DER-encoded SubjectPublicKeyInfo (SPKI) object using the RSASSA-PSS OID. 207 * 208 * @param libCtx [IN] Library context 209 * @param attrName [IN] Specify expected attribute values 210 * @param pubKey [IN] A DER-encoded SubjectPublicKeyInfo (SPKI) object using the RSASSA-PSS OID 211 * @param pubKeyLen [IN] Length of public key data 212 * @param pkeyCtx [OUT] Pointer to store created key context 213 * 214 * @retval #0, if successful. 215 * other error codes, failed. 216 */ 217 typedef int32_t (*HITLS_AUTH_PrivPassDecodePubKey)(void *libCtx, const char *attrName, uint8_t *pubKey, 218 uint32_t pubKeyLen, void **pkeyCtx); 219 220 /** 221 * @ingroup auth_privpass 222 * @brief Decodes a private key and gen a key ctx. The default algorithm callback implementation is supported only from 223 * PEM-encoded PKCS #8 unencrypted RSA issuer private key. 224 * 225 * @param libCtx [IN] Library context 226 * @param attrName [IN] Specify expected attribute values 227 * @param param [IN] Parameters may need by private key decoding. 228 * @param prvKey [IN] A PEM-encoded PKCS #8 RSA unencrypted issuer private Key 229 * @param prvKeyLen [IN] Length of private key data 230 * @param pkeyCtx [OUT] Pointer to store created key context 231 * 232 * @retval #0, if successful. 233 * other error codes, failed. 234 */ 235 typedef int32_t (*HITLS_AUTH_PrivPassDecodePrvKey)(void *libCtx, const char *attrName, void *param, uint8_t *prvKey, 236 uint32_t prvKeyLen, void **pkeyCtx); 237 238 /** 239 * @ingroup auth_privpass 240 * @brief Verifies that a public/private key pair matches. 241 * 242 * @param pubKeyCtx [IN] Public key context 243 * @param prvKeyCtx [IN] Private key context 244 * 245 * @retval #0, if successful. 246 * other error codes, failed. 247 */ 248 typedef int32_t (*HITLS_AUTH_PrivPassCheckKeyPair)(void *pubKeyCtx, void *prvKeyCtx); 249 250 /** 251 * @ingroup auth_privpass 252 * @brief Generates random bytes. 253 * 254 * @param buffer [IN] Buffer to store random bytes 255 * @param bufferLen [IN] Length of buffer 256 * 257 * @retval #0, if successful. 258 * other error codes, failed. 259 */ 260 typedef int32_t (*HITLS_AUTH_PrivPassRandom)(uint8_t *buffer, uint32_t bufferLen); 261 262 /** 263 * @ingroup auth_privpass 264 * @brief Create a new PrivPass context object, all library callbacks by default are setted when created. 265 * @param tokenType [IN] Type of token to create, defined in HITLS_AUTH_PrivPassTokenType. 266 * 267 * @retval HITLS_AUTH_PrivPassCtx pointer. 268 * NULL, if the operation fails. 269 */ 270 HITLS_AUTH_PrivPassCtx *HITLS_AUTH_PrivPassNewCtx(int32_t protocolType); 271 272 /** 273 * @ingroup auth_privpass 274 * @brief Free a PrivPass context object. 275 * 276 * @param ctx [IN] Context to be freed 277 */ 278 void HITLS_AUTH_PrivPassFreeCtx(HITLS_AUTH_PrivPassCtx *ctx); 279 /** 280 * @ingroup auth_privpass 281 * @brief Create a new PrivPass token object. 282 * 283 * @param tokenType [IN] Type of token to create, defined in HITLS_AUTH_PrivPassTokenType. 284 * 285 * @retval HITLS_AUTH_PrivPassToken pointer. 286 * NULL, if the operation fails. 287 */ 288 HITLS_AUTH_PrivPassToken *HITLS_AUTH_PrivPassNewToken(int32_t tokenType); 289 290 /** 291 * @ingroup auth_privpass 292 * @brief Free a PrivPass token object. 293 * 294 * @param object [IN] Token to be freed 295 */ 296 void HITLS_AUTH_PrivPassFreeToken(HITLS_AUTH_PrivPassToken *object); 297 298 /** 299 * @ingroup auth_privpass 300 * @brief Set cryptographic callback functions for the context. When setting callbacks, 301 * the input callbacks will be checked. Non-NULL callbacks will override the default callbacks. 302 * 303 * @param ctx [IN/OUT] PrivPass context 304 * @param cbType [IN] Callback type, defined in PrivPassCryptCbType 305 * @param cryptCb [IN] Callback functions to be set 306 * 307 * @retval #HITLS_AUTH_SUCCESS, if successful. 308 * For other error codes, see auth_errno.h. 309 */ 310 int32_t HITLS_AUTH_PrivPassSetCryptCb(HITLS_AUTH_PrivPassCtx *ctx, int32_t cbType, void *cryptCb); 311 312 /** 313 * @ingroup auth_privpass 314 * @brief Serialize a PrivPass token object to binary format, If the object == NULL, outbufferlen returns 315 * the length required for serialization 316 * 317 * @param ctx [IN] PrivPass context 318 * @param object [IN] Token to serialize 319 * @param buffer [OUT] Buffer to store serialized data 320 * @param outBuffLen [IN/OUT] Length of the serialized data 321 * 322 * @retval #HITLS_AUTH_SUCCESS, if successful. 323 * For other error codes, see auth_errno.h. 324 */ 325 int32_t HITLS_AUTH_PrivPassSerialization(HITLS_AUTH_PrivPassCtx *ctx, const HITLS_AUTH_PrivPassToken *object, 326 uint8_t *buffer, uint32_t *outBuffLen); 327 328 /** 329 * @ingroup auth_privpass 330 * @brief Deserialize binary data into a PrivPass token object. The object needs to be freed by the caller 331 * using HITLS_AUTH_PrivPassFreeToken 332 * 333 * @param ctx [IN] PrivPass context 334 * @param tokenType [IN] Expected token type 335 * @param buffer [IN] Serialized data buffer 336 * @param buffLen [IN] Length of serialized data 337 * @param object [OUT] Pointer to store deserialized token 338 * 339 * @retval #HITLS_AUTH_SUCCESS, if successful. 340 * For other error codes, see auth_errno.h. 341 */ 342 int32_t HITLS_AUTH_PrivPassDeserialization(HITLS_AUTH_PrivPassCtx *ctx, int32_t tokenType, const uint8_t *buffer, 343 uint32_t buffLen, HITLS_AUTH_PrivPassToken **object); 344 345 /** 346 * @ingroup auth_privpass 347 * @brief Generate a token challenge. The challenge token is generated based on 348 * the input param. The construct of param refer to auth_params.h. 349 * @param ctx [IN] PrivPass context 350 * @param param [IN] Parameters for challenge generation, the param is limited to the library specification, 351 * the argument passed by the caller should ensure that the serialized length cannot exceed the upper limit. 352 * The tokenType, issuerName, redemption must be contained in the param, and originalInfo can be NULL. 353 * @param challenge [OUT] Generated challenge token 354 * 355 * @retval #HITLS_AUTH_SUCCESS, if successful. 356 * For other error codes, see auth_errno.h. 357 */ 358 int32_t HITLS_AUTH_PrivPassGenTokenChallenge(HITLS_AUTH_PrivPassCtx *ctx, const BSL_Param *param, 359 HITLS_AUTH_PrivPassToken **challenge); 360 361 /** 362 * @ingroup auth_privpass 363 * @brief Generate a token request. 364 * 365 * @param ctx [IN] PrivPass context 366 * @param tokenChallenge [IN] Challenge token 367 * @param tokenRequest [OUT] Generated request token 368 * 369 * @retval #HITLS_AUTH_SUCCESS, if successful. 370 * For other error codes, see auth_errno.h. 371 */ 372 int32_t HITLS_AUTH_PrivPassGenTokenReq(HITLS_AUTH_PrivPassCtx *ctx, const HITLS_AUTH_PrivPassToken *tokenChallenge, 373 HITLS_AUTH_PrivPassToken **tokenRequest); 374 375 /** 376 * @ingroup auth_privpass 377 * @brief Generate a token response. 378 * 379 * @param ctx [IN] PrivPass context 380 * @param tokenRequest [IN] Request token 381 * @param tokenResponse [OUT] Generated response token 382 * 383 * @retval #HITLS_AUTH_SUCCESS, if successful. 384 * For other error codes, see auth_errno.h. 385 */ 386 int32_t HITLS_AUTH_PrivPassGenTokenResponse(HITLS_AUTH_PrivPassCtx *ctx, const HITLS_AUTH_PrivPassToken *tokenRequest, 387 HITLS_AUTH_PrivPassToken **tokenResponse); 388 389 /** 390 * @ingroup auth_privpass 391 * @brief Generate final token. 392 * 393 * @param ctx [IN] PrivPass context 394 * @param tokenChallenge [IN] Challenge token 395 * @param tokenResponse [IN] Response token 396 * @param token [OUT] Generated final token 397 * 398 * @retval #HITLS_AUTH_SUCCESS, if successful. 399 * For other error codes, see auth_errno.h. 400 */ 401 int32_t HITLS_AUTH_PrivPassGenToken(HITLS_AUTH_PrivPassCtx *ctx, const HITLS_AUTH_PrivPassToken *tokenChallenge, 402 const HITLS_AUTH_PrivPassToken *tokenResponse, HITLS_AUTH_PrivPassToken **token); 403 404 /** 405 * @ingroup auth_privpass 406 * @brief Verify the validity of a token. 407 * 408 * @param ctx [IN] PrivPass context 409 * @param tokenChallenge [IN] Challenge token 410 * @param token [IN] Token to verify 411 * 412 * @retval #HITLS_AUTH_SUCCESS, if successful. 413 * For other error codes, see auth_errno.h. 414 */ 415 int32_t HITLS_AUTH_PrivPassVerifyToken(HITLS_AUTH_PrivPassCtx *ctx, const HITLS_AUTH_PrivPassToken *tokenChallenge, 416 const HITLS_AUTH_PrivPassToken *token); 417 418 /** 419 * @ingroup auth_privpass 420 * @brief Set the public key for the ctx. We support the repeated setting of the public key. If the ctx 421 * contains the private key when the public key is set, we will check whether the public key 422 * matches the private key. If its not match, an exception is returned. 423 * 424 * @param ctx [IN] PrivPass context 425 * @param pki [IN] A DER-encoded SubjectPublicKeyInfo (SPKI) object using the RSASSA-PSS OID 426 * @param pkiLen [IN] Length of public key data 427 * 428 * @retval #HITLS_AUTH_SUCCESS, if successful. 429 * For other error codes, see auth_errno.h. 430 */ 431 int32_t HITLS_AUTH_PrivPassSetPubkey(HITLS_AUTH_PrivPassCtx *ctx, uint8_t *pki, uint32_t pkiLen); 432 433 /** 434 * @ingroup auth_privpass 435 * @brief Set the private key for the ctx. We support the repeated setting of the private key. If the ctx 436 * contains the public key when the private key is set, we will check whether the private key 437 * matches the public key. If its not match, an exception is returned. 438 * @param ctx [IN] PrivPass context 439 * @param param [IN] Parameters may need by private key decoding. 440 * @param ski [IN] A PEM-encoded PKCS #8 RSA unencrypted issuer private key 441 * @param skiLen [IN] Length of private key data 442 * 443 * @retval #HITLS_AUTH_SUCCESS, if successful. 444 * For other error codes, see auth_errno.h. 445 */ 446 int32_t HITLS_AUTH_PrivPassSetPrvkey(HITLS_AUTH_PrivPassCtx *ctx, void *param, uint8_t *ski, uint32_t skiLen); 447 448 /** 449 * @ingroup auth_privpass 450 * @brief Control interface for getting/setting various parameters in token object. 451 * 452 * @param object [IN] token object 453 * @param cmd [IN] Command to execute, defined in HITLS_AUTH_PrivPassCmd 454 * @param param [IN/OUT] Command parameters 455 * @param paramLen [IN] Length of parameters 456 * 457 * @retval #HITLS_AUTH_SUCCESS, if successful. 458 * For other error codes, see auth_errno.h. 459 */ 460 int32_t HITLS_AUTH_PrivPassTokenCtrl(HITLS_AUTH_PrivPassToken *object, int32_t cmd, void *param, uint32_t paramLen); 461 462 /** 463 * @ingroup auth_privpass 464 * @brief Control interface for getting/setting various parameters in Priv-Pass Ctx. 465 * 466 * @param ctx [IN] PrivPass context 467 * @param cmd [IN] Command to execute, defined in HITLS_AUTH_PrivPassCmd 468 * @param param [IN/OUT] Command parameters 469 * @param paramLen [IN] Length of parameters 470 * 471 * @retval #HITLS_AUTH_SUCCESS, if successful. 472 * For other error codes, see auth_errno.h. 473 */ 474 int32_t HITLS_AUTH_PrivPassCtxCtrl(HITLS_AUTH_PrivPassCtx *ctx, int32_t cmd, void *param, uint32_t paramLen); 475 476 #ifdef __cplusplus 477 } 478 #endif 479 480 #endif // AUTH_PRIVPASS_TOKEN_H 481