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:
OverSIP::SipEvents.on_client_tls_handshake
OverSIP::SipEvents.on_server_tls_handshake
OverSIP::WebSocketEvents.on_client_tls_handshake
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, andnil
when no certificate was provided by the peer or no CA’s were provided for TLS validation (ca_dir
parameter within thetls
section ofoversip.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 benil
.
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