Skip to main content

OCSP support and configuration

RFC 6187: Certificate-Based Authentication

The NanoSSH client and NanoSSH server support RFC 6187 certificate-based authentication. The NanoSSH client requests certificate-based authentication from the server by sending the string “x509v3-ssh-rsa”, as required by RFC 6187. When the request is received, the server contacts the OCSP responder to obtain a fresh OCSP response for its certificate. The NanoSSH server responds by including its own certificate along with the OCSP response in its response to the client. The client parses the obtained certificate for validity. It also parses the OCSP response and terminates the connection if the certificate is revoked or unknown.

NanoSSH supports certificate-based client authentication. The client uses the “publickey” USER_AUTH_MESSAGE to send the certificate to the server. The client sends a x509v3-ssh-rsa/x509v3-ecdsa-sha2-nistp256/x509v3-ecdsa-sha2-nistp384/x509v3-ecdsa-sha2-nistp521 string if it is sending a certificate to the server, and then the server extracts the certificate and validates it against its trust chain.

For example code that shows how to implement certificate-based authentication, refer to ssh_example.c and sshc_example.c (both in the examples directory), and search for the __ENABLE_MOCANA_SSH_X509V3_RFC_6187_SUPPORT__ flag.

  • Server configuration: If the certificate has a valid AIA field and OCSP URI, then the OCSP URL is picked up from the certificate. The OCSP responder URL can also be manually configured by setting the SSH_sshSettings->pOcspResponderUrl value,

    SSH_sshSettings->pOcspResponderUrl = "http://127.0.0.1:8907";

    Note: Use the ocsp_url command-line argument if using ssh_example.c.

  • Client configuration: Write a function that returns the CA certificate that corresponds to the issuer’s distinguished name (DN), and assign that function as the funcPtrCertificateStoreLookup callback.

    SSHC_sshClientSettings->funcPtrCertificateStoreLookup = <your function-name>

  • Compiler flags: Add the following arguments to the build script to configure the client self-authentication certificate:

    • –client_cert_auth

    • –cert

OCSP Stapling for Certificate-Based Authentication

NanoSSH Client and NanoSSH Server support OCSP stapling which checks for the revocation status of X.509 digital certificates. The certificate presenter includes the OCSP responses and a time-stamped OCSP response signed by the CA to the other entity which eliminates the need for servers and clients to contact the CA.

OCSP Client API for Certificate Revocation Status

The OCSP_CLIENT_getCertStatus API may be used to verify the certificate revocation status.

#ifdef __ENABLE_MOCANA_OCSP_CERT_VERIFY__

MOC_EXTERN MSTATUS

OCSP_CLIENT_getCertStatus(ubyte *pCertificate, ubyte4 certLen, certChainPtr pCertChain, the ubyte *pAnchorCert, ubyte4 anchorCertLen);
#endif /* __ENABLE_MOCANA_OCSP_CERT_VERIFY__ */

NanoSSH Certificate Status Callback

The NanoSSH certificate status callback is as follows:

sbyte4(*funcPtrCertStatus) (sbyte4 connectionInstance, the ubyte *pUser, ubyte4 userLength, sbyte4 cert_status, ubyte *pCertificate, ubyte4 certLen, certChainPtr pCertChain, the ubyte *pAnchorCert, ubyte4 anchorCertLen);

where:

  • connectionInstance: Connection instance returned from SSH_acceptConnection() or SH_ASYNC_acceptConnection().

  • pUser: A pointer to the username.

  • userLength: Number of bytes in the username (pUser).

  • cert_status: Certificate verification status done by the stack.

  • pCertificate: Certificate of the peer.

  • certLen: Length of the certificate buffer.

  • pCertChain: Certificate chain leading to the anchor.

  • pAnchorCert: Anchor CA certificate if not present in pCertChain.

  • anchorCertLen: Anchor certificate length if present.

If the call is successful, OK (0) is returned; otherwise, a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function’s returned error status, use the DISPLAY_ERROR macro.

For example code that shows how to implement certificate-based authentication, refer to ssh_example.c and sshc_example.c (both in the examples directory), and search for the __ENABLE_MOCANA_SSH_OCSP_SUPPORT__ flag.

  • Server configuration: Write a function that returns the verification status and the certificate(s), and assign that function as the funcPtrCertStatus callback.

    SSH_sshSettings->funcPtrCertStatus = <your-function-name>

  • Client configuration: Write a function that returns the verification status and the certificate(s), and assign that function as the funcPtrCertStatus callback.

    SSHC_sshClientSettings->funcPtrCertStatus = <your function-name>

  • Compiler flags: Define the following flags to configure the OCSP stapling support for certificate-based authentication:

    • __ENABLE_MOCANA_SSH_OCSP_SUPPORT__

    • __ENABLE_MOCANA_OCSP_CLIENT__

    • __ENABLE_MOCANA_OCSP_CERT_VERIFY__

OCSP Timeout Callback for NanoSSH Server

NanoSSH allows the timeout value to be configured when the server communicates with the OCSP responder.

  • Server configuration: Write a function that returns the verification status and the certificate(s), and assign that function as the funcPtrCertStatus callback.

    SSH_sshSettings->ocspTimeout = <timeout-value>

  • Compiler flag: Define the following flag to configure the OCSP timeout value:

    __ENABLE_MOCANA_OCSP_TIMEOUT_CONFIG__
In this section: