YumaPro Security Guide

Secure management. Shared policy. Operational visibility.

This whitepaper explains the security architecture of YumaPro SDK for readers familiar with networking and security. It connects transport protection, identity, admission control, and YANG authorization across NETCONF, RESTCONF, and the other management interfaces. It is an architectural guide rather than an installation tutorial.

Security Built Around the Data Model

YumaPro combines encrypted management channels with an integrated RFC 8341 Network Configuration Access Control Model (NACM). A management identity can be granted access to a particular YANG subtree, operation, or notification without granting general access to the device. This makes policy meaningful at the level where administrators actually work: interfaces, routing configuration, services, and operational state.

The architecture has four cooperating layers. A transport authenticates the peer and protects traffic. Admission control decides whether the identified user and protocol may establish a management session. NACM determines what that session may read, change, execute, and receive. Logging and monitoring provide evidence of the resulting decisions. Password handling separately protects supported hashed password fields when they are written.

The principal security controls at a glance. Password handling applies to supported hashed fields; it is not a session admission stage.

Different secure transports converge on an identified management session and shared YANG authorization. Adapter and internal socket trust are part of the deployment boundary.

The benefit is consistency across management tools. A NETCONF automation client and a RESTCONF application working as the same user encounter policy on the same managed data. Changing protocol does not itself grant permission to edit a protected subtree. Equivalent identities, enabled enforcement, and correct adapter integration are essential to this property.

Security Capabilities at a Glance

Capability	Security value	Control boundary
NETCONF over SSH	Encrypted transport with SSH authentication and authenticated user identity	SSH service and NETCONF subsystem
NETCONF over TLS	TLS 1.3 support, X.509 peer verification, certificate-to-user mapping	Native netconfd-pro TLS listener
RESTCONF over HTTPS	TLS protection and web authentication before YANG request processing	Web server and RESTCONF gateway
NACM (RFC 8341)	Integrated read, write, operation, action, and notification authorization	Shared server access-control engine
Admission and resource controls	Protocol selection, allowed users, concurrent-session limits and timeouts	Server session management
Live security operations	Policy edits, selected server settings, certificate/key reload and diagnostics	YANG configuration and protected RPCs

NETCONF Transport Security

SSH and Authenticated Management Identity

NETCONF over SSH uses the SSH service to establish the secure channel and user identity. Password and public-key authentication are configured at that service; host-key verification belongs to the client. The NETCONF subsystem passes the authenticated identity to netconfd-pro. NACM then decides the permissions of that user independently of the SSH authentication method.

This division lets deployments use their existing SSH account and key management while keeping device-data permissions in YANG. SSH access to a host is not automatically a reason to permit management access: the server's --allowed-user list can restrict NETCONF admission further. SSH service settings, host keys, and the subsystem connection must be administered as part of the security boundary. See the SSH configuration reference.

TLS 1.3 and Mutual X.509 Authentication

netconfd-pro supports TLS 1.3 for native NETCONF over TLS when built and linked with a TLS 1.3-capable OpenSSL library. The server uses a negotiating TLS method on current OpenSSL builds, and explicitly recognizes TLS 1.2 and TLS 1.3. The listener is enabled with --with-netconf-tls; its default TCP port is 6513. The product must include OpenSSL support (WITH_OPENSSL=1).

The normal operating mode verifies the client certificate against the configured trust store. A successful certificate check is followed by certificate-to-user mapping and admission checks. OpenSSL is configured with SSL_VERIFY_PEER | SSL_VERIFY_FAIL_IF_NO_PEER_CERT, and a post-handshake check also rejects a missing peer certificate.

The CLI parameter setting --tls-v1.3-only='true` raises the listener's minimum TLS version to 1.3. With the default settings on current OpenSSL builds, the listener sets TLS 1.2 as the minimum during negotiation, so deprecated versions fail the handshake. A separate post-handshake check currently admits only TLS 1.2 and TLS 1.3. This is a server listener setting, not a RESTCONF HTTPS or yangcli-pro setting.

