Skip to content

Commit fec6766

Browse files
ubkrubkr
authored
Merge pull request #687 from onvif/fix/snmpv3-spec-edits
SNMPv3 spec edits for readability
2 parents 999f119 + eafeab1 commit fec6766

File tree

3 files changed

+94
-115
lines changed

3 files changed

+94
-115
lines changed

‎doc/Core.xml‎

Lines changed: 44 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -5372,28 +5372,22 @@ onvif://www.onvif.org/name/ARV-453
53725372
</section>
53735373

53745374
<section xml:id="s.snmp_extension">
5375-
<title>SNMP Configuration (Optional)</title>
5376-
<para>
5377-
This section defines an optional extension to the Device Management Service for supporting Simple Network Management Protocol version 3 (SNMPv3) as specified in [RFC 3410] and related standards. Devices supporting this extension shall indicate this capability via the <literal>SNMP</literal> flag in the <literal>DeviceServiceCapabilities</literal> (see Section <xref linkend="_Ref468447902"/>).
5378-
</para>
5379-
<para>
5380-
Only SNMPv3 is within the scope of this extension.
5381-
</para>
5375+
<title>SNMP Configuration</title>
5376+
<para>This section defines a feature extension to the Device Management Service for supporting
5377+
Simple Network Management Protocol as specified in [RFC 3410] and related standards. Devices
5378+
supporting this extension shall indicate their capability via the SNMP flag in the
5379+
DeviceServiceCapabilities. (see Section <xref linkend="_Ref468447902"/>). </para>
5380+
<para>Only SNMPv3 is within the scope of this extension. </para>
53825381
<section xml:id="s.snmp_service_control">
53835382
<title>SNMP Service Control</title>
5384-
<para>
5385-
Devices supporting this extension shall provide the following operations for managing the SNMP service itself.
5386-
</para>
5387-
<para>
5388-
The SNMP service shall be disabled by default unless explicitly enabled by a Client. When disabled, the Device should not listen on the SNMP port, and attempts to query via SNMP should fail.
5389-
</para>
5383+
<para>The SNMP service shall be disabled by default. When enabled, the Device shall start to
5384+
listen for commands and queries on the configured SNMP port. </para>
53905385

53915386
<section xml:id="op.GetSNMPConfiguration">
53925387
<title>GetSNMPConfiguration</title>
5393-
<para>
5394-
This operation is used by a Client to retrieve the current SNMP service status and global configuration parameters from a Device.
5395-
A Device supporting the SNMP extension shall implement this command.
5396-
</para>
5388+
<para>This operation allows the client to retrieve the current SNMP service status along
5389+
with its configuration parameters. A device that signals support for SNMP via the SNMP
5390+
capability shall implement this command.</para>
53975391
<variablelist role="op">
53985392
<varlistentry>
53995393
<term>request</term>
@@ -5427,10 +5421,10 @@ onvif://www.onvif.org/name/ARV-453
54275421
<row>
54285422
<entry>EngineID</entry>
54295423
<entry>xs:hexBinary</entry>
5430-
<entry>
5431-
The SNMP Engine ID of the Device, as defined in [RFC 3411]. This value is typically read-only after initial configuration or discovery by the SNMP engine itself.
5432-
The Device <emphasis role="bold">should</emphasis> persist this EngineID across reboots.
5433-
</entry>
5424+
<entry> The SNMP Engine ID of the Device, as defined in [RFC 3411]. This value
5425+
is typically read-only after initial configuration or discovery by the
5426+
SNMP engine itself. The Device should persist this EngineID across
5427+
reboots. </entry>
54345428
</row>
54355429
<row>
54365430
<entry>ListeningPort</entry>
@@ -5459,18 +5453,18 @@ onvif://www.onvif.org/name/ARV-453
54595453

54605454
<section xml:id="op.SetSNMPConfiguration">
54615455
<title>SetSNMPConfiguration</title>
5462-
<para>
5463-
This operation is used by a Client to enable or disable the SNMP service and to configure its global parameters.
5464-
Additionally, this operation can optionally create an initial SNMP user during service setup (only SNMPv3 users are supported).
5465-
A Device supporting the SNMP extension shall implement this command.
5466-
</para>
5467-
<para>
5468-
Some parameters, like the <literal>EngineID</literal>, may not be settable by a Client after initial determination by the Device, or may only be settable under specific conditions (e.g., when the service is disabled). If an attempt is made to set a non-settable <literal>EngineID</literal>, the Device shall return a <literal>ter:SNMPEngineIDNotSettable</literal> fault.
5469-
If an optional parameter is not present in the request, the Device shall not change the current value of that parameter.
5470-
</para>
5471-
<para>
5472-
For initial user creation: If <literal>InitialUserName</literal> is provided, then <literal>SecurityLevel</literal> must also be provided. Depending on the <literal>SecurityLevel</literal>, additional authentication and privacy parameters may be required as specified in the parameter descriptions. The Device shall validate that all required parameters for the chosen security level are provided and return appropriate fault codes if the configuration is incomplete or invalid.
5473-
</para>
5456+
<para>This operation allows the client to enable or disable the SNMP service and to
5457+
configure its parameters. This operation can optionally create an initial SNMP user
5458+
during service setup (only SNMPv3 users are supported). A device that signals support
5459+
for SNMP via the SNMP capability shall implement this command. </para>
5460+
<para>Some parameters, like the EngineID may only allowed to be set when the service is
5461+
disabled, while returning an error otherwise. If an optional parameter is missing in the
5462+
request, the device shall retain the current value of that parameter. </para>
5463+
<para>The operation request may include SecurityLevel along with InitialUserName for initial
5464+
user creation. Depending on the type of SecurityLevel input, additional authentication
5465+
and privacy parameters shall be required as specified in the parameter descriptions. The
5466+
device shall validate required parameters for the chosen security level and returns
5467+
appropriate fault codes if the configuration is incomplete or invalid. </para>
54745468
<variablelist role="op">
54755469
<varlistentry>
54765470
<term>request</term>
@@ -5496,31 +5490,30 @@ onvif://www.onvif.org/name/ARV-453
54965490
<entry>Enabled</entry>
54975491
<entry>xs:boolean</entry>
54985492
<entry>optional</entry>
5499-
<entry>Enables or disables the SNMP service. If not provided, the current enabled state is maintained.</entry>
5493+
<entry>Enables or disables the SNMP service. If not provided, the current
5494+
state is maintained.</entry>
55005495
</row>
55015496
<row>
55025497
<entry>EngineID</entry>
55035498
<entry>xs:hexBinary</entry>
55045499
<entry>optional</entry>
5505-
<entry>
5506-
The SNMP Engine ID. The ability to set this <emphasis role="bold">may</emphasis> be restricted by the Device.
5507-
If not provided, the current EngineID is maintained.
5508-
</entry>
5500+
<entry>The SNMP Engine ID. The ability to set this <emphasis role="bold"
5501+
>may</emphasis> be restricted by the Device. If not provided, the
5502+
current EngineID is maintained. </entry>
55095503
</row>
55105504
<row>
55115505
<entry>ListeningPort</entry>
55125506
<entry>xs:unsignedInt</entry>
55135507
<entry>optional</entry>
5514-
<entry>
5515-
The UDP port number for the SNMP agent. If not provided, the current port is maintained.
5516-
Valid port range is typically 1-65535.
5517-
</entry>
5508+
<entry>The UDP port number for the SNMP agent. If not provided, the current
5509+
port is maintained. Valid port range is typically 1-65535. </entry>
55185510
</row>
55195511
<row>
55205512
<entry>InitialUserName</entry>
55215513
<entry>xs:string</entry>
55225514
<entry>optional</entry>
5523-
<entry>Username for the initial SNMP user. If provided, SecurityLevel must also be specified. Max length 32 octets per USM requirements.</entry>
5515+
<entry>Username for the initial SNMP user. If provided, SecurityLevel shall
5516+
also be included. Max length 32 octets per USM requirements.</entry>
55245517
</row>
55255518
<row>
55265519
<entry>SecurityLevel</entry>
@@ -5567,11 +5560,15 @@ onvif://www.onvif.org/name/ARV-453
55675560
<term>faults</term>
55685561
<listitem>
55695562
<para role="param">env:Sender - ter:InvalidArgVal - ter:InvalidSNMPPort</para>
5570-
<para role="text">The provided <literal>ListeningPort</literal> is outside the valid range or is otherwise unusable.</para>
5563+
<para role="text">The provided ListeningPort is outside the valid range or is
5564+
otherwise unusable.</para>
55715565
<para role="param">env:Sender - ter:InvalidArgVal - ter:InvalidSNMPEngineID</para>
5572-
<para role="text">The provided <literal>EngineID</literal> is malformed or invalid according to [RFC 3411].</para>
5573-
<para role="param">env:Receiver - ter:ActionNotSupported - ter:SNMPEngineIDNotSettable</para>
5574-
<para role="text">The Device does not allow the <literal>EngineID</literal> to be set via this command, or under the current conditions.</para>
5566+
<para role="text">The provided EngineID is malformed or invalid according to [RFC
5567+
3411].</para>
5568+
<para role="param">env:Receiver - ter:OperationProhibited -
5569+
ter:SNMPEngineIDNotSettable</para>
5570+
<para role="text">The Device does not allow the EngineID to be set via this command
5571+
under the current conditions.</para>
55755572
<para role="param">env:Sender - ter:InvalidArgVal - ter:SNMPInitialUserIncomplete</para>
55765573
<para role="text">Initial user configuration is incomplete (missing required fields for specified SecurityLevel).</para>
55775574
<para role="param">env:Sender - ter:InvalidArgVal - ter:SNMPInvalidInitialUser</para>

