1 #ifndef NSSLCLIENT_H 2 #define NSSLCLIENT_H 3 4 /*---------------------------------------------------------------------------* 5 Project: Nintendo SSL Client 6 File: nsslclient.h 7 Description: This file provides the SSL client side APIs for establishing 8 a secure SSL connection with an SSL server. 9 10 Copyright (C) 2012 Nintendo. All rights reserved. 11 12 These coded instructions, statements, and computer programs contain 13 proprietary information of Nintendo of America Inc. and/or Nintendo 14 Company Ltd., and are protected by Federal copyright law. They may 15 not be disclosed to third parties or copied or duplicated in any form, 16 in whole or in part, without the prior written consent of Nintendo. 17 18 *---------------------------------------------------------------------------*/ 19 #ifdef __ghs__ 20 #include <types.h> 21 #endif 22 23 #include <cafe/nssl/certstore.h> 24 #include <cafe/nssl/nssl_init.h> 25 26 #define NSSL_IO_BUFFER_ALIGN 64 27 28 29 #ifdef __cplusplus 30 extern "C" { 31 #endif 32 33 /*---------------------------------------------------------------------------* 34 * 35 * Globals/Externs 36 * -- Variables/Functions -- 37 * 38 *---------------------------------------------------------------------------*/ 39 40 /*---------------------------------------------------------------------------* 41 * 42 * Constants defined for this file 43 * -- #Defines's -- 44 * 45 *---------------------------------------------------------------------------*/ 46 #define NSSL_EMPTY_STR "" 47 #define NSSL_EMPTY_STR_LEN 0 48 49 #define NSSL_RM_FD_INVALID (-1) 50 51 /* 52 * Bit masks to be used for peer validation options for SSL handshake 53 * ( 'peerVerifyOptions' parameter for 'NSSLCreateConnection' ) 54 */ 55 56 /* NSSL_VERIFY_NONE: Do not verify peer certificate */ 57 #define NSSL_VERIFY_NONE 0x0 58 59 /* NSSL_VERIFY_PEER_CA: Validate the peer certificate using 60 * the server certificates specified using NSSLAddServerPKIExternal 61 * NOTE: Peer certificate's ValidFrom and ValidTo dates are 62 * not checked unless NSSL_VERIFY_DATE_VALIDITY bit is also set. 63 */ 64 #define NSSL_VERIFY_PEER_CA 0x1 65 66 /* 67 * NSSL_VERIFY_HOSTNAME: In addition to peer certificate validation 68 * (see NSSL_VERIFY_PEER_CA), also check if the hostname matches 69 * the Common Name field or a Subject Alternate Name field in the 70 * peer certificate. 71 * 72 * NOTE: If NSSL_VERIFY_HOSTNAME is set, NSSL_VERIFY_PEER_CA is 73 * assumed to be set. 74 */ 75 #define NSSL_VERIFY_HOSTNAME 0x2 76 77 /* 78 * NSSL_VERIFY_HOSTNAME: In addition to peer certificate validation, 79 * validate certificates ValidFrom and ValidTo fields. 80 * 81 * NOTE: If NSSL_VERIFY_DATE_VALIDITY is set, NSSL_VERIFY_PEER_CA is 82 * assumed to be set. 83 */ 84 #define NSSL_VERIFY_DATE_VALIDITY 0x4 85 86 #define NSSL_VERIFY_ALL \ 87 (NSSL_VERIFY_PEER_CA | NSSL_VERIFY_HOSTNAME | NSSL_VERIFY_DATE_VALIDITY) 88 89 #define NSSL_VERIFY_ALL_EXCEPT_DATE \ 90 (NSSL_VERIFY_PEER_CA | NSSL_VERIFY_HOSTNAME ) 91 92 /* Bit masks for NSSL context flags */ 93 94 /*Enables CRL checking only for the certificate chain leaf certificate */ 95 #define NSSL_CTX_FLAG_CRL_CHECK_LEAF 0x1 96 97 /*Enables CRL checking for the rest of the certificate chain */ 98 /*(Valid only if NSSL_CTX_FLAG_CRL_CHECK_LEAF is also set) */ 99 #define NSSL_CTX_FLAG_CRL_CHECK_CHAIN 0x2 100 101 /* peer certificate validation status codes */ 102 #define NSSL_CERT_VALID 0 103 #define NSSL_CERT_V_ERR_UNKNOWN 1000 104 #define NSSL_CERT_V_ERR_HOSTNAME_MISMATCH 1001 105 106 #define NSSL_CERT_V_ERR_UNABLE_TO_GET_ISSUER_CERT 2 107 #define NSSL_CERT_V_ERR_UNABLE_TO_GET_CRL 3 108 #define NSSL_CERT_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE 4 109 #define NSSL_CERT_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE 5 110 #define NSSL_CERT_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY 6 111 #define NSSL_CERT_V_ERR_CERT_SIGNATURE_FAILURE 7 112 #define NSSL_CERT_V_ERR_CRL_SIGNATURE_FAILURE 8 113 #define NSSL_CERT_V_ERR_CERT_NOT_YET_VALID 9 114 #define NSSL_CERT_V_ERR_CERT_HAS_EXPIRED 10 115 #define NSSL_CERT_V_ERR_CRL_NOT_YET_VALID 11 116 #define NSSL_CERT_V_ERR_CRL_HAS_EXPIRED 12 117 #define NSSL_CERT_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD 13 118 #define NSSL_CERT_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD 14 119 #define NSSL_CERT_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD 15 120 #define NSSL_CERT_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD 16 121 #define NSSL_CERT_V_ERR_OUT_OF_MEM 17 122 #define NSSL_CERT_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT 18 123 #define NSSL_CERT_V_ERR_SELF_SIGNED_CERT_IN_CHAIN 19 124 #define NSSL_CERT_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY 20 125 #define NSSL_CERT_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE 21 126 #define NSSL_CERT_V_ERR_CERT_CHAIN_TOO_LONG 22 127 #define NSSL_CERT_V_ERR_CERT_REVOKED 23 128 #define NSSL_CERT_V_ERR_INVALID_CA 24 129 #define NSSL_CERT_V_ERR_PATH_LENGTH_EXCEEDED 25 130 #define NSSL_CERT_V_ERR_INVALID_PURPOSE 26 131 #define NSSL_CERT_V_ERR_CERT_UNTRUSTED 27 132 #define NSSL_CERT_V_ERR_CERT_REJECTED 28 133 #define NSSL_CERT_V_ERR_SUBJECT_ISSUER_MISMATCH 29 134 #define NSSL_CERT_V_ERR_AKID_SKID_MISMATCH 30 135 #define NSSL_CERT_V_ERR_AKID_ISSUER_SERIAL_MISMATCH 31 136 #define NSSL_CERT_V_ERR_KEYUSAGE_NO_CERTSIGN 32 137 #define NSSL_CERT_V_ERR_UNABLE_TO_GET_CRL_ISSUER 33 138 #define NSSL_CERT_V_ERR_UNHANDLED_CRITICAL_EXTENSION 34 139 #define NSSL_CERT_V_ERR_KEYUSAGE_NO_CRL_SIGN 35 140 #define NSSL_CERT_V_ERR_UNHANDLED_CRITICAL_CRL_EXTENSION 36 141 #define NSSL_CERT_V_ERR_INVALID_NON_CA 37 142 #define NSSL_CERT_V_ERR_PROXY_PATH_LENGTH_EXCEEDED 38 143 #define NSSL_CERT_V_ERR_KEYUSAGE_NO_DIGITAL_SIGNATURE 39 144 #define NSSL_CERT_V_ERR_PROXY_CERTIFICATES_NOT_ALLOWED 40 145 #define NSSL_CERT_V_ERR_INVALID_EXTENSION 41 146 #define NSSL_CERT_V_ERR_INVALID_POLICY_EXTENSION 42 147 #define NSSL_CERT_V_ERR_NO_EXPLICIT_POLICY 43 148 #define NSSL_CERT_V_ERR_DIFFERENT_CRL_SCOPE 44 149 #define NSSL_CERT_V_ERR_UNSUPPORTED_EXTENSION_FEATURE 45 150 #define NSSL_CERT_V_ERR_UNNESTED_RESOURCE 46 151 #define NSSL_CERT_V_ERR_PERMITTED_VIOLATION 47 152 #define NSSL_CERT_V_ERR_EXCLUDED_VIOLATION 48 153 #define NSSL_CERT_V_ERR_SUBTREE_MINMAX 49 154 #define NSSL_CERT_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE 51 155 #define NSSL_CERT_V_ERR_APPLICATION_VERIFICATION 50 156 #define NSSL_CERT_V_ERR_UNSUPPORTED_CONSTRAINT_SYNTAX 52 157 #define NSSL_CERT_V_ERR_UNSUPPORTED_NAME_SYNTAX 53 158 #define NSSL_CERT_V_ERR_CRL_PATH_VALIDATION_ERROR 54 159 160 161 162 /* 163 * Client certificates (to be used when calling NSSLSetClientPKI) 164 * 165 */ 166 #define NSSL_CLIENT_CERT_NONE (0) 167 /* Nintendo client cert IDs */ 168 #define NSSL_CLIENT_CERT_DEFAULT (1) 169 170 /* 171 * Server i.e. trusted CA certificates (to be used when calling NSSLAddServerPKI) 172 * 173 */ 174 /* 175 * Group: CERTSTORE_ENTITY_GROUP_NINTENDO_CA_CERTS 176 * Nintendo CA certificate IDs 177 */ 178 179 #define NSSL_SERVER_CERT_NONE (0) 180 #define NSSL_SERVER_CERT_NINTENDO_CA (100) 181 #define NSSL_SERVER_CERT_NINTENDO_CA_G2 (101) 182 #define NSSL_SERVER_CERT_NINTENDO_CA_G3 (102) 183 #define NSSL_SERVER_CERT_NINTENDO_CLASS2_CA (103) 184 #define NSSL_SERVER_CERT_NINTENDO_CLASS2_CA_G2 (104) 185 #define NSSL_SERVER_CERT_NINTENDO_CLASS2_CA_G3 (105) 186 187 /* 188 * Group : CERTSTORE_ENTITY_GROUP_COMMERCIAL_CA_CERTS 189 * Commercial CA certificate IDs 190 */ 191 #define NSSL_SERVER_CERT_BALTIMORE_CYBERTRUST_ROOT_CA (1001) 192 #define NSSL_SERVER_CERT_CYBERTRUST_GLOBAL_ROOT_CA (1002) 193 #define NSSL_SERVER_CERT_VERIZON_GLOBAL_ROOT_CA (1003) 194 #define NSSL_SERVER_CERT_GLOBALSIGN_ROOT_CA (1004) 195 #define NSSL_SERVER_CERT_GLOBALSIGN_ROOT_CA_R2 (1005) 196 #define NSSL_SERVER_CERT_GLOBALSIGN_ROOT_CA_R3 (1006) 197 #define NSSL_SERVER_CERT_VERISIGN_CLASS3_PUBLIC_PRIMARY_CA_G3 (1007) 198 #define NSSL_SERVER_CERT_VERISIGN_UNIVERSAL_ROOT_CA (1008) 199 #define NSSL_SERVER_CERT_VERISIGN_CLASS3_PUBLIC_PRIMARY_CA_G5 (1009) 200 #define NSSL_SERVER_CERT_THAWTE_PRIMARY_ROOT_CA_G3 (1010) 201 #define NSSL_SERVER_CERT_THAWTE_PRIMARY_ROOT_CA (1011) 202 #define NSSL_SERVER_CERT_GEOTRUST_GLOBAL_CA (1012) 203 #define NSSL_SERVER_CERT_GEOTRUST_GLOBAL_CA2 (1013) 204 #define NSSL_SERVER_CERT_GEOTRUST_PRIMARY_CA (1014) 205 #define NSSL_SERVER_CERT_GEOTRUST_PRIMARY_CA_G3 (1015) 206 #define NSSL_SERVER_CERT_ADDTRUST_EXT_CA_ROOT (1016) 207 #define NSSL_SERVER_CERT_COMODO_CA (1017) 208 #define NSSL_SERVER_CERT_UTN_DATACORP_SGC_CA (1018) 209 #define NSSL_SERVER_CERT_UTN_USERFIRST_HARDWARE_CA (1019) 210 #define NSSL_SERVER_CERT_DIGICERT_HIGH_ASSURANCE_EV_ROOT_CA (1020) 211 #define NSSL_SERVER_CERT_DIGICERT_ASSURED_ID_ROOT_CA (1021) 212 #define NSSL_SERVER_CERT_DIGICERT_GLOBAL_ROOT_CA (1022) 213 #define NSSL_SERVER_CERT_GTE_CYBERTRUST_GLOBAL_ROOT (1023) 214 #define NSSL_SERVER_CERT_VERISIGN_CLASS3_PUBLIC_PRIMARY_CA (1024) 215 #define NSSL_SERVER_CERT_THAWTE_PREMIUM_SERVER_CA (1025) 216 #define NSSL_SERVER_CERT_EQUIFAX_SECURE_CA (1026) 217 #define NSSL_SERVER_CERT_ENTRUST_SECURE_SERVER_CA (1027) 218 #define NSSL_SERVER_CERT_VERISIGN_CLASS3_PUBLIC_PRIMARY_CA_G2 (1028) 219 #define NSSL_SERVER_CERT_ENTRUST_CA_2048 (1029) 220 #define NSSL_SERVER_CERT_ENTRUST_ROOT_CA (1030) 221 #define NSSL_SERVER_CERT_ENTRUST_ROOT_CA_G2 (1031) 222 #define NSSL_SERVER_CERT_DIGICERT_ASSURED_ID_ROOT_CA_G2 (1032) 223 #define NSSL_SERVER_CERT_DIGICERT_GLOBAL_ROOT_CA_G2 (1033) 224 225 /*---------------------------------------------------------------------------* 226 * 227 * Data types defined for this file 228 * -- Struct's, Typedef's, Enum's -- 229 * 230 *---------------------------------------------------------------------------*/ 231 typedef int NSSLClientCertID; 232 typedef int NSSLServerCertID; 233 typedef CertstoreEntityGroupMask NSSLServerCertGroupMask; 234 235 typedef enum 236 { 237 NSSL_HANDSHAKE_OK, 238 NSSL_HANDSHAKE_INCOMPLETE, 239 NSSL_HANDSHAKE_ERROR_UNKNOWN, 240 NSSL_HANDSHAKE_ERROR_INVALID_CLIENT_CERT, 241 NSSL_HANDSHAKE_ERROR_CLIENT_CERT_NEEDED, 242 NSSL_HANDSHAKE_ERROR_CIPHER_MISMATCH, 243 NSSL_HANDSHAKE_ERROR_UNSUPPORTED_PROTOCOL, 244 NSSL_HANDSHAKE_ERROR_PEER_CERT_HOSTNAME_MISMATCH, 245 NSSL_HANDSHAKE_ERROR_SERVER_CERT_VERIFY_FAILED 246 } NSSLHandshakeError; 247 248 typedef enum 249 { 250 NSSL_SSLVERSION_INVALID = -1, 251 252 /* Automatically select the highest version supported out of TLS1.0/SSLv3 */ 253 NSSL_SSLVERSION_AUTO, 254 255 /* TLS 1.0 */ 256 NSSL_SSLVERSION_TLSv1, 257 258 /* SSLv3 */ 259 NSSL_SSLVERSION_SSLv3 260 } NSSLSSLVersion; 261 262 typedef enum 263 { 264 NSSL_CERT_TYPE_DER 265 } NSSLCertType; 266 267 typedef enum 268 { 269 NSSL_PRIV_KEY_TYPE_RSA 270 } NSSLPrivKeyType; 271 272 typedef enum 273 { 274 NSSL_CRL_TYPE_DER 275 } NSSLCrlType; 276 277 typedef int NSSLContextHandle; 278 typedef int NSSLConnectionHandle; 279 typedef int NSSLSessionHandle; 280 typedef int NSSLCertValidationStatus; 281 282 /*---------------------------------------------------------------------------* 283 * 284 * File scope functions/symbols defined for this file 285 * -- Function Prototypes, File Scope Data -- 286 * 287 *---------------------------------------------------------------------------*/ 288 289 /*---------------------------------------------------------------------------* 290 * 291 * PRIVATE METHODS 292 * 293 *---------------------------------------------------------------------------*/ 294 295 /*---------------------------------------------------------------------------* 296 * 297 * PUBLIC METHODS 298 * 299 *---------------------------------------------------------------------------*/ 300 301 302 /*--------------------------------------------------------------------------- 303 Name: NSSLCreateContext() 304 305 Description: Creates an SSL context to hold certificates and keys to be 306 used for SSL communication. The certificates and keys 307 associated with a SSL context by the application will be used 308 for all SSL connections created with the context. An 309 application can create maximum upto 32 contexts. 310 311 Arguments: sslVersion: Version of SSL/TLS to be used. 312 313 Returns: NSSL context handle (0 or +ve) on success. Appropriate error 314 code (-ve) on failure. 315 *---------------------------------------------------------------------------*/ 316 NSSLContextHandle NSSLCreateContext(NSSLSSLVersion sslVersion); 317 318 319 /*--------------------------------------------------------------------------- 320 Name: NSSLDestroyContext() 321 322 Description: Destroys a SSL Context. All the SSL connections associated 323 with the context will be also be destroyed. 324 325 Arguments: context: A handle to the context to be destroyed. 326 327 Returns: NSSL_RVAL_OK on success. Appropriate error code on failure. 328 *---------------------------------------------------------------------------*/ 329 NSSL_RVAL NSSLDestroyContext(NSSLContextHandle context); 330 331 /*--------------------------------------------------------------------------- 332 Name: NSSLSetClientPKI() 333 334 Description: Set the client certificate and private key (from the build-in 335 certificate store) to be used in case the server performs 336 client certificate verification. The certificate 337 and private key will be used for all the connections created 338 under the context. 339 340 NOTE: Access to the individual built-in 341 certificates is restricted based on capabilities of the 342 application. NSSL_RVAL_CERT_NO_ACCESS is returned if 343 application tries to use a certificate for which it 344 does not have access permission. 345 346 Arguments: context: Context 347 348 clientCertID: Identifier of the built-in client certificate 349 to be used. 350 351 Returns: NSSL_RVAL_OK on success. Appropriate error code on failure. 352 *---------------------------------------------------------------------------*/ 353 NSSL_RVAL NSSLSetClientPKI(NSSLContextHandle context, 354 NSSLClientCertID clientCertID); 355 356 /*--------------------------------------------------------------------------- 357 Name: NSSLAddServerPKI() 358 359 Description: Add a trusted CA certificate (from the build-in certificate 360 store) to be used to verify the peer certificate. The 361 certificate is used for all the connections created under 362 the context. 363 NSSLAddServerPKI can be called multiple times 364 for a context to add multiple trusted CA certificates. 365 366 NOTE: Access to the individual built-in 367 certificates is restricted based on capabilities of the 368 application. NSSL_RVAL_CERT_NO_ACCESS is returned if 369 application tries to use a certificate for which it 370 does not have access permission. 371 372 Arguments: context: Context 373 374 serverCertID: Identifier for the CA certificate 375 to be added. 376 377 Returns: NSSL_RVAL_OK on success. Appropriate error code on failure. 378 *---------------------------------------------------------------------------*/ 379 NSSL_RVAL NSSLAddServerPKI(NSSLContextHandle context, 380 NSSLServerCertID serverCertID); 381 382 /*--------------------------------------------------------------------------- 383 Name: NSSLAddServerPKIGroups() 384 385 386 Description: Add group(s) of server verification certificate (from the 387 build-in certificate store) for the context. The certificates 388 will be used for all the connections created 389 under the context. 390 391 NOTE: NSSL_RVAL_OK is returned even if error(s) are encountered 392 in adding one or more of the certificates. addedCount and 393 errorCount indicate the number of certificates successfully 394 added and the the number of certificates which could not be 395 added due to error. 396 397 Arguments: context: The context for which the certificates are to be added. 398 399 certGroupMask: A bit mask with bits for the certificate group 400 to be added to the context. 401 402 addedCount[out]: A pointer to hold the count of certificates 403 added to the context. 404 405 errorCount[out]: A pointer to hold the count of certificates 406 which could not be added to the context 407 (due to error). 408 409 Returns: NSSL_RVAL_OK on success. Appropriate error code on failure. 410 *---------------------------------------------------------------------------*/ 411 NSSL_RVAL NSSLAddServerPKIGroups(NSSLContextHandle context, 412 NSSLServerCertGroupMask certGroupMask, 413 int *addedCount, 414 int *errorCount); 415 416 /*--------------------------------------------------------------------------- 417 Name: NSSLSetClientPKIExternal() 418 419 Description: Set the client certificate and private key to be used in 420 case the server performs client certificate verification. 421 The certificate and private key will be used for all the 422 connections created under the context. 423 424 Arguments: context: The context for which the client certificate is to 425 be set. 426 427 pClientCert: Certificate buffer (The buffer size and address 428 should be aligned to NSSL_IO_BUFFER_ALIGN) 429 430 clientCertLen: Certificate buffer length (max size 4KB) 431 432 clientCertType: Type of the certificate (currently only 433 NSSL_CERT_TYPE_DER is supported, pClientCert should 434 contain client certificate in DER format) 435 436 pClientPrivKey: Private key buffer (The buffer size and address 437 should be aligned to NSSL_IO_BUFFER_ALIGN], 438 pClientPrivKey should contain RSA private key 439 in PKCS#1 format) 440 441 clientPrivKeyLen: Private key buffer length (max size 4KB) 442 443 clientPrivKeyType: Type of the private key 444 (currently only NSSL_PRIV_KEY_TYPE_RSA is supported) 445 446 447 Returns: NSSL_RVAL_OK on success. Appropriate error code on failure. 448 *---------------------------------------------------------------------------*/ 449 NSSL_RVAL NSSLSetClientPKIExternal(NSSLContextHandle context, 450 const u8* pClientCert, 451 int clientCertLen, 452 NSSLCertType clientCertType, 453 const u8* pClientPrivKey, 454 int clientPrivKeyLen, 455 NSSLPrivKeyType clientPrivKeyType); 456 457 /*--------------------------------------------------------------------------- 458 Name: NSSLAddServerPKIExternal() 459 460 Description: Add a trusted CA certificate to be used to verify the 461 peer certificate. The certificate is used for all the 462 connections created under the context. 463 NSSLAddServerPKIExternal can be called multiple times 464 for a context to add multiple trusted CA certificates. 465 466 Arguments: context: The context for which the certificate is to be added. 467 pServerCert: Certificate buffer (The buffer size and address 468 should be aligned to NSSL_IO_BUFFER_ALIGN]). 469 serverCertLen: Certificate buffer length 470 serverCertType: Type of the certificate (currently only 471 NSSL_CERT_TYPE_DER is supported, 472 pServerCert should contain a certificate 473 in DER format). 474 475 Returns: NSSL_RVAL_OK on success. Appropriate error code on failure. 476 *---------------------------------------------------------------------------*/ 477 NSSL_RVAL NSSLAddServerPKIExternal(NSSLContextHandle context, 478 const u8* pServerCert, 479 int serverCertLen, 480 NSSLCertType serverCertType); 481 482 /*--------------------------------------------------------------------------- 483 Name: NSSLAddCRLExternal() 484 485 Description: Add a Certificate Revocation List (CRL) to be used during the 486 verification of the peer certificate. The CRL is used for all 487 the connections created under the context. 488 NSSLAddCRLExternal can be called multiple times 489 for a context to add multiple CRLs. 490 491 Arguments: context: The context for which the CRL is to be added. 492 pCRL: CRL buffer (The buffer size and address 493 should be aligned to NSSL_IO_BUFFER_ALIGN]). 494 crlLen: CRL buffer length 495 crlType: Type of the CRL (currently only 496 NSSL_CRL_TYPE_DER is supported, 497 pCRL should contain a CRL 498 in DER format). 499 500 Returns: NSSL_RVAL_OK on success. Appropriate error code on failure. 501 *---------------------------------------------------------------------------*/ 502 NSSL_RVAL NSSLAddCRLExternal(NSSLContextHandle context, 503 const u8* pCRL, 504 int crlLen, 505 NSSLCrlType crlType); 506 507 /*--------------------------------------------------------------------------- 508 Name: NSSLContextSetFlags() 509 510 Description: Sets flags for NSSL context that control behavior during 511 verification of server certificate 512 513 Arguments: context: The NSSL Context for which the flags need to be set. 514 flags: bitmask of flags to be set 515 516 Returns: NSSL_RVAL_OK on success. Appropriate error code on failure. 517 *---------------------------------------------------------------------------*/ 518 519 NSSL_RVAL NSSLContextSetFlags(NSSLContextHandle context, 520 unsigned long flags); 521 522 /*--------------------------------------------------------------------------- 523 Name: NSSLContextClearFlags() 524 525 Description: Clears specified flags for NSSL context that control behavior 526 during verification of server certificate 527 528 Arguments: context: NSSL Context for which the flags need to be cleared. 529 flags: bitmask of flags to be cleared 530 531 Returns: NSSL_RVAL_OK on success. Appropriate error code on failure. 532 *---------------------------------------------------------------------------*/ 533 534 NSSL_RVAL NSSLContextClearFlags(NSSLContextHandle context, 535 unsigned long flags); 536 537 /*--------------------------------------------------------------------------- 538 Name: NSSLContextGetFlags() 539 540 Description: Gets current flags for NSSL context that control behavior during 541 verification of server certificate 542 543 Arguments: context: NSSL Context for which the flags need to be obtained. 544 pFlags: [output] pointer to an unsigned long where bitmask of 545 flags will be stored 546 547 Returns: NSSL_RVAL_OK on success. Appropriate error code on failure. 548 *---------------------------------------------------------------------------*/ 549 NSSL_RVAL NSSLContextGetFlags(NSSLContextHandle context, 550 unsigned long *pFlags); 551 552 /*--------------------------------------------------------------------------- 553 Name: NSSLCreateConnection() 554 555 Description: Creates a new SSL connection to perform secure data 556 transfer over TCP/IP connection created by an application. An 557 application can create maximum upto 32 connections. 558 559 Arguments: context: A context to be used for the connection. Client 560 and server certificates associated with the context will be 561 used for the connection. 562 pHostname: hostname of the server (used for hostname 563 verification) 564 hostnameLen: Length of hostname buffer 565 peerVerifyOptions: Bit mask for verification options for 566 peer certificate 567 sockfd: Socket fd of the underlying TCP/IP connection. 568 Application should create a socket using SOSocket, 569 connect it to the server using SOConnect before 570 calling NSSLCreateConnection. 571 blocking: Indicator if the socket is going to be used in a 572 blocking mode or non-blocking mode. 573 574 Returns: NSSL connection handle (0 or +ve) on success, 575 Appropriate error code (-ve) on failure. 576 *---------------------------------------------------------------------------*/ 577 NSSLConnectionHandle NSSLCreateConnection(NSSLContextHandle context, 578 const char* pHostname, 579 int hostnameLen, 580 int peerVerifyOptions, 581 int sockfd, 582 BOOL blocking); 583 584 /*--------------------------------------------------------------------------- 585 Name: NSSLDestroyConnection() 586 587 Description: Shuts down the underlying SSL connection and destroys the 588 connection. The application should close the underlying TCP/IP 589 socket after calling NSSLDestroyConnection. 590 591 Arguments: connection: A handle to the connection to be destroyed. 592 593 Returns: NSSL_RVAL_OK on success. Appropriate error code on failure. 594 *---------------------------------------------------------------------------*/ 595 NSSL_RVAL NSSLDestroyConnection(NSSLConnectionHandle connection); 596 597 598 /*--------------------------------------------------------------------------- 599 Name: NSSLDoHandshake() 600 601 Description: Perform SSL handshake with the peer. Handshake error code is 602 written into pHsError and peer certificate validation status 603 is written into pPeerVertValidationStatus when completed. 604 605 Arguments: connection: A SSL connection on which a handshake is 606 to be performed 607 pHsError: [Output] A pointer to hold handshake error code. 608 pPeerVertValidationStatus: [Output] A pointer to hold bitmask 609 indicating peer certificate validation status. 610 611 Returns: NSSL_RVAL_OK on success else the following error codes 612 NSSL_RVAL_WANT_READ/NSSL_RVAL_WANT_WRITE: (Only applicable for 613 non blocking connections) The operation did 614 not complete; NSSLDoHandshake should be 615 called again later. If, by then, the underlying socket has 616 data available for reading (if the result code is 617 NSSL_RVAL_WANT_READ) or allows writing data 618 (NSSL_RVAL_WANT_WRITE), then some TLS/SSL protocol 619 progress will take place, i.e. at least part of an 620 TLS/SSL record will be read or written. Note that the 621 retry may again lead to a NSSL_RVAL_WANT_READ or 622 NSSL_RVAL_WANT_WRITE condition. There is no fixed 623 upper limit for the number of iterations that 624 may be necessary until progress becomes visible 625 at application protocol level. 626 NSSL_RVAL_HANDSHAKE_ERROR: SSL handshake failed. 627 NSSL_RVAL_IO_ERROR: Some IO error occurred on the underlying 628 socket. 629 NSSL_RVAL_NSSLLIB_ERROR: A failure in the NSSL library occurred. 630 *---------------------------------------------------------------------------*/ 631 NSSL_RVAL NSSLDoHandshake(NSSLConnectionHandle connection, 632 NSSLHandshakeError* pHsError, 633 NSSLCertValidationStatus *pPeerCertValidationStatus); 634 635 636 /*--------------------------------------------------------------------------- 637 Name: NSSLRead() 638 639 Description: Read from the SSL connection, count of bytes read is written 640 into pBytesRead when completed. 641 642 Arguments: connection: A SSL connection from which to read. 643 pBuf: [Output] Buffer to read into, (The buffer size and address 644 should be aligned to NSSL_IO_BUFFER_ALIGN]). 645 len: number of bytes to read 646 pBytesRead: [Output] A pointer to hold the count of 647 bytes read 648 649 Returns: NSSL_RVAL_OK on success else the following error codes 650 NSSL_RVAL_ZERO_RETURN: The SSL connection has been closed. 651 NSSL_RVAL_WANT_READ/NSSL_RVAL_WANT_WRITE: (Only applicable for 652 non blocking connections) The operation did 653 not complete; the same NSSL I/O function should be 654 called again later. If, by then, the underlying socket has 655 data available for reading (if the result code is 656 NSSL_RVAL_WANT_READ) or allows writing data 657 (NSSL_RVAL_WANT_WRITE), then some TLS/SSL protocol 658 progress will take place, i.e. at least part of an 659 TLS/SSL record will be read or written. Note that the 660 retry may again lead to a NSSL_RVAL_WANT_READ or 661 NSSL_RVAL_WANT_WRITE condition. There is no fixed 662 upper limit for the number of iterations that 663 may be necessary until progress becomes visible 664 at application protocol level. 665 NSSL_RVAL_IO_ERROR: Some IO error occurred on the underlying socket. 666 NSSL_RVAL_NSSLLIB_ERROR: A failure in the NSSL library occurred. 667 *---------------------------------------------------------------------------*/ 668 NSSL_RVAL NSSLRead(NSSLConnectionHandle connection, 669 void* pBuf, 670 int len, 671 int* pBytesRead); 672 673 674 /*--------------------------------------------------------------------------- 675 Name: NSSLWrite() 676 677 Description: Write to the SSL connection, count of bytes written is written 678 into pBytesWritten when completed. 679 680 Arguments: connection: A SSL connection to write to 681 pBuf: Buffer to write into, (The buffer size and address 682 should be aligned to NSSL_IO_BUFFER_ALIGN]). 683 len: number of bytes to write 684 pBytesWritten: [Output] A pointer to hold the count of 685 bytes written 686 687 Returns: NSSL_RVAL_OK on success else the following error codes 688 NSSL_RVAL_ZERO_RETURN: The SSL connection has been closed. 689 NSSL_RVAL_WANT_READ/NSSL_RVAL_WANT_WRITE: (Only applicable 690 to non-blocking connections) The operation did 691 not complete; the same NSSL I/O function should be 692 called again later. If, by then, the underlying socket has 693 data available for reading (if the result code is 694 NSSL_RVAL_WANT_READ) or allows writing data 695 (NSSL_RVAL_WANT_WRITE), then some TLS/SSL protocol 696 progress will take place, i.e. at least part of an 697 TLS/SSL record will be read or written. Note that the 698 retry may again lead to a NSSL_RVAL_WANT_READ or 699 NSSL_RVAL_WANT_WRITE condition. There is no fixed 700 upper limit for the number of iterations that 701 may be necessary until progress becomes visible 702 at application protocol level. 703 NSSL_RVAL_IO_ERROR: Some IO error occurred on the underlying socket. 704 NSSL_RVAL_NSSLLIB_ERROR: A failure in the NSSL library occurred. 705 *---------------------------------------------------------------------------*/ 706 NSSL_RVAL NSSLWrite(NSSLConnectionHandle connection, 707 const void* pBuf, 708 int len, 709 int* pBytesWritten); 710 711 712 /*--------------------------------------------------------------------------- 713 Name: NSSLGetSession() 714 715 Description: Returns handle to SSL session which can be used for 716 session resumption across SSL connection (under the 717 same Context). The session handle is reference counted. 718 NSSLGetSession() increments the count, use NSSLFreeSession 719 to decrement the same. 720 721 Arguments: connection: A handle to a SSL connection to be queried. 722 723 Returns: NSSL session handle (0 or +ve) on success. Appropriate error 724 code (-ve) on failure. 725 *---------------------------------------------------------------------------*/ 726 NSSLSessionHandle NSSLGetSession(NSSLConnectionHandle connection); 727 728 /*--------------------------------------------------------------------------- 729 Name: NSSLSetSession() 730 731 Description: Sets SSL session handle on a connection to reuse the 732 session. 733 734 Arguments: connection: A handle to a SSL connection. 735 session: A handle to a session to be reused. 736 737 Returns: NSSL_RVAL_OK on success. Appropriate error code on failure. 738 *---------------------------------------------------------------------------*/ 739 NSSL_RVAL NSSLSetSession(NSSLConnectionHandle connection, 740 NSSLSessionHandle session); 741 742 /*--------------------------------------------------------------------------- 743 Name: NSSLFreeSession() 744 745 Description: Decrements reference count of SSL session handle 746 obtained using NSSLGetSession. The session handle is 747 released when the reference count goes to zero. 748 749 Arguments: session: Handle to a session to be freed. 750 751 Returns: NSSL_RVAL_OK on success. Appropriate error code on failure. 752 *---------------------------------------------------------------------------*/ 753 NSSL_RVAL NSSLFreeSession(NSSLSessionHandle session); 754 755 /*--------------------------------------------------------------------------- 756 Name: NSSLRemoveSession() 757 758 Description: Removes a SSL session from cache. 759 760 Arguments: session: Handle to a session to be removed. 761 762 Returns: NSSL_RVAL_OK on success. Appropriate error code on failure. 763 *---------------------------------------------------------------------------*/ 764 NSSL_RVAL NSSLRemoveSession(NSSLSessionHandle session); 765 766 /*--------------------------------------------------------------------------- 767 Name: NSSLGetPending() 768 769 Description: Returns the count of bytes available on the connection 770 inside NSSL to read immediately. This is uses by libcurl. 771 772 Arguments: connection: A handle to a SSL connection to be queried. 773 pPendingBytes: [Output] A pointer to hold count of bytes 774 available to be read 775 776 Returns: NSSL_RVAL_OK on success. Appropriate error code on failure. 777 *---------------------------------------------------------------------------*/ 778 NSSL_RVAL NSSLGetPending(NSSLConnectionHandle connection, 779 int* pPendingBytes); 780 781 /*--------------------------------------------------------------------------- 782 Name: NSSLGetPeerCertSize() 783 784 Description: Get size of peer certificate in DER form 785 786 Arguments: connection: A handle to a SSL connection to be queried. 787 788 Returns: 0 or positive value indicates the length of the peer 789 certificate in DER form. Negative value indicates 790 appropriate error code. 791 *---------------------------------------------------------------------------*/ 792 int NSSLGetPeerCertSize(NSSLConnectionHandle connection); 793 794 /*--------------------------------------------------------------------------- 795 Name: NSSLGetPeerCert() 796 797 Description: Get SSL peer certificate in DER form 798 799 Arguments: connection: A handle to a SSL connection to be queried. 800 pCertBuff: [OUTPUT] A pointer to buffer in which the 801 certificate should be written. (The buffer size and 802 address should be aligned to NSSL_IO_BUFFER_ALIGN] 803 pCertBuffLen: [INPUT/OUTPUT] A pointer to int specifying 804 length of pCertBuff. NSSL_RVAL_INVALID_SIZE 805 is returned if the certificate is 806 larger then provided buffer size. Use 807 NSSLGetPeerCertSize to determine the size of the 808 buffer to pass. After completion length of peer 809 certificate (in DER form) is written into it. 810 811 Returns: NSSL_RVAL_OK on success. Appropriate error code on failure. 812 *---------------------------------------------------------------------------*/ 813 NSSL_RVAL NSSLGetPeerCert(NSSLConnectionHandle connection, 814 unsigned char* pCertBuff, 815 int *pCertBuffLen); 816 817 /*--------------------------------------------------------------------------- 818 Name: NSSLGetCipherInfo() 819 820 Description: Get details of the cipher being used for the SSL connection. 821 822 Arguments: connection: A handle to a SSL connection to be queried. 823 pVersionBuf: [Output] A pointer to hold cipher version 824 (memory for the buffer to be allocated by the application), 825 on completion contains a null terminated cipher version. 826 versionBufLen: [Input] Length of input pVersionBuf. 827 pNameBuf: [Output] A pointer to hold cihpher Name 828 (memory for the buffer to be allocated by the application), 829 on completion contains a null terminated cipher name. 830 nameBufLen: [Input] Length of input pNameBuf. 831 pBits: [Output] A pointer to hold count of secret bits used for cipher. 832 833 Returns: NSSL_RVAL_OK on success. Appropriate error code on failure. 834 *---------------------------------------------------------------------------*/ 835 NSSL_RVAL NSSLGetCipherInfo(NSSLConnectionHandle connection, 836 char* pVersionBuf, int versionBufLen, 837 char* pNameBuf, int nameBufLen, 838 int *pBits); 839 840 /*--------------------------------------------------------------------------- 841 Name: NSSLExportInternalServerCertificate 842 843 Description: Exports the specified internal server certificate (if the 844 certificte is 'exportable'). 845 846 NOTE: Access to the individual built-in 847 certificte is restricted based on capabilities of the 848 application. NSSL_RVAL_CERT_NO_ACCESS is returned if 849 application tries to use a certificate for which it 850 does not have access permission. NSSL_RVAL_CERT_NOT_EXPORTALE is returned 851 if the certificate is not 'exportable'. 852 853 Arguments: 854 id[IN]: ID of the certificate to be exported 855 pCertBuf[OUT]: Pointer to buffer where the certificate data is 856 to be exported. Has to be aligned to PPC IPC 857 cache boundary. 858 pCertBufSize[OUT]: Pointer to hold size of pCertBuf. The caller 859 should provide allocated size of ‘pCertBuf’, 860 on return it will contain the size of ‘pCertBuf’ 861 filled with the certificate data. 862 pCertType[OUT]: Pointer to hold the type of certificate 863 (currently only NSSL_CERT_TYPE_DER is supported) 864 865 Pass pCertBuf = NULL and *pCertBufSize=0 to get size of the 866 certificate data in ‘pCertBufSize’ 867 868 Returns: NSSL_RVAL_OK on success. Appropriate error code on failure. 869 *---------------------------------------------------------------------------*/ 870 NSSL_RVAL NSSLExportInternalServerCertificate(NSSLServerCertID id, 871 char* pCertBuf, 872 int *pCertBufSize, 873 NSSLCertType *pCertType); 874 875 /*--------------------------------------------------------------------------- 876 Name: NSSLExportInternalClientCertificate 877 878 Description: Exports the specified internal client certificate and its 879 private key (if the certificate is 'exportable'). 880 881 NOTE: Access to the individual built-in 882 certificte is restricted based on capabilities of the 883 application. NSSL_RVAL_CERT_NO_ACCESS is returned if 884 application tries to use a certificate for which it 885 does not have access permission. NSSL_RVAL_CERT_NOT_EXPORTALE is returned 886 if the certificate is not 'exportable'. 887 888 Arguments: 889 id[IN]: ID of the certificate to be exported. 890 pCertBuf[OUT]: Pointer to buffer where the certificate data is 891 to be exported. Has to be aligned to PPC IPC 892 cache boundary. 893 pCertBufSize[OUT]: Pointer to hold size of pCertBuf. The caller should 894 provide allocated size of ‘pCertBuf’, on return it 895 will contain the size of ‘pCertBuf’ filled with the 896 certificate data. 897 pCertType[OUT]: Pointer to hold the type of certificate 898 (currently only NSSL_CERT_TYPE_DER is supported) 899 pPvtKeyBuf[OUT]: Pointer to buffer where the private key data is to be 900 exported. Has to be aligned to PPC IPC 901 cache boundary. 902 pPvtKeyBufSize[OUT]: Pointer to hold size of pvtKeyBuf. The caller 903 should provide allocated size of ‘pPvtKeyBuf’, 904 on return it will contain the size of ‘pPvtKeyBuf’ 905 filled with the private key data. 906 pPvtKeyType[OUT]: Pointer to hold the type of private key (currently only 907 NSSL_PRIV_KEY_TYPE_RSA is supported and the RSA key is 908 exported in DER foramt) 909 910 Pass pCertBuf = NULL and *pCertBufSize=0 to get size of the 911 certificate data in ‘pCertBufSize’ 912 Pass pPvtKeyBuf = NULL and *pPvtKeyBufSize=0 to get size of the 913 private key data in ‘pPvtKeyBufSize’ 914 915 Returns: NSSL_RVAL_OK on success. Appropriate error code on failure. 916 *---------------------------------------------------------------------------*/ 917 NSSL_RVAL NSSLExportInternalClientCertificate(NSSLClientCertID id, 918 char* pCertBuf, 919 int *pCertBufSize, 920 NSSLCertType *pCertType, 921 char* pPvtKeyBuf, 922 int *pPvtKeyBufSize, 923 NSSLPrivKeyType *pPvtKeyType); 924 #ifdef __cplusplus 925 } 926 #endif 927 928 #endif /* NSSLCLIENT_H */ 929