TLS 1.3 provides authenticated encryption and a modern handshake. Its availability does not by itself prove that a particular session negotiated it. The server's debug2 log reports the actual TLS version and cipher. The effective capabilities depend on the linked library and its policy.

Encryption, peer authentication, identity mapping, and authorization each answer a different security question. NETCONF does not use TLS early data.

Certificates, Identity, and Revocation

The server exposes certificate, private-key, and trust-store locations as --netconf-tls-certificate, --netconf-tls-key, and --netconf-tls-trust-store. Trust stores can be files or directories. Private keys and trust-store administration remain operating-system responsibilities; these configuration parameters do not encrypt keys at rest.

Identity selection has a deliberate order. Static --cert-usermap entries are checked first, followed by the YANG cert-to-name entries in yumaworks-cert-usermap.yang. The latter adapts the standardized ietf-x509-cert-to-name grouping. If neither yields a mapping, --tls-autosan-mode can use a valid Subject Alternative Name as a username. Explicit mappings provide control over the relationship between certificate issuance and management roles. Automatic SAN mapping requires the issuing CA to control those identity values appropriately.

The --tls-crl-mode parameter selects no checking (off, the default), client-certificate checking (client), or client and CA checking (ca). The trust material must supply the required CRLs. The --tls-crl-missing-ok parameter weakens that check: the schema and verification callback also allow it to tolerate not-yet-valid or expired CRLs, beyond the missing-CRL case suggested by its name. A policy requiring revocation checks should keep that exception disabled.

Two compatibility/debug controls change the authentication guarantee.

• --insecure-ok allows certificate verification failures to be ignored in server debug builds.

• --tls-common-auth disables client-certificate authentication and assigns the session the username admin.

The latter is explicitly documented by its YANG schema as violating the NETCONF mutual-authentication requirement.

Cipher configuration has an important boundary. The --tls-cipherlist parameter is passed to OpenSSL's SSL_CTX_set_cipher_list and controls TLS 1.2 and earlier cipher selection. It does not select TLS 1.3 cipher suites.

See the OpenSSL cipher API reference in Standards and Implementation References.

The yangcli-pro TLS Client

The yangcli-pro client selects native NETCONF TLS with --transport='tls'. Its shared manager connection code loads the client certificate and key, verifies the server certificate chain, and uses a negotiating TLS client method on current OpenSSL builds. This provides TLS 1.3 capability when the linked library supports it.

The new --tls-strict='true' parameter opts in to RFC 9918-oriented client checks. It establishes TLS 1.2 as the minimum protocol version and verifies the certificate identity against ssl-server-name or, for an ordinary outbound connection, the configured server address. DNS references match a subjectAltName DNS entry; IP references match an iPAddress entry. Common Name fallback and partial wildcards are excluded. The read-write $$tls-strict and $$ssl-server-name system variables can change these settings for later connections in the same client process.

RFC 9918 Implementation Assessment

RFC 9918 updates NETCONF over TLS by retaining mutually authenticated TLS 1.2, preferring TLS 1.3 where implemented, prohibiting early data, and carrying forward NETCONF certificate and peer-identity requirements. The current implementation provides the following supporting behavior for native NETCONF TLS. These controls concern the netconfd-pro listener and yangcli-pro client; RESTCONF HTTPS is governed by its web-server TLS policy.

RFC 9918 area	netconfd-pro	yangcli-pro
Mutual TLS 1.2	Requires and validates a client certificate in normal mode, maps it to a username, and defaults to a TLS 1.2 minimum	Loads and validates the client certificate/key and server chain; strict mode sets a TLS 1.2 minimum
TLS 1.3 capability and preference	Uses a negotiating OpenSSL method, accepts TLS 1.3, and offers an optional TLS 1.3 minimum	Uses a negotiating OpenSSL method; regression coverage verifies TLS 1.3 preference when both peers offer it
Early-data prohibition	Sets the TLS 1.3 maximum early-data allowance to zero before accepting sessions	Sets the TLS 1.3 maximum early-data allowance to zero and uses the ordinary handshake and I/O path
Mandatory TLS 1.3 cipher	Uses the linked OpenSSL TLS 1.3 suite policy	Regression coverage negotiates TLS_AES_128_GCM_SHA256 when TLS 1.3 is available
Peer identity and authentication	Applies trust validation, certificate-to-name mapping, SAN options, and allowed-user checks before NETCONF admission	Strict mode verifies the expected DNS name or IP address, including an explicitly configured Call Home identity
NETCONF transport behavior	Starts NETCONF processing after the authenticated TLS session is admitted	Uses the existing manager transport and NETCONF framing path after the authenticated handshake

Call Home and Controlled Reachability

IETF Call Home lets netconfd-pro initiate the TCP connection to a configured manager while retaining the NETCONF client/server roles. YumaPro supports NETCONF Call Home over SSH and TLS, providing managed reachability for devices behind firewalls and a basis for discovery and bootstrap. Outbound connection establishment does not replace peer authentication or NACM.

Retry and reconnect settings govern connection behavior, and yumaworks-callhome.yang provides YANG configuration of manager endpoints. With strict client validation, the manager recognizes the intended device identity from --ssl-server-name parameter. An explicit value is required for strict TLS Call Home because an incoming network address is not used as the trusted reference identity. See Call Home reference.

RESTCONF Security and the HTTPS Boundary

RESTCONF shares the YANG datastore and access-control infrastructure with NETCONF, while HTTPS is terminated by the deployment's web server. The Apache or NGINX configuration therefore owns the HTTPS certificate, private key, accepted TLS versions, cipher policy, and web authentication mechanism. TLS 1.3 for RESTCONF depends on that web stack and its configuration, not on netconf-tls-* or tls-v1.3-only in netconfd-pro.

The RESTCONF gateway normally obtains the authenticated username from REMOTE_USER. If that value is absent, the gateway tries BASE64_USER for Apache deployments; if that value is absent or cannot be decoded, it falls back to the literal restconf account. That fail-open fallback is security-sensitive: deployments must authenticate and protect the fallback account, configure the web server to establish the identity from authentication, and protect the gateway/backend connection against untrusted callers. A public HTTP header supplied by a client must not be treated as a trusted management identity. The supplied installation material illustrates web-server authentication; it is not a claim that all possible identity providers are implemented by netconfd-pro.

Once admitted, a RESTCONF request encounters authorization on the managed YANG resources. Read filtering, write permissions, RPC/action permissions, and event access continue to matter after HTTPS authentication succeeds. This applies to RESTCONF data operations and YANG Patch as well as ordinary resource retrieval. A RESTCONF error is represented in HTTP/RESTCONF terms; a NETCONF request expresses a corresponding denial as a protocol error. Read-denied content is filtered rather than disclosed merely because a request was authenticated.

RESTCONF event streams extend the same security discussion to ongoing data delivery. Authentication of a subscription does not grant blanket access to all events or their data. Monitoring and stream exposure must be covered by the intended NACM policy. See RESTCONF operation and TLS deployment for deployment details.

Integrated NACM Across Management Protocols

A Complete Authorization Model

YumaPro implements the integrated NACM model defined by RFC 8341, including the YANG 1.1 additions for actions and notifications tied to data nodes. The authorization surface covers reading data, creating/updating/deleting configuration, executing RPCs and actions, and receiving notifications. The standard ietf-netconf-acm model makes the policy itself manageable through YANG, rather than embedding permissions in each client application. Here, complete describes this authorization scope; it is not a claim of independent certification or of enforcement on every trusted internal API.

Policy combines usernames, group membership, ordered rule-lists, ordered rules, and operation-specific defaults. A rule can select a module, a data path, an RPC, or a notification and grant or deny matching access operations. Data-path rules also provide the instance context required by YANG 1.1. The first applicable matching rule determines the decision. Rule order is therefore part of the policy, not just presentation.

Local groups are configured in /nacm/groups. External group membership can be supplied through the NACM external-groups callback.

The normal NACM policy path. Recovery users, disabled enforcement, and trusted internal operations are exceptions discussed below.

Defaults and Schema Protection

The server defaults to --access-control='enforcing'. Standard NACM defaults permit reads, deny writes, and permit execution, subject to schema protection and explicit rules. An all-deny policy can be built with read-default, write-default, and exec-default set to deny. Such a policy needs intentional grants for the desired discovery, schema, monitoring, and management operations so clients can function.

• The nacm:default-deny-write extension protects configuration from default write access.

• The nacm:default-deny-all provides default protection for all relevant access.

These extensions do not prevent an explicit matching permit rule from allowing access. In particular, default-deny-write does not by itself hide readable data. The NACM configuration container is itself marked default-deny-all, helping protect the policy from ordinary users.

YumaPro also provides the ncx:user-write extension to restrict which user write operations a modeled object permits. These restrictions apply independently of NACM, including when NACM is disabled. They are useful for objects whose lifecycle permits creation and deletion but not later modification. YumaWorks module-tag rules extend policy selection to tagged collections of modules; this is a product extension rather than standard RFC 8341 syntax.

One Identity, Several Protocols

NETCONF and RESTCONF reach the shared agent and datastore, so a policy on a YANG resource can serve both interfaces. The same design extends to the supported gNMI, YumaWorks gRPC, SNMP, and YP-SHELL integrations. Their transport and identity mechanisms differ; enabling a protocol is not proof that its front end is securely authenticated.

Interface	Identity/transport boundary	Authorization interpretation
NETCONF	SSH identity or native TLS certificate mapping	YANG read/write, RPC/action, and notification permissions
RESTCONF	HTTPS and authenticated web-server username	Shared resource policy after trusted gateway handoff
gNMI / gRPC	Protocol adapter credentials and secure transport	Stock adapters authorize requests as their OS process account; request authentication is not forwarded to NACM
SNMP	Net-SNMP authentication, including SNMPv3 options	YumaPro uses NACM; its SNMP integration documents disabling VACM
YP-SHELL	Authenticated CLI session	Shared YANG operations and data permissions
DB-API / internal instrumentation	Trusted application or subsystem	Internal access can bypass NACM unless enforcement is requested

Transport Guarantees and Trusted Exceptions

SNMPv3 authentication and privacy protect the SNMP transport; NACM protects the managed data. Community-based SNMP versions do not provide the same transport guarantees. The VACM guidance applies to the YumaPro integration, not as a general recommendation for unrelated Net-SNMP deployments.

Recovery users configured with superuser are exempt from NACM. They should be reserved for controlled recovery and policy repair. They also bypass the allowed-user list, although protocol and resource admission controls still matter. access-control modes other than enforcing and enable-nacm=false change the effective policy guarantee. Product integrators must separately review custom access-control callbacks and trusted DB-API access. The external ACM model replaces the built-in policy; its documented contract requires the vendor callbacks, otherwise access is allowed by default. Selecting that model is therefore a substantive change to the security implementation, not an additional NACM rule source. Session hooks provide another integration point for product-specific session handling. These trust boundaries must remain visible in a multi-protocol security design. See the ACM integration contract and system callbacks.

Managing Security Through CLI and YANG

Configuration With an Operational Lifecycle

CLI parameters and the startup config (e.f. set with --startup parameter; default: netconfd-pro.conf) establish the boot configuration, unless the --no-startup parameter is used.

The yumaworks-server.yang model exposes server parameters through YANG, and a documented subset takes effect immediately. Other parameter edits are for the next restart. A live YANG edit does not imply that every transport setting changes on existing sessions.

Refer to the Session Admission Control section for details on restricting management sessions in various ways.

The distinction between available, initialized, and admitted protocols is useful operationally. Runtime protocol control can change admissions without a reboot, but it cannot add a protocol omitted from the executable. Admission settings also include total, per-user, and CLI concurrent-session limits. Timeouts bound waiting and idle sessions; they complement transport and front-end resource controls rather than constituting a complete denial-of-service defense.

The following is a policy sketch, not a complete deployable configuration. Certificate identities, NACM roles, credentials, and platform configuration are intentionally deployment-specific:

