Module org.snmp4j

Class TLSTM

    • Constructor Detail

      • TLSTM

        public TLSTM()
              throws java.net.UnknownHostException
        Creates a default TCP transport mapping with the server for incoming messages disabled.
        Throws:
        java.net.UnknownHostException - if the local host cannot be determined.
      • TLSTM

        public TLSTM​(TlsAddress address)
              throws java.io.IOException
        Creates a TLS transport mapping with the server for incoming messages bind to the given address. The securityCallback needs to be specified before listen() is called.
        Parameters:
        address - the address to bind for incoming requests.
        Throws:
        java.io.IOException - on failure of binding a local port.
      • TLSTM

        public TLSTM​(TlsTmSecurityCallback<java.security.cert.X509Certificate> securityCallback,
                     TlsAddress serverAddress)
              throws java.io.IOException
        Creates a TLS transport mapping that binds to the given address (interface) on the local host.
        Parameters:
        securityCallback - a security name callback to resolve X509 certificates to tmSecurityNames.
        serverAddress - the TcpAddress instance that describes the server address to listen on incoming connection requests.
        Throws:
        java.io.IOException - if the given address cannot be bound.
      • TLSTM

        public TLSTM​(TlsTmSecurityCallback<java.security.cert.X509Certificate> securityCallback,
                     TlsAddress serverAddress,
                     CounterSupport counterSupport)
              throws java.io.IOException
        Creates a TLS transport mapping that binds to the given address (interface) on the local host.
        Parameters:
        securityCallback - a security name callback to resolve X509 certificates to tmSecurityNames.
        serverAddress - the TcpAddress instance that describes the server address to listen on incoming connection requests.
        counterSupport - The CounterSupport instance to be used to count events created by this TLSTM instance. To get a default instance, use CounterSupport.getInstance().
        Throws:
        java.io.IOException - if the given address cannot be bound.
    • Method Detail

      • getTlsMaxFragmentSize

        public int getTlsMaxFragmentSize()
        Gets the maximum fragment size of supported for this transport mapping when acting as TLS server.
        Returns:
        the maximum TLS fragment size as defined by RFC 6066 section 4.
      • setTlsMaxFragmentSize

        public void setTlsMaxFragmentSize​(int tlsMaxFragmentSize)
        Sets the maximum TLS fragment size that this transport mapping should support as server. There is no need to change that from the default TLS_MAX_FRAGMENT_SIZE unless, a new Java version allows to set the maximum fragment size to a lower value.
        Parameters:
        tlsMaxFragmentSize - a value as defined by RFC 6066 section 4.
        Since:
        3.0.5
      • getTlsProtocols

        @Deprecated
        public java.lang.String[] getTlsProtocols()
        Deprecated.
        Gets the TLS protocols supported by this transport mapping.
        Returns:
        an array of TLS protocol (version) names supported by the SunJSSE provider.
      • setTlsProtocols

        @Deprecated
        public void setTlsProtocols​(java.lang.String[] tlsProtocols)
        Deprecated.
        Sets the TLS protocols/versions that TLSTM should use during handshake. The default is defined by DEFAULT_TLSTM_PROTOCOLS.
        Parameters:
        tlsProtocols - an array of TLS protocol (version) names supported by the SunJSSE provider. The order in the array defines which protocol is tried during handshake first.
        Since:
        2.0.3
      • setProtocolVersions

        public void setProtocolVersions​(java.lang.String[] protocolVersions)
        Sets the TLS protocols/versions that TLSTM should use during handshake. The default is defined by DEFAULT_TLSTM_PROTOCOLS.
        Specified by:
        setProtocolVersions in interface TlsTransportMappingConfig<java.security.cert.X509Certificate>
        Parameters:
        protocolVersions - an array of TLS protocol (version) names supported by the SunJSSE provider. The order in the array defines which protocol is tried during handshake first.
        Since:
        3.0
      • getProtocolVersions

        public java.lang.String[] getProtocolVersions()
        Description copied from interface: TlsTransportMappingConfig
        Return the (D)TLS protocol versions used by this transport mapping.
        Specified by:
        getProtocolVersions in interface TlsTransportMappingConfig<java.security.cert.X509Certificate>
        Returns:
        an array of SunJSSE TLS/DTLS provider (depending on the transport mapping type).
      • setLocalCertificateAlias

        public void setLocalCertificateAlias​(java.lang.String localCertificateAlias)
        Sets the certificate alias used for client and server authentication by this TLSTM. Setting this property to a value other than null filters out any certificates which are not in the chain of the given alias.
        Specified by:
        setLocalCertificateAlias in interface TlsTransportMappingConfig<java.security.cert.X509Certificate>
        Parameters:
        localCertificateAlias - a certificate alias which filters a single certification chain from the javax.net.ssl.keyStore key store to be used to authenticate this TLS transport mapping. If null no filtering appears, which could lead to more than a single chain available for authentication by the peer, which would violate the TLSTM standard requirements.
      • setSslEngineConfigurator

        public void setSslEngineConfigurator​(SSLEngineConfigurator sslEngineConfigurator)
        Sets the configurator for the SSLEngine internally used to run the TLS communication. This method should be called before any new connection is established that should use this configurator/configuration.
        Parameters:
        sslEngineConfigurator - a SSLEngineConfigurator instance like DefaultSSLEngineConfiguration.
        Since:
        3.0.5
      • setTrustManagerFactory

        public void setTrustManagerFactory​(TLSTMTrustManagerFactory trustManagerFactory)
        Set the TLSTM trust manager factory. Using a trust manager factory other than the default allows to add support for Java 1.7 X509ExtendedTrustManager.
        Parameters:
        trustManagerFactory - a X.509 trust manager factory implementing the interface TLSTMTrustManagerFactory.
        Since:
        2.0.3
      • listen

        public void listen()
                    throws java.io.IOException
        Listen for incoming and outgoing requests. If the serverEnabled member is false the server for incoming requests is not started. This starts the internal server thread that processes messages.
        Specified by:
        listen in interface TransportMapping<TcpAddress>
        Specified by:
        listen in class TcpTransportMapping<org.snmp4j.transport.TLSTM.SocketEntry>
        Throws:
        java.net.SocketException - when the transport is already listening for incoming/outgoing messages.
        java.io.IOException - if the listen port could not be bound to the server thread.
      • setThreadName

        public void setThreadName​(java.lang.String name)
        Sets the name of the listen thread for this UDP transport mapping. This method has no effect, if called before listen() has been called for this transport mapping.
        Parameters:
        name - the new thread name.
        Since:
        1.6
      • getThreadName

        public java.lang.String getThreadName()
        Returns the name of the listen thread.
        Returns:
        the thread name if in listening mode, otherwise null.
        Since:
        1.6
      • close

        public void close()
        Closes all open sockets and stops the internal server thread that processes messages.
        Specified by:
        close in interface java.lang.AutoCloseable
        Specified by:
        close in interface java.io.Closeable
        Specified by:
        close in interface TransportMapping<TcpAddress>
        Specified by:
        close in class TcpTransportMapping<org.snmp4j.transport.TLSTM.SocketEntry>
      • sendMessage

        public void sendMessage​(TcpAddress address,
                                byte[] message,
                                TransportStateReference tmStateReference,
                                long timeoutMillis,
                                int maxRetries)
                         throws java.io.IOException
        Sends a SNMP message to the supplied address.
        Specified by:
        sendMessage in interface TransportMapping<TcpAddress>
        Specified by:
        sendMessage in class TcpTransportMapping<org.snmp4j.transport.TLSTM.SocketEntry>
        Parameters:
        address - an TcpAddress. A ClassCastException is thrown if address is not a TcpAddress instance.
        message - byte[] the message to sent.
        tmStateReference - the (optional) transport model state reference as defined by RFC 5590 section 6.1.
        timeoutMillis - maximum number of milli seconds the connection creation might take (if connection based).
        maxRetries - maximum retries during connection creation.
        Throws:
        java.io.IOException - if an IO exception occurs while trying to send the message.
      • setConnectionTimeout

        public void setConnectionTimeout​(long connectionTimeout)
        Sets the connection timeout. This timeout specifies the time a connection may be idle before it is closed.
        Specified by:
        setConnectionTimeout in interface ConnectionOrientedTransportMapping<TcpAddress>
        Overrides:
        setConnectionTimeout in class TcpTransportMapping<org.snmp4j.transport.TLSTM.SocketEntry>
        Parameters:
        connectionTimeout - the idle timeout in milliseconds. A zero or negative value will disable any timeout and connections opened by this transport mapping will stay opened until they are explicitly closed.
      • isServerEnabled

        public boolean isServerEnabled()
        Checks whether a server for incoming requests is enabled.
        Returns:
        boolean
      • setServerEnabled

        public void setServerEnabled​(boolean serverEnabled)
        Sets whether a server for incoming requests should be created when the transport is set into listen state. Setting this value has no effect until the listen() method is called (if the transport is already listening, close() has to be called before).
        Parameters:
        serverEnabled - if true if the transport will listens for incoming requests after listen() has been called.
      • setMaxInboundMessageSize

        public void setMaxInboundMessageSize​(int maxInboundMessageSize)
        Sets the maximum buffer size for incoming requests. When SNMP packets are received that are longer than this maximum size, the messages will be silently dropped and the connection will be closed.
        Parameters:
        maxInboundMessageSize - the length of the inbound buffer in bytes.
      • isListening

        public boolean isListening()
        Description copied from interface: TransportMapping
        Returns true if the transport mapping is listening for incoming messages. For connection oriented transport mappings this is a prerequisite to be able to send SNMP messages. For connectionless transport mappings it is a prerequisite to be able to receive responses.
        Specified by:
        isListening in interface TransportMapping<TcpAddress>
        Returns:
        true if this transport mapping is listening for messages.
      • getListenAddress

        public TcpAddress getListenAddress()
        Description copied from interface: TransportMapping
        Returns the address that represents the actual incoming address this transport mapping uses to listen for incoming packets.
        Specified by:
        getListenAddress in interface TransportMapping<TcpAddress>
        Overrides:
        getListenAddress in class TcpTransportMapping<org.snmp4j.transport.TLSTM.SocketEntry>
        Returns:
        the address for incoming packets or null this transport mapping is not configured to listen for incoming packets.