#ifndef NSSLCLIENT_H #define NSSLCLIENT_H /*---------------------------------------------------------------------------* Project: Nintendo SSL Client File: nsslclient.h Description: This file provides the SSL client side APIs for establishing a secure SSL connection with an SSL server. Copyright (C) 2012 Nintendo. All rights reserved. These coded instructions, statements, and computer programs contain proprietary information of Nintendo of America Inc. and/or Nintendo Company Ltd., and are protected by Federal copyright law. They may not be disclosed to third parties or copied or duplicated in any form, in whole or in part, without the prior written consent of Nintendo. *---------------------------------------------------------------------------*/ #ifdef __ghs__ #include #endif #include #include #define NSSL_IO_BUFFER_ALIGN 64 #ifdef __cplusplus extern "C" { #endif /*---------------------------------------------------------------------------* * * Globals/Externs * -- Variables/Functions -- * *---------------------------------------------------------------------------*/ /*---------------------------------------------------------------------------* * * Constants defined for this file * -- #Defines's -- * *---------------------------------------------------------------------------*/ #define NSSL_EMPTY_STR "" #define NSSL_EMPTY_STR_LEN 0 #define NSSL_RM_FD_INVALID (-1) /* * Bit masks to be used for peer validation options for SSL handshake * ( 'peerVerifyOptions' parameter for 'NSSLCreateConnection' ) */ /* NSSL_VERIFY_NONE: Do not verify peer certificate */ #define NSSL_VERIFY_NONE 0x0 /* NSSL_VERIFY_PEER_CA: Validate the peer certificate using * the server certificates specified using NSSLAddServerPKIExternal * NOTE: Peer certificate's ValidFrom and ValidTo dates are * not checked unless NSSL_VERIFY_DATE_VALIDITY bit is also set. */ #define NSSL_VERIFY_PEER_CA 0x1 /* * NSSL_VERIFY_HOSTNAME: In addition to peer certificate validation * (see NSSL_VERIFY_PEER_CA), also check if the hostname matches * the Common Name field or a Subject Alternate Name field in the * peer certificate. * * NOTE: If NSSL_VERIFY_HOSTNAME is set, NSSL_VERIFY_PEER_CA is * assumed to be set. */ #define NSSL_VERIFY_HOSTNAME 0x2 /* * NSSL_VERIFY_HOSTNAME: In addition to peer certificate validation, * validate certificates ValidFrom and ValidTo fields. * * NOTE: If NSSL_VERIFY_DATE_VALIDITY is set, NSSL_VERIFY_PEER_CA is * assumed to be set. */ #define NSSL_VERIFY_DATE_VALIDITY 0x4 #define NSSL_VERIFY_ALL \ (NSSL_VERIFY_PEER_CA | NSSL_VERIFY_HOSTNAME | NSSL_VERIFY_DATE_VALIDITY) #define NSSL_VERIFY_ALL_EXCEPT_DATE \ (NSSL_VERIFY_PEER_CA | NSSL_VERIFY_HOSTNAME ) /* Bit masks for NSSL context flags */ /*Enables CRL checking only for the certificate chain leaf certificate */ #define NSSL_CTX_FLAG_CRL_CHECK_LEAF 0x1 /*Enables CRL checking for the rest of the certificate chain */ /*(Valid only if NSSL_CTX_FLAG_CRL_CHECK_LEAF is also set) */ #define NSSL_CTX_FLAG_CRL_CHECK_CHAIN 0x2 /* peer certificate validation status codes */ #define NSSL_CERT_VALID 0 #define NSSL_CERT_V_ERR_UNKNOWN 1000 #define NSSL_CERT_V_ERR_HOSTNAME_MISMATCH 1001 #define NSSL_CERT_V_ERR_UNABLE_TO_GET_ISSUER_CERT 2 #define NSSL_CERT_V_ERR_UNABLE_TO_GET_CRL 3 #define NSSL_CERT_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE 4 #define NSSL_CERT_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE 5 #define NSSL_CERT_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY 6 #define NSSL_CERT_V_ERR_CERT_SIGNATURE_FAILURE 7 #define NSSL_CERT_V_ERR_CRL_SIGNATURE_FAILURE 8 #define NSSL_CERT_V_ERR_CERT_NOT_YET_VALID 9 #define NSSL_CERT_V_ERR_CERT_HAS_EXPIRED 10 #define NSSL_CERT_V_ERR_CRL_NOT_YET_VALID 11 #define NSSL_CERT_V_ERR_CRL_HAS_EXPIRED 12 #define NSSL_CERT_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD 13 #define NSSL_CERT_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD 14 #define NSSL_CERT_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD 15 #define NSSL_CERT_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD 16 #define NSSL_CERT_V_ERR_OUT_OF_MEM 17 #define NSSL_CERT_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT 18 #define NSSL_CERT_V_ERR_SELF_SIGNED_CERT_IN_CHAIN 19 #define NSSL_CERT_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY 20 #define NSSL_CERT_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE 21 #define NSSL_CERT_V_ERR_CERT_CHAIN_TOO_LONG 22 #define NSSL_CERT_V_ERR_CERT_REVOKED 23 #define NSSL_CERT_V_ERR_INVALID_CA 24 #define NSSL_CERT_V_ERR_PATH_LENGTH_EXCEEDED 25 #define NSSL_CERT_V_ERR_INVALID_PURPOSE 26 #define NSSL_CERT_V_ERR_CERT_UNTRUSTED 27 #define NSSL_CERT_V_ERR_CERT_REJECTED 28 #define NSSL_CERT_V_ERR_SUBJECT_ISSUER_MISMATCH 29 #define NSSL_CERT_V_ERR_AKID_SKID_MISMATCH 30 #define NSSL_CERT_V_ERR_AKID_ISSUER_SERIAL_MISMATCH 31 #define NSSL_CERT_V_ERR_KEYUSAGE_NO_CERTSIGN 32 #define NSSL_CERT_V_ERR_UNABLE_TO_GET_CRL_ISSUER 33 #define NSSL_CERT_V_ERR_UNHANDLED_CRITICAL_EXTENSION 34 #define NSSL_CERT_V_ERR_KEYUSAGE_NO_CRL_SIGN 35 #define NSSL_CERT_V_ERR_UNHANDLED_CRITICAL_CRL_EXTENSION 36 #define NSSL_CERT_V_ERR_INVALID_NON_CA 37 #define NSSL_CERT_V_ERR_PROXY_PATH_LENGTH_EXCEEDED 38 #define NSSL_CERT_V_ERR_KEYUSAGE_NO_DIGITAL_SIGNATURE 39 #define NSSL_CERT_V_ERR_PROXY_CERTIFICATES_NOT_ALLOWED 40 #define NSSL_CERT_V_ERR_INVALID_EXTENSION 41 #define NSSL_CERT_V_ERR_INVALID_POLICY_EXTENSION 42 #define NSSL_CERT_V_ERR_NO_EXPLICIT_POLICY 43 #define NSSL_CERT_V_ERR_DIFFERENT_CRL_SCOPE 44 #define NSSL_CERT_V_ERR_UNSUPPORTED_EXTENSION_FEATURE 45 #define NSSL_CERT_V_ERR_UNNESTED_RESOURCE 46 #define NSSL_CERT_V_ERR_PERMITTED_VIOLATION 47 #define NSSL_CERT_V_ERR_EXCLUDED_VIOLATION 48 #define NSSL_CERT_V_ERR_SUBTREE_MINMAX 49 #define NSSL_CERT_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE 51 #define NSSL_CERT_V_ERR_APPLICATION_VERIFICATION 50 #define NSSL_CERT_V_ERR_UNSUPPORTED_CONSTRAINT_SYNTAX 52 #define NSSL_CERT_V_ERR_UNSUPPORTED_NAME_SYNTAX 53 #define NSSL_CERT_V_ERR_CRL_PATH_VALIDATION_ERROR 54 /* * Client certificates (to be used when calling NSSLSetClientPKI) * */ #define NSSL_CLIENT_CERT_NONE (0) /* Nintendo client cert IDs */ #define NSSL_CLIENT_CERT_DEFAULT (1) /* * Server i.e. trusted CA certificates (to be used when calling NSSLAddServerPKI) * */ /* * Group: CERTSTORE_ENTITY_GROUP_NINTENDO_CA_CERTS * Nintendo CA certificate IDs */ #define NSSL_SERVER_CERT_NONE (0) #define NSSL_SERVER_CERT_NINTENDO_CA (100) #define NSSL_SERVER_CERT_NINTENDO_CA_G2 (101) #define NSSL_SERVER_CERT_NINTENDO_CA_G3 (102) #define NSSL_SERVER_CERT_NINTENDO_CLASS2_CA (103) #define NSSL_SERVER_CERT_NINTENDO_CLASS2_CA_G2 (104) #define NSSL_SERVER_CERT_NINTENDO_CLASS2_CA_G3 (105) /* * Group : CERTSTORE_ENTITY_GROUP_COMMERCIAL_CA_CERTS * Commercial CA certificate IDs */ #define NSSL_SERVER_CERT_BALTIMORE_CYBERTRUST_ROOT_CA (1001) #define NSSL_SERVER_CERT_CYBERTRUST_GLOBAL_ROOT_CA (1002) #define NSSL_SERVER_CERT_VERIZON_GLOBAL_ROOT_CA (1003) #define NSSL_SERVER_CERT_GLOBALSIGN_ROOT_CA (1004) #define NSSL_SERVER_CERT_GLOBALSIGN_ROOT_CA_R2 (1005) #define NSSL_SERVER_CERT_GLOBALSIGN_ROOT_CA_R3 (1006) #define NSSL_SERVER_CERT_VERISIGN_CLASS3_PUBLIC_PRIMARY_CA_G3 (1007) #define NSSL_SERVER_CERT_VERISIGN_UNIVERSAL_ROOT_CA (1008) #define NSSL_SERVER_CERT_VERISIGN_CLASS3_PUBLIC_PRIMARY_CA_G5 (1009) #define NSSL_SERVER_CERT_THAWTE_PRIMARY_ROOT_CA_G3 (1010) #define NSSL_SERVER_CERT_THAWTE_PRIMARY_ROOT_CA (1011) #define NSSL_SERVER_CERT_GEOTRUST_GLOBAL_CA (1012) #define NSSL_SERVER_CERT_GEOTRUST_GLOBAL_CA2 (1013) #define NSSL_SERVER_CERT_GEOTRUST_PRIMARY_CA (1014) #define NSSL_SERVER_CERT_GEOTRUST_PRIMARY_CA_G3 (1015) #define NSSL_SERVER_CERT_ADDTRUST_EXT_CA_ROOT (1016) #define NSSL_SERVER_CERT_COMODO_CA (1017) #define NSSL_SERVER_CERT_UTN_DATACORP_SGC_CA (1018) #define NSSL_SERVER_CERT_UTN_USERFIRST_HARDWARE_CA (1019) #define NSSL_SERVER_CERT_DIGICERT_HIGH_ASSURANCE_EV_ROOT_CA (1020) #define NSSL_SERVER_CERT_DIGICERT_ASSURED_ID_ROOT_CA (1021) #define NSSL_SERVER_CERT_DIGICERT_GLOBAL_ROOT_CA (1022) #define NSSL_SERVER_CERT_GTE_CYBERTRUST_GLOBAL_ROOT (1023) #define NSSL_SERVER_CERT_VERISIGN_CLASS3_PUBLIC_PRIMARY_CA (1024) #define NSSL_SERVER_CERT_THAWTE_PREMIUM_SERVER_CA (1025) #define NSSL_SERVER_CERT_EQUIFAX_SECURE_CA (1026) #define NSSL_SERVER_CERT_ENTRUST_SECURE_SERVER_CA (1027) #define NSSL_SERVER_CERT_VERISIGN_CLASS3_PUBLIC_PRIMARY_CA_G2 (1028) #define NSSL_SERVER_CERT_ENTRUST_CA_2048 (1029) #define NSSL_SERVER_CERT_ENTRUST_ROOT_CA (1030) #define NSSL_SERVER_CERT_ENTRUST_ROOT_CA_G2 (1031) #define NSSL_SERVER_CERT_DIGICERT_ASSURED_ID_ROOT_CA_G2 (1032) #define NSSL_SERVER_CERT_DIGICERT_GLOBAL_ROOT_CA_G2 (1033) /*---------------------------------------------------------------------------* * * Data types defined for this file * -- Struct's, Typedef's, Enum's -- * *---------------------------------------------------------------------------*/ typedef int NSSLClientCertID; typedef int NSSLServerCertID; typedef CertstoreEntityGroupMask NSSLServerCertGroupMask; typedef enum { NSSL_HANDSHAKE_OK, NSSL_HANDSHAKE_INCOMPLETE, NSSL_HANDSHAKE_ERROR_UNKNOWN, NSSL_HANDSHAKE_ERROR_INVALID_CLIENT_CERT, NSSL_HANDSHAKE_ERROR_CLIENT_CERT_NEEDED, NSSL_HANDSHAKE_ERROR_CIPHER_MISMATCH, NSSL_HANDSHAKE_ERROR_UNSUPPORTED_PROTOCOL, NSSL_HANDSHAKE_ERROR_PEER_CERT_HOSTNAME_MISMATCH, NSSL_HANDSHAKE_ERROR_SERVER_CERT_VERIFY_FAILED } NSSLHandshakeError; typedef enum { NSSL_SSLVERSION_INVALID = -1, /* Automatically select the highest version supported out of TLS1.0/SSLv3 */ NSSL_SSLVERSION_AUTO, /* TLS 1.0 */ NSSL_SSLVERSION_TLSv1, /* SSLv3 */ NSSL_SSLVERSION_SSLv3 } NSSLSSLVersion; typedef enum { NSSL_CERT_TYPE_DER } NSSLCertType; typedef enum { NSSL_PRIV_KEY_TYPE_RSA } NSSLPrivKeyType; typedef enum { NSSL_CRL_TYPE_DER } NSSLCrlType; typedef int NSSLContextHandle; typedef int NSSLConnectionHandle; typedef int NSSLSessionHandle; typedef int NSSLCertValidationStatus; /*---------------------------------------------------------------------------* * * File scope functions/symbols defined for this file * -- Function Prototypes, File Scope Data -- * *---------------------------------------------------------------------------*/ /*---------------------------------------------------------------------------* * * PRIVATE METHODS * *---------------------------------------------------------------------------*/ /*---------------------------------------------------------------------------* * * PUBLIC METHODS * *---------------------------------------------------------------------------*/ /*--------------------------------------------------------------------------- Name: NSSLCreateContext() Description: Creates an SSL context to hold certificates and keys to be used for SSL communication. The certificates and keys associated with a SSL context by the application will be used for all SSL connections created with the context. An application can create maximum upto 32 contexts. Arguments: sslVersion: Version of SSL/TLS to be used. Returns: NSSL context handle (0 or +ve) on success. Appropriate error code (-ve) on failure. *---------------------------------------------------------------------------*/ NSSLContextHandle NSSLCreateContext(NSSLSSLVersion sslVersion); /*--------------------------------------------------------------------------- Name: NSSLDestroyContext() Description: Destroys a SSL Context. All the SSL connections associated with the context will be also be destroyed. Arguments: context: A handle to the context to be destroyed. Returns: NSSL_RVAL_OK on success. Appropriate error code on failure. *---------------------------------------------------------------------------*/ NSSL_RVAL NSSLDestroyContext(NSSLContextHandle context); /*--------------------------------------------------------------------------- Name: NSSLSetClientPKI() Description: Set the client certificate and private key (from the build-in certificate store) to be used in case the server performs client certificate verification. The certificate and private key will be used for all the connections created under the context. NOTE: Access to the individual built-in certificates is restricted based on capabilities of the application. NSSL_RVAL_CERT_NO_ACCESS is returned if application tries to use a certificate for which it does not have access permission. Arguments: context: Context clientCertID: Identifier of the built-in client certificate to be used. Returns: NSSL_RVAL_OK on success. Appropriate error code on failure. *---------------------------------------------------------------------------*/ NSSL_RVAL NSSLSetClientPKI(NSSLContextHandle context, NSSLClientCertID clientCertID); /*--------------------------------------------------------------------------- Name: NSSLAddServerPKI() Description: Add a trusted CA certificate (from the build-in certificate store) to be used to verify the peer certificate. The certificate is used for all the connections created under the context. NSSLAddServerPKI can be called multiple times for a context to add multiple trusted CA certificates. NOTE: Access to the individual built-in certificates is restricted based on capabilities of the application. NSSL_RVAL_CERT_NO_ACCESS is returned if application tries to use a certificate for which it does not have access permission. Arguments: context: Context serverCertID: Identifier for the CA certificate to be added. Returns: NSSL_RVAL_OK on success. Appropriate error code on failure. *---------------------------------------------------------------------------*/ NSSL_RVAL NSSLAddServerPKI(NSSLContextHandle context, NSSLServerCertID serverCertID); /*--------------------------------------------------------------------------- Name: NSSLAddServerPKIGroups() Description: Add group(s) of server verification certificate (from the build-in certificate store) for the context. The certificates will be used for all the connections created under the context. NOTE: NSSL_RVAL_OK is returned even if error(s) are encountered in adding one or more of the certificates. addedCount and errorCount indicate the number of certificates successfully added and the the number of certificates which could not be added due to error. Arguments: context: The context for which the certificates are to be added. certGroupMask: A bit mask with bits for the certificate group to be added to the context. addedCount[out]: A pointer to hold the count of certificates added to the context. errorCount[out]: A pointer to hold the count of certificates which could not be added to the context (due to error). Returns: NSSL_RVAL_OK on success. Appropriate error code on failure. *---------------------------------------------------------------------------*/ NSSL_RVAL NSSLAddServerPKIGroups(NSSLContextHandle context, NSSLServerCertGroupMask certGroupMask, int *addedCount, int *errorCount); /*--------------------------------------------------------------------------- Name: NSSLSetClientPKIExternal() Description: Set the client certificate and private key to be used in case the server performs client certificate verification. The certificate and private key will be used for all the connections created under the context. Arguments: context: The context for which the client certificate is to be set. pClientCert: Certificate buffer (The buffer size and address should be aligned to NSSL_IO_BUFFER_ALIGN) clientCertLen: Certificate buffer length (max size 4KB) clientCertType: Type of the certificate (currently only NSSL_CERT_TYPE_DER is supported, pClientCert should contain client certificate in DER format) pClientPrivKey: Private key buffer (The buffer size and address should be aligned to NSSL_IO_BUFFER_ALIGN], pClientPrivKey should contain RSA private key in PKCS#1 format) clientPrivKeyLen: Private key buffer length (max size 4KB) clientPrivKeyType: Type of the private key (currently only NSSL_PRIV_KEY_TYPE_RSA is supported) Returns: NSSL_RVAL_OK on success. Appropriate error code on failure. *---------------------------------------------------------------------------*/ NSSL_RVAL NSSLSetClientPKIExternal(NSSLContextHandle context, const u8* pClientCert, int clientCertLen, NSSLCertType clientCertType, const u8* pClientPrivKey, int clientPrivKeyLen, NSSLPrivKeyType clientPrivKeyType); /*--------------------------------------------------------------------------- Name: NSSLAddServerPKIExternal() Description: Add a trusted CA certificate to be used to verify the peer certificate. The certificate is used for all the connections created under the context. NSSLAddServerPKIExternal can be called multiple times for a context to add multiple trusted CA certificates. Arguments: context: The context for which the certificate is to be added. pServerCert: Certificate buffer (The buffer size and address should be aligned to NSSL_IO_BUFFER_ALIGN]). serverCertLen: Certificate buffer length serverCertType: Type of the certificate (currently only NSSL_CERT_TYPE_DER is supported, pServerCert should contain a certificate in DER format). Returns: NSSL_RVAL_OK on success. Appropriate error code on failure. *---------------------------------------------------------------------------*/ NSSL_RVAL NSSLAddServerPKIExternal(NSSLContextHandle context, const u8* pServerCert, int serverCertLen, NSSLCertType serverCertType); /*--------------------------------------------------------------------------- Name: NSSLAddCRLExternal() Description: Add a Certificate Revocation List (CRL) to be used during the verification of the peer certificate. The CRL is used for all the connections created under the context. NSSLAddCRLExternal can be called multiple times for a context to add multiple CRLs. Arguments: context: The context for which the CRL is to be added. pCRL: CRL buffer (The buffer size and address should be aligned to NSSL_IO_BUFFER_ALIGN]). crlLen: CRL buffer length crlType: Type of the CRL (currently only NSSL_CRL_TYPE_DER is supported, pCRL should contain a CRL in DER format). Returns: NSSL_RVAL_OK on success. Appropriate error code on failure. *---------------------------------------------------------------------------*/ NSSL_RVAL NSSLAddCRLExternal(NSSLContextHandle context, const u8* pCRL, int crlLen, NSSLCrlType crlType); /*--------------------------------------------------------------------------- Name: NSSLContextSetFlags() Description: Sets flags for NSSL context that control behavior during verification of server certificate Arguments: context: The NSSL Context for which the flags need to be set. flags: bitmask of flags to be set Returns: NSSL_RVAL_OK on success. Appropriate error code on failure. *---------------------------------------------------------------------------*/ NSSL_RVAL NSSLContextSetFlags(NSSLContextHandle context, unsigned long flags); /*--------------------------------------------------------------------------- Name: NSSLContextClearFlags() Description: Clears specified flags for NSSL context that control behavior during verification of server certificate Arguments: context: NSSL Context for which the flags need to be cleared. flags: bitmask of flags to be cleared Returns: NSSL_RVAL_OK on success. Appropriate error code on failure. *---------------------------------------------------------------------------*/ NSSL_RVAL NSSLContextClearFlags(NSSLContextHandle context, unsigned long flags); /*--------------------------------------------------------------------------- Name: NSSLContextGetFlags() Description: Gets current flags for NSSL context that control behavior during verification of server certificate Arguments: context: NSSL Context for which the flags need to be obtained. pFlags: [output] pointer to an unsigned long where bitmask of flags will be stored Returns: NSSL_RVAL_OK on success. Appropriate error code on failure. *---------------------------------------------------------------------------*/ NSSL_RVAL NSSLContextGetFlags(NSSLContextHandle context, unsigned long *pFlags); /*--------------------------------------------------------------------------- Name: NSSLCreateConnection() Description: Creates a new SSL connection to perform secure data transfer over TCP/IP connection created by an application. An application can create maximum upto 32 connections. Arguments: context: A context to be used for the connection. Client and server certificates associated with the context will be used for the connection. pHostname: hostname of the server (used for hostname verification) hostnameLen: Length of hostname buffer peerVerifyOptions: Bit mask for verification options for peer certificate sockfd: Socket fd of the underlying TCP/IP connection. Application should create a socket using SOSocket, connect it to the server using SOConnect before calling NSSLCreateConnection. blocking: Indicator if the socket is going to be used in a blocking mode or non-blocking mode. Returns: NSSL connection handle (0 or +ve) on success, Appropriate error code (-ve) on failure. *---------------------------------------------------------------------------*/ NSSLConnectionHandle NSSLCreateConnection(NSSLContextHandle context, const char* pHostname, int hostnameLen, int peerVerifyOptions, int sockfd, BOOL blocking); /*--------------------------------------------------------------------------- Name: NSSLDestroyConnection() Description: Shuts down the underlying SSL connection and destroys the connection. The application should close the underlying TCP/IP socket after calling NSSLDestroyConnection. Arguments: connection: A handle to the connection to be destroyed. Returns: NSSL_RVAL_OK on success. Appropriate error code on failure. *---------------------------------------------------------------------------*/ NSSL_RVAL NSSLDestroyConnection(NSSLConnectionHandle connection); /*--------------------------------------------------------------------------- Name: NSSLDoHandshake() Description: Perform SSL handshake with the peer. Handshake error code is written into pHsError and peer certificate validation status is written into pPeerVertValidationStatus when completed. Arguments: connection: A SSL connection on which a handshake is to be performed pHsError: [Output] A pointer to hold handshake error code. pPeerVertValidationStatus: [Output] A pointer to hold bitmask indicating peer certificate validation status. Returns: NSSL_RVAL_OK on success else the following error codes NSSL_RVAL_WANT_READ/NSSL_RVAL_WANT_WRITE: (Only applicable for non blocking connections) The operation did not complete; NSSLDoHandshake should be called again later. If, by then, the underlying socket has data available for reading (if the result code is NSSL_RVAL_WANT_READ) or allows writing data (NSSL_RVAL_WANT_WRITE), then some TLS/SSL protocol progress will take place, i.e. at least part of an TLS/SSL record will be read or written. Note that the retry may again lead to a NSSL_RVAL_WANT_READ or NSSL_RVAL_WANT_WRITE condition. There is no fixed upper limit for the number of iterations that may be necessary until progress becomes visible at application protocol level. NSSL_RVAL_HANDSHAKE_ERROR: SSL handshake failed. NSSL_RVAL_IO_ERROR: Some IO error occurred on the underlying socket. NSSL_RVAL_NSSLLIB_ERROR: A failure in the NSSL library occurred. *---------------------------------------------------------------------------*/ NSSL_RVAL NSSLDoHandshake(NSSLConnectionHandle connection, NSSLHandshakeError* pHsError, NSSLCertValidationStatus *pPeerCertValidationStatus); /*--------------------------------------------------------------------------- Name: NSSLRead() Description: Read from the SSL connection, count of bytes read is written into pBytesRead when completed. Arguments: connection: A SSL connection from which to read. pBuf: [Output] Buffer to read into, (The buffer size and address should be aligned to NSSL_IO_BUFFER_ALIGN]). len: number of bytes to read pBytesRead: [Output] A pointer to hold the count of bytes read Returns: NSSL_RVAL_OK on success else the following error codes NSSL_RVAL_ZERO_RETURN: The SSL connection has been closed. NSSL_RVAL_WANT_READ/NSSL_RVAL_WANT_WRITE: (Only applicable for non blocking connections) The operation did not complete; the same NSSL I/O function should be called again later. If, by then, the underlying socket has data available for reading (if the result code is NSSL_RVAL_WANT_READ) or allows writing data (NSSL_RVAL_WANT_WRITE), then some TLS/SSL protocol progress will take place, i.e. at least part of an TLS/SSL record will be read or written. Note that the retry may again lead to a NSSL_RVAL_WANT_READ or NSSL_RVAL_WANT_WRITE condition. There is no fixed upper limit for the number of iterations that may be necessary until progress becomes visible at application protocol level. NSSL_RVAL_IO_ERROR: Some IO error occurred on the underlying socket. NSSL_RVAL_NSSLLIB_ERROR: A failure in the NSSL library occurred. *---------------------------------------------------------------------------*/ NSSL_RVAL NSSLRead(NSSLConnectionHandle connection, void* pBuf, int len, int* pBytesRead); /*--------------------------------------------------------------------------- Name: NSSLWrite() Description: Write to the SSL connection, count of bytes written is written into pBytesWritten when completed. Arguments: connection: A SSL connection to write to pBuf: Buffer to write into, (The buffer size and address should be aligned to NSSL_IO_BUFFER_ALIGN]). len: number of bytes to write pBytesWritten: [Output] A pointer to hold the count of bytes written Returns: NSSL_RVAL_OK on success else the following error codes NSSL_RVAL_ZERO_RETURN: The SSL connection has been closed. NSSL_RVAL_WANT_READ/NSSL_RVAL_WANT_WRITE: (Only applicable to non-blocking connections) The operation did not complete; the same NSSL I/O function should be called again later. If, by then, the underlying socket has data available for reading (if the result code is NSSL_RVAL_WANT_READ) or allows writing data (NSSL_RVAL_WANT_WRITE), then some TLS/SSL protocol progress will take place, i.e. at least part of an TLS/SSL record will be read or written. Note that the retry may again lead to a NSSL_RVAL_WANT_READ or NSSL_RVAL_WANT_WRITE condition. There is no fixed upper limit for the number of iterations that may be necessary until progress becomes visible at application protocol level. NSSL_RVAL_IO_ERROR: Some IO error occurred on the underlying socket. NSSL_RVAL_NSSLLIB_ERROR: A failure in the NSSL library occurred. *---------------------------------------------------------------------------*/ NSSL_RVAL NSSLWrite(NSSLConnectionHandle connection, const void* pBuf, int len, int* pBytesWritten); /*--------------------------------------------------------------------------- Name: NSSLGetSession() Description: Returns handle to SSL session which can be used for session resumption across SSL connection (under the same Context). The session handle is reference counted. NSSLGetSession() increments the count, use NSSLFreeSession to decrement the same. Arguments: connection: A handle to a SSL connection to be queried. Returns: NSSL session handle (0 or +ve) on success. Appropriate error code (-ve) on failure. *---------------------------------------------------------------------------*/ NSSLSessionHandle NSSLGetSession(NSSLConnectionHandle connection); /*--------------------------------------------------------------------------- Name: NSSLSetSession() Description: Sets SSL session handle on a connection to reuse the session. Arguments: connection: A handle to a SSL connection. session: A handle to a session to be reused. Returns: NSSL_RVAL_OK on success. Appropriate error code on failure. *---------------------------------------------------------------------------*/ NSSL_RVAL NSSLSetSession(NSSLConnectionHandle connection, NSSLSessionHandle session); /*--------------------------------------------------------------------------- Name: NSSLFreeSession() Description: Decrements reference count of SSL session handle obtained using NSSLGetSession. The session handle is released when the reference count goes to zero. Arguments: session: Handle to a session to be freed. Returns: NSSL_RVAL_OK on success. Appropriate error code on failure. *---------------------------------------------------------------------------*/ NSSL_RVAL NSSLFreeSession(NSSLSessionHandle session); /*--------------------------------------------------------------------------- Name: NSSLRemoveSession() Description: Removes a SSL session from cache. Arguments: session: Handle to a session to be removed. Returns: NSSL_RVAL_OK on success. Appropriate error code on failure. *---------------------------------------------------------------------------*/ NSSL_RVAL NSSLRemoveSession(NSSLSessionHandle session); /*--------------------------------------------------------------------------- Name: NSSLGetPending() Description: Returns the count of bytes available on the connection inside NSSL to read immediately. This is uses by libcurl. Arguments: connection: A handle to a SSL connection to be queried. pPendingBytes: [Output] A pointer to hold count of bytes available to be read Returns: NSSL_RVAL_OK on success. Appropriate error code on failure. *---------------------------------------------------------------------------*/ NSSL_RVAL NSSLGetPending(NSSLConnectionHandle connection, int* pPendingBytes); /*--------------------------------------------------------------------------- Name: NSSLGetPeerCertSize() Description: Get size of peer certificate in DER form Arguments: connection: A handle to a SSL connection to be queried. Returns: 0 or positive value indicates the length of the peer certificate in DER form. Negative value indicates appropriate error code. *---------------------------------------------------------------------------*/ int NSSLGetPeerCertSize(NSSLConnectionHandle connection); /*--------------------------------------------------------------------------- Name: NSSLGetPeerCert() Description: Get SSL peer certificate in DER form Arguments: connection: A handle to a SSL connection to be queried. pCertBuff: [OUTPUT] A pointer to buffer in which the certificate should be written. (The buffer size and address should be aligned to NSSL_IO_BUFFER_ALIGN] pCertBuffLen: [INPUT/OUTPUT] A pointer to int specifying length of pCertBuff. NSSL_RVAL_INVALID_SIZE is returned if the certificate is larger then provided buffer size. Use NSSLGetPeerCertSize to determine the size of the buffer to pass. After completion length of peer certificate (in DER form) is written into it. Returns: NSSL_RVAL_OK on success. Appropriate error code on failure. *---------------------------------------------------------------------------*/ NSSL_RVAL NSSLGetPeerCert(NSSLConnectionHandle connection, unsigned char* pCertBuff, int *pCertBuffLen); /*--------------------------------------------------------------------------- Name: NSSLGetCipherInfo() Description: Get details of the cipher being used for the SSL connection. Arguments: connection: A handle to a SSL connection to be queried. pVersionBuf: [Output] A pointer to hold cipher version (memory for the buffer to be allocated by the application), on completion contains a null terminated cipher version. versionBufLen: [Input] Length of input pVersionBuf. pNameBuf: [Output] A pointer to hold cihpher Name (memory for the buffer to be allocated by the application), on completion contains a null terminated cipher name. nameBufLen: [Input] Length of input pNameBuf. pBits: [Output] A pointer to hold count of secret bits used for cipher. Returns: NSSL_RVAL_OK on success. Appropriate error code on failure. *---------------------------------------------------------------------------*/ NSSL_RVAL NSSLGetCipherInfo(NSSLConnectionHandle connection, char* pVersionBuf, int versionBufLen, char* pNameBuf, int nameBufLen, int *pBits); /*--------------------------------------------------------------------------- Name: NSSLExportInternalServerCertificate Description: Exports the specified internal server certificate (if the certificte is 'exportable'). NOTE: Access to the individual built-in certificte is restricted based on capabilities of the application. NSSL_RVAL_CERT_NO_ACCESS is returned if application tries to use a certificate for which it does not have access permission. NSSL_RVAL_CERT_NOT_EXPORTALE is returned if the certificate is not 'exportable'. Arguments: id[IN]: ID of the certificate to be exported pCertBuf[OUT]: Pointer to buffer where the certificate data is to be exported. Has to be aligned to PPC IPC cache boundary. pCertBufSize[OUT]: Pointer to hold size of pCertBuf. The caller should provide allocated size of ‘pCertBuf’, on return it will contain the size of ‘pCertBuf’ filled with the certificate data. pCertType[OUT]: Pointer to hold the type of certificate (currently only NSSL_CERT_TYPE_DER is supported) Pass pCertBuf = NULL and *pCertBufSize=0 to get size of the certificate data in ‘pCertBufSize’ Returns: NSSL_RVAL_OK on success. Appropriate error code on failure. *---------------------------------------------------------------------------*/ NSSL_RVAL NSSLExportInternalServerCertificate(NSSLServerCertID id, char* pCertBuf, int *pCertBufSize, NSSLCertType *pCertType); /*--------------------------------------------------------------------------- Name: NSSLExportInternalClientCertificate Description: Exports the specified internal client certificate and its private key (if the certificate is 'exportable'). NOTE: Access to the individual built-in certificte is restricted based on capabilities of the application. NSSL_RVAL_CERT_NO_ACCESS is returned if application tries to use a certificate for which it does not have access permission. NSSL_RVAL_CERT_NOT_EXPORTALE is returned if the certificate is not 'exportable'. Arguments: id[IN]: ID of the certificate to be exported. pCertBuf[OUT]: Pointer to buffer where the certificate data is to be exported. Has to be aligned to PPC IPC cache boundary. pCertBufSize[OUT]: Pointer to hold size of pCertBuf. The caller should provide allocated size of ‘pCertBuf’, on return it will contain the size of ‘pCertBuf’ filled with the certificate data. pCertType[OUT]: Pointer to hold the type of certificate (currently only NSSL_CERT_TYPE_DER is supported) pPvtKeyBuf[OUT]: Pointer to buffer where the private key data is to be exported. Has to be aligned to PPC IPC cache boundary. pPvtKeyBufSize[OUT]: Pointer to hold size of pvtKeyBuf. The caller should provide allocated size of ‘pPvtKeyBuf’, on return it will contain the size of ‘pPvtKeyBuf’ filled with the private key data. pPvtKeyType[OUT]: Pointer to hold the type of private key (currently only NSSL_PRIV_KEY_TYPE_RSA is supported and the RSA key is exported in DER foramt) Pass pCertBuf = NULL and *pCertBufSize=0 to get size of the certificate data in ‘pCertBufSize’ Pass pPvtKeyBuf = NULL and *pPvtKeyBufSize=0 to get size of the private key data in ‘pPvtKeyBufSize’ Returns: NSSL_RVAL_OK on success. Appropriate error code on failure. *---------------------------------------------------------------------------*/ NSSL_RVAL NSSLExportInternalClientCertificate(NSSLClientCertID id, char* pCertBuf, int *pCertBufSize, NSSLCertType *pCertType, char* pPvtKeyBuf, int *pPvtKeyBufSize, NSSLPrivKeyType *pPvtKeyType); #ifdef __cplusplus } #endif #endif /* NSSLCLIENT_H */