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