netconfd-pro {
    with-netconf-tls true
    tls-v1.3-only true
    tls-common-auth false
    insecure-ok false
    access-control enforcing
    tls-debug false
}

Certificate Rotation Without Replacing Policy

The reload-netconf-tls-keypair function in yumaworks-server.yang loads the configured certificate and key and verifies the pair. It allows rotation without disrupting existing NETCONF TLS sessions; newly established sessions use the resulting listener credentials. It does not reload RESTCONF's web-server certificate or automatically rotate trust anchors and CRLs.

This RPC is protected by nacm:default-deny-all. Its success contract is unusually important: inspect all three output status leafs, cert-status, key-status, and verify-status. All must be zero. A reply without an rpc-error is insufficient, and the operation does not attempt rollback if a stage fails. Failed replacement can leave new native TLS connections unavailable until the key material is corrected. Treat this as a controlled security operation with credential validation and recovery planning, not a transactional key-store API.

Protecting Sensitive Modeled Values

YumaPro recognizes iana-crypt-hash password data and the OpenConfig openconfig-hashed-value extension. Cleartext inputs to supported hashed password fields are converted to a stored hash; the default crypt-hash conversion uses SHA-512 and the default minimum length is eight. These are product defaults, not a declaration that they meet every organization's password policy.

The legacy ncx:password extension is deprecated and does not provide complete disclosure protection. Use a supported hashed representation and NACM protection for sensitive fields. Hashing does not encrypt arbitrary configuration at rest, protect private-key files, or remove the need to secure logs and backups. Debug builds with raw input tracing can expose incoming cleartext before conversion. The password handling reference explains these distinctions.

Security Visibility and Diagnosis

Observe the Layer That Made the Decision

Security diagnosis is most effective when evidence follows the connection through its layers. A TLS failure, an unknown certificate mapping, rejected admission, and an NACM denial are different outcomes and need different corrective actions. Granting broader NACM rights cannot repair an untrusted certificate; weakening TLS cannot correct a rule that selects the wrong YANG path.

Question	Evidence	Interpretation
Was the protected channel established?	SSH/web-server logs; native TLS version and cipher at debug2	Distinguish negotiation and credential errors from later denials
Which identity was established?	TLS mapping diagnostics; authenticated gateway/adapter identity	Check the resulting username before changing group policy
Was the session admitted?	Protocol state, allowed-user and concurrent-session diagnostics	Successful authentication can still be refused admission
Which rule decided access?	agt_acm permit/deny messages; matched rule details at debug2	Check rule ordering, groups, namespace, path and access operation
What was denied over time?	NACM counters and selected audit events	Correlate user, operation, affected data and time

tls-debug enables additional native TLS diagnostics in combination with log-level: shared cipher detail is available at debug3 and cipher lists at debug4. Normal session information includes the negotiated version and cipher at debug2. Debug verbosity should be bounded to the investigation and logs handled as sensitive operational data.

The NACM model exposes denied-operations, denied-data-writes, and denied-notifications. These counters do not provide a per-leaf denied-read ledger. Read-denied values can simply disappear from results, and the standard logs need not show a message when the read default decides access. An empty or reduced retrieval is therefore a reason to inspect the user's policy, not proof that the data is absent from the datastore.

The independent audit log can record configuration activity and selected access denials. audit-log-events includes edit-running, acm-write-error, and acm-exec-error. audit-log selects an explicit log path; FHS operation can create the default log unless disabled. Choose retention, file permissions, and off-device collection for the deployment. The presence of an audit channel is not a claim of tamper-evident storage.

Standards and Implementation References

The security design is strongest when transport settings, identity mapping, NACM, and operational evidence are reviewed together. The following sources anchor the capability and limitation statements in this edition.

• IETF, RFC 8341: Network Configuration Access Control Model.

• IETF, RFC 7589: NETCONF over TLS with mutual X.509 authentication.

• IETF, RFC 9918: NETCONF over TLS update.

• OpenSSL, Cipher-list and TLS 1.3 cipher-suite configuration.

• NETCONF TLS reference, NACM reference, and admission controls.

• SNMP security and server CLI reference.