‎wsdl/ver10/device/wsdl/devicemgmt.wsdl‎

Lines changed: 50 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -2428,7 +2428,7 @@ IN NO EVENT WILL THE CORPORATION OR ITS MEMBERS OR THEIR AFFILIATES BE LIABLE FO
24282428
</xs:element>
24292429
<!--===============================-->
24302430
<!--===============================-->
2431-
<!-- SNMP Device Management Extension (Optional) - Only SNMPv3 is supported -->
2431+
<!-- SNMP Device Management Extension - Only SNMPv3 is supported -->
24322432
<xs:element name="GetSNMPConfiguration">
24332433
<xs:complexType>
24342434
<xs:sequence/>
@@ -2437,28 +2437,14 @@ IN NO EVENT WILL THE CORPORATION OR ITS MEMBERS OR THEIR AFFILIATES BE LIABLE FO
24372437
<xs:element name="GetSNMPConfigurationResponse">
24382438
<xs:complexType>
24392439
<xs:sequence>
2440-
<xs:element name="Enabled" type="xs:boolean"/>
2441-
<xs:element name="EngineID" type="xs:string"/>
2442-
<xs:element name="ListeningPort" type="xs:int" minOccurs="0"/>
2443-
<xs:element name="Uptime" type="xs:duration" minOccurs="0"/>
2444-
<xs:element name="ErrorCounters" type="xs:string" minOccurs="0"/>
2445-
<xs:any namespace="##any" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
2440+
<xs:element name="SNMPConfiguration" type="tds:SNMPConfiguration" minOccurs="1"/>
24462441
</xs:sequence>
24472442
</xs:complexType>
24482443
</xs:element>
24492444
<xs:element name="SetSNMPConfiguration">
24502445
<xs:complexType>
24512446
<xs:sequence>
2452-
<xs:element name="Enabled" type="xs:boolean" minOccurs="0"/>
2453-
<xs:element name="EngineID" type="xs:hexBinary" minOccurs="0"/>
2454-
<xs:element name="ListeningPort" type="xs:int" minOccurs="0"/>
2455-
<xs:element name="InitialUserName" type="xs:string" minOccurs="0"/>
2456-
<xs:element name="SecurityLevel" type="tt:SNMPSecurityLevel" minOccurs="0"/>
2457-
<xs:element name="AuthenticationProtocol" type="tt:SNMPAuthenticationProtocol" minOccurs="0"/>
2458-
<xs:element name="AuthenticationKey" type="tt:BinaryData" minOccurs="0"/>
2459-
<xs:element name="PrivacyProtocol" type="tt:SNMPPrivacyProtocol" minOccurs="0"/>
2460-
<xs:element name="PrivacyKey" type="tt:BinaryData" minOccurs="0"/>
2461-
<xs:any namespace="##any" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
2447+
<xs:element name="SNMPConfiguration" type="tds:SNMPConfiguration" minOccurs="1"/>
24622448
</xs:sequence>
24632449
</xs:complexType>
24642450
</xs:element>
@@ -2467,6 +2453,53 @@ IN NO EVENT WILL THE CORPORATION OR ITS MEMBERS OR THEIR AFFILIATES BE LIABLE FO
24672453
<xs:sequence/>
24682454
</xs:complexType>
24692455
</xs:element>
2456+
2457+
<!--=========================================-->
2458+
<!-- Begin, SNMPConfiguration -->
2459+
<!--=========================================-->
2460+
<xs:simpleType name="SNMPSecurityLevel">
2461+
<xs:restriction base="xs:string">
2462+
<xs:enumeration value="noAuthNoPriv"/>
2463+
<xs:enumeration value="authNoPriv"/>
2464+
<xs:enumeration value="authPriv"/>
2465+
</xs:restriction>
2466+
</xs:simpleType>
2467+
2468+
<xs:simpleType name="SNMPAuthenticationProtocol">
2469+
<xs:restriction base="xs:string">
2470+
<xs:enumeration value="HMAC_SHA_256"/> <!-- usmHMACSHA256AuthProtocol -->
2471+
<xs:enumeration value="HMAC_SHA_384"/> <!-- usmHMACSHA384AuthProtocol -->
2472+
<xs:enumeration value="HMAC_SHA_512"/> <!-- usmHMACSHA512AuthProtocol -->
2473+
</xs:restriction>
2474+
</xs:simpleType>
2475+
2476+
<xs:simpleType name="SNMPPrivacyProtocol">
2477+
<xs:restriction base="xs:string">
2478+
<xs:enumeration value="CFB_AES_128"/> <!-- usmAesCfb128PrivProtocol -->
2479+
<xs:enumeration value="CFB_AES_192"/> <!-- usmAesCfb192PrivProtocol (check OID) -->
2480+
<xs:enumeration value="CFB_AES_256"/> <!-- usmAesCfb256PrivProtocol (check OID) -->
2481+
</xs:restriction>
2482+
</xs:simpleType>
2483+
2484+
<xs:complexType name="SNMPConfiguration">
2485+
<xs:sequence>
2486+
<xs:element name="Enabled" type="xs:boolean" minOccurs="0"/>
2487+
<xs:element name="EngineID" type="xs:hexBinary" minOccurs="0"/>
2488+
<xs:element name="ListeningPort" type="xs:unsignedInt" minOccurs="0"/>
2489+
<xs:element name="InitialUserName" type="xs:string" minOccurs="0"/>
2490+
<xs:element name="SecurityLevel" type="xs:string" minOccurs="0"/>
2491+
<xs:element name="AuthenticationProtocol" type="xs:string" minOccurs="0"/>
2492+
<xs:element name="AuthenticationKey" type="tt:BinaryData" minOccurs="0"/>
2493+
<xs:element name="PrivacyProtocol" type="xs:string" minOccurs="0"/>
2494+
<xs:element name="PrivacyKey" type="tt:BinaryData" minOccurs="0"/>
2495+
<xs:any namespace="##any" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
2496+
</xs:sequence>
2497+
<xs:anyAttribute namespace="##any"/>
2498+
</xs:complexType>
2499+
2500+
<!--=========================================-->
2501+
<!-- End, SNMPConfiguration -->
2502+
<!--=========================================-->
24702503
<!--===============================-->
24712504
</xs:schema>
24722505
</wsdl:types>

