/ home / Documentation / 1.2.x / API / TLS API

TLS API: Module OverSIP::TLS

OverSIP provide TLS utilities for validating and inspecting TLS certificates provided by peers via the OverSIP::TLS module. Those methods are useful within the following callbacks:

Module class methods

validate(pems)

Validates the given chain of X509 certificates by performing common TLS validation procedures.

Parameters

pems
An Array with the chain of X509 certificates in PEM format (String) presented by the peer during the TLS handshake. The first element is the most-resolved certificate, followed by the successive intermediate certificates and the root (or CA) certificate at the end. It could be empty if the client does not present a TLS certificate.

Return value

The return value is an Array with the following fields:

cert
The OpenSSL::X509::Certificate instance of the first certificate provided by the peer (nil if the client did not present a certificate).
validated
true if the given certificate(s) are valid according to the TLS validation procedures, false otherwise, and nil when no certificate was provided by the peer or no CA’s were provided for TLS validation (ca_dir parameter within the tls section of oversip.conf).
tls_error
TLS validation error code (Fixnum) in case of validation error.
tls_error_string
TLS validation error description (String) in case of validation error.

Example

def (OverSIP::SipEvents).on_server_tls_handshake connection, pems
  cert, validated, tls_error, tls_error_string = ::OverSIP::TLS.validate pems

  if validated
    log_info "valid TLS certificate"
  else
    log_notice "invalid TLS certificate (TLS error: #{tls_error}, description: #{tls_error_string})"
    connection.close
  end
end

get_sip_identities(cert)

Extracts the SIP domain identities from a TLS certificate by following the procedures in RFC 5922.

Parameters

cert
An OpenSSL::X509::Certificate instance. It could also be nil.

Return value

The return value is an Array with the SIP domain identities (Strings) found in the certificate. If cert parameter is nil then the returned value is an empty Array.

Example

def (OverSIP::SipEvents).on_server_tls_handshake connection, pems
  cert, validated, tls_error, tls_error_string = ::OverSIP::TLS.validate pems
  sip_identities = ::OverSIP::TLS.get_sip_identities cert

  # sip_identities is [ "example.net", "sip.example.net" ]
  log_info "SIP identities in the certificate: #{sip_identities}"
end

/ home / Documentation / 1.2.x / API / TLS API