‎wsdl/ver10/schema/onvif.xsd‎

Lines changed: 0 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -9218,55 +9218,4 @@ If RectangleOnly is not set to true, this parameter is required.
92189218
<xs:anyAttribute processContents="lax"/>
92199219
</xs:complexType>
92209220

9221-
<!--=========================================-->
9222-
<!-- Begin, SNMPConfiguration -->
9223-
<!--=========================================-->
9224-
<xs:simpleType name="SNMPSecurityLevel">
9225-
<xs:restriction base="xs:string">
9226-
<xs:enumeration value="noAuthNoPriv"/>
9227-
<xs:enumeration value="authNoPriv"/>
9228-
<xs:enumeration value="authPriv"/>
9229-
</xs:restriction>
9230-
</xs:simpleType>
9231-
9232-
<xs:simpleType name="SNMPAuthenticationProtocol">
9233-
<xs:restriction base="xs:string">
9234-
<xs:enumeration value="HMAC_SHA_256"/> <!-- usmHMACSHA256AuthProtocol -->
9235-
<xs:enumeration value="HMAC_SHA_384"/> <!-- usmHMACSHA384AuthProtocol -->
9236-
<xs:enumeration value="HMAC_SHA_512"/> <!-- usmHMACSHA512AuthProtocol -->
9237-
</xs:restriction>
9238-
</xs:simpleType>
9239-
9240-
<xs:simpleType name="SNMPPrivacyProtocol">
9241-
<xs:restriction base="xs:string">
9242-
<xs:enumeration value="CFB_AES_128"/> <!-- usmAesCfb128PrivProtocol -->
9243-
<xs:enumeration value="CFB_AES_192"/> <!-- usmAesCfb192PrivProtocol (check OID) -->
9244-
<xs:enumeration value="CFB_AES_256"/> <!-- usmAesCfb256PrivProtocol (check OID) -->
9245-
</xs:restriction>
9246-
</xs:simpleType>
9247-
9248-
<xs:complexType name="SNMPConfiguration">
9249-
<xs:sequence>
9250-
<xs:element name="Enabled" type="xs:boolean" minOccurs="0"/>
9251-
<xs:element name="EngineID" type="xs:hexBinary" minOccurs="0"/>
9252-
<xs:element name="ListeningPort" type="xs:unsignedInt" minOccurs="0"/>
9253-
<xs:element name="InitialUserName" type="xs:string" minOccurs="0"/>
9254-
<xs:element name="SecurityLevel" type="tt:SNMPSecurityLevel" minOccurs="0"/>
9255-
<xs:element name="AuthenticationProtocol" type="tt:SNMPAuthenticationProtocol" minOccurs="0"/>
9256-
<xs:element name="AuthenticationKey" type="tt:BinaryData" minOccurs="0"/>
9257-
<xs:element name="PrivacyProtocol" type="tt:SNMPPrivacyProtocol" minOccurs="0"/>
9258-
<xs:element name="PrivacyKey" type="tt:BinaryData" minOccurs="0"/>
9259-
<xs:any namespace="##any" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
9260-
</xs:sequence>
9261-
<xs:anyAttribute namespace="##any"/>
9262-
</xs:complexType>
9263-
9264-
9265-
9266-
9267-
<!--=========================================-->
9268-
<!-- End, SNMPConfiguration -->
9269-
<!--=========================================-->
9270-
9271-
92729221
</xs:schema>

0 commit comments

Comments
 (0)