Cisco MASA Service

Table 1. Feature History Table

Feature Name

Release Information

Feature Description

Extend Device Ownership

Release 7.10.1

Your router can now run in a dual-ownership mode wherein you can securely migrate the operating system from Cisco IOS XR to third-party software such as SONiC. You can only install the signed SONiC image authorized by Cisco using an ownership voucher (OV) and authenticated variables (AV) on the router. This authorization prevents tampering with the software using unauthorized third-party images.

Cisco MASA Service

IOS XR 7.8.1

The Cisco Manufacturer Authorized Signing Authority (MASA) service creates ownership vouchers (OVs) for a Cisco IOS XR router. These OVs along with the owner certificate (OC) certify that the router belongs to a given customer.

Use cases where OVs and OCs are required include secure ZTP workflows and securely booting up your device on a 5G cell site over a third-party ethernet service.

You can use the MASA service to download, and view logging and audit of OVs for the routers you own.

This service also enables Cisco’s Account teams to assign the serial number of a device to customers and view details of the logging, verification, and audit of OVs.

Key Terms and Concepts

Authentication Flow: The purpose of the Authentication flow is to identify and authenticate the router when it boots up. During this flow, the router also checks if the network can be trusted. The router does this by:

  • validating the OV it received during the bootstrapping process and

  • verifying the signature on the onboarding information with the owner certificate it received during the bootstrapping process.

The workflow involves the router booting to dynamically obtain the OV from MASA via the customer's staging or management servers

MASA Service: There are many services that require the ownership of the router to be authenticated, so it can be trusted by the network. MASA is a service run by Cisco to create and log OVs that are then used to validate the ownership of the router.

Owner Certificate: The OC is an X.509 certificate [RFC5280] that is used to identify an owner, for example, an organization. The OC can be signed by any certificate authority (CA).

The OC is used by a router to verify the CA signature using the public key that is also in the owner certificate.

The OC structure must contain the owner certificate itself, as well as all intermediate certificates leading to the "pinned-domain-cert" (PDC) certificate specified in the ownership voucher.

Ownership Voucher: The ownership voucher (OV) [RFC8366] is used to securely identify the router's owner, as known to the manufacturer. The ownership voucher is signed by the device's manufacturer.

The OV is used to verify that the owner certificate has a chain of trust leading to the trusted certificate (PDC) included in the ownership voucher.

pinned-domain-cert: The PDC field present in the OV typically pins a domain certificate, such as the certificate of a domain CA.

Why Do I Need Cisco MASA?

The Cisco MASA service securely authorizes ownership of a router so that the router can then establish a secure connection to the router owner's (your) network infrastructure.

The establishment of the ownership of the router is achieved through an authentication workflow that on successful completion generates an ownership voucher (OV). The primary purpose of the OV is to securely convey a certificate—the "pinned-domain-cert" (PDC), that the router can then use to authenticate subsequent interactions with the network, for example, secure bootstrapping. Establishing ownership is important to the bootstrapping mechanisms so that the router can authenticate the network that is trying to take control of it.

Use Cases for Ownership Vouchers

The following use cases show examples where ownership vouchers apply:

  • Secure Zero Touch Provisioning (ZTP) Bootstrapping

    Secure ZTP requires the ability to securely bootstrap a router over an untrusted network. This requires the ability of MASA to provide an OV to the router. The OV is used to authenticate the router to ensure connectivity of the router to the network.

    For more information on Secure ZTP, see the Secure Zero Touch Provisioning chapter in the System Setup and Software Installation Guide for NCS 540 Series Routers.


    Note

    MASA can help generate OVs for Cisco Routers only.

  • Application Hosting on XR

    Cisco IOS XR’s Application Hosting (App Hosting) capability provides an IOS XR container on the router. This allows an application that augments XR features to be deployed. These applications can fall in one of the following categories:

    • Customer Apps—developed by Cisco’s customers and cannot be signed by Cisco.

    • Partner Apps—developed by partners and are signed by Cisco.

    • Cisco App—developed by Cisco and signed by Cisco.

    You can use MASA in conjunction with the Golden ISO Tool (gisobuild.py) to provide the OVs to enable secure workflows for onboarding third party RPMs on router running Cisco IOS XR.

    For more information, see the Application Hosting Guide for Cisco 8000 Series Routers.

  • Extend Device Ownership

    Use the extended ownership voucher to move the state of Cisco Trusted Platform Module (TPM) and platform keys to allow customized control on the router. With this voucher, you can securely transfer the control of the Unified Extensible Firmware Interface (UEFI) database ownership from Cisco generic mode to an extended mode, owned by both Cisco and the Customer to securely install third-party images.

    For more information about configuring the extended device ownership to migrate from Cisco IOS XR to SONiC software, see the Migrate from Cisco IOS XR to SONiC on Cisco 8000 Series Routers.

  • Deploy Router Using BootZ

    Bootz is a secure zero-touch provisioning solution for data centers that automates the setup of network devices while ensuring robust security. It enables devices to connect and authenticate with the Bootz server, safeguarding the onboarding process against unauthorized access and cyber threats, streamlining remote device configuration without compromising safety.

    Bootz uses a MASA to issue OVs that authenticate network devices during zero-touch provisioning.

    For more information on BootZ, see the Deploying Router Using Bootz Protocol chapter in the System Setup and Software Installation Guide for Cisco 8000 Series Routers.

Authentication Flow

The following figure is a high-level overview of different components involved in the authentication flow.

Figure 1. Components of the Authentication Flow

You can interact with the MASA Server web application through the ZTP Server to request, manage, and download the OVs for your routers.

The Zero Touch Provisioning (ZTP) server is to used to make a REST API call to the MASA Server.

The MASA Server authenticates the user, and on successful validation, generates the OVs.

The following figure illustrates the typical workflow to obtain the OVs.

Figure 2. Workflow to Obtain Ownership Vouchers

Interacting with the MASA Server

There are two ways to interact with the MASA server:

  • through Web Application

  • through REST API calls

Entities

The following entities interact with the MASA Server:

  • Organization—A group in MASA specific to a Cisco customer. Data and access for each Organization is available to members of that group only.

  • Admin—One or more initially-designated member(s) of an Organization who can invite other members into that organization in MASA, set access restrictions, and adjust other organization level settings.

  • User—Any non-admin member of an organization who can interact with MASA. A user must be invited into an organization by the Admin

    • By default, new users have view-only access.

    • The Admin assigns permissions to request, download, or archive ownership vouchers

Prerequisites for Interacting with MASA Server

  1. You must be an authorized MASA User

    • You must have a Cisco account and an active invitation to access MASA for the first time.


      Note

      Contact the Cisco Technical Assistance team or your Account team to get a Cisco account.

    • Initial authentication requires Cisco Single Sign On to the MASA web application (masa.cisco.com).

      For subsequent authentication, you can generate access keys called tokens. Token serve as an alternative authentication mechanism that can be passed along in the header of API calls.


      Note

      To generate access keys for the first time, on masa.cisco.com, go to Settings→ Tokens. For subsequent sessions, use API calls to manage existing tokens or create new ones as long as an unexpired token is still available.

      The following is an example of using a token in a header of a REST API call.

      ‘Authorization: Bearer 637c98ddcc58c75f679a94d7f244777be05c6600923c4549bc5669b26e04f2bc
gAAAAABjfRr9hqndFqbuqes9OvcfgucApgxpmm9qoVmUidYEs-_Aziu7yue-10dazZ3Rxk6vJHYD2Je7Z-IOD1Zc7kYSuBTX0
6GcQvF2e3nSM-_F9BoltjxAHcXkoMgbqS4APFGi16LiWRyP2b1_0rZO-EaTKFLEldTLfMAmovPDkZZ5vbBwRS058PZN1vB3IZIZ
jftYYYi9H_grazfwnAImjKbQC6tjQw==

      Tokens can have a custom validity period of up to six months that can be revoked at any time. The scope of the tokens is limited to scope of your role.

  2. ZTP server must be able to access the Internet


    Note

    MASA application is served through HTTPS to provide a secure connection between the end user and the service.

User Permissions

The MASA Server supports Role Based Access Control and provides the following access:

  • Regular user—By default, regular users have only read access to their organization. Admin users can provide additional privileges as required.

  • Admin—Admin users have the ability to view and manage OVs for all routers in the database in their organization as well as other privileges as mentioned in the table below.

Table 2. User Permissions

Type

Regular User

Admin

Invite other People into the organization

Not allowed

Allowed by default

Add or remove permissions for other users

Not allowed

Allowed by default

View all existing vouchers

Allowed by default

Allowed by default

Request new vouchers

Permission can be provided by Admin

Allowed by default

Download vouchers

Permission can be provided by Admin

Allowed by default

Archive vouchers

Permission can be provided by Admin

Allowed by default

Interacting with MASA Through Web Application

Table 3. Feature History Table

Feature Name

Release Information

Feature Description

Pre-upload Pinned-Domain Certificate

Release 24.1.1

You can now pre-upload your Pinned-Domain Certificate (PDC) credentials before requesting OVs Ownership Vouchers (OVs) from the MASA server, thus making the voucher request process easier.

  1. Go to masa.cisco.com

    Figure 3. Sign in Page—MASA Web Application

  2. Click Sign in using Cisco SSO.

  3. Enter your username and password to access the application

  4. Accept the End User License Agreement.

    The MASA Home page displays the status of any recent requests that were initiated and quick links to download any recently generated ownership vouchers.

    Figure 4. Home Page—MASA Web Application

Requesting OVs for Your Router

  1. Click New Request on the top right of the Home page.

  2. In the New Request dialog box, enter details for one of the following:

    • Serial number of your router

      You can get the serial number from the bottom of your router; it is an 11 digit alphanumeric string. You can also get the serial number by running the show version command on your router.

    • Pinned-domain Certificate

      There are multiple ways to generate a PDC (.pem). For example, through OpenSSL. You can either paste the content of the certificate directly or browse to a file that contains the PDC.

      You can pre-upload the certificate prior to requesting the OV.

      To select the pre-uploaded certificate while requesting OV, turn on the toggle button named use pre-uploaded certificate.You can see the already uploaded certificates here, you can select the certificate from this list.

    • Serial number of one or more routers for which you want the OVs.


    Note

    Always use the serial number of the route processor (RP) of your router.

    Figure 5. New Request Page
    Figure 6. Home Page—With New OVs Displayed

    Depending on your user permissions, you can perform the following actions from the Home page.

    • Download the generated OVs.

    • Regenerate OVs.

    • View details of past requests

    • Filter, sort, and group the requests based on their attributes

    • Archive the OVs.

Interacting with MASA Through REST APIs

You can also use APIs to programmatically interact with the MASA service.

See the OpenAPI documentation page that contains details about the paths, formats, and structures of the APIs.

For example, use this API to request for the ownership voucher:

POST /request/ov

Use this API to fetch details about an already generated voucher:

GET /voucher/{voucher_id}
Response:
{
  "ok": true,
  "voucher": {
    "req_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "voucher_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "requested_at": "2022-08-31T09:43:39.719Z",
    "created_at": "2022-08-31T09:43:39.719Z",
    "expires_at": "2022-08-31T09:43:39.719Z",
    "last_renewal_at": "2022-08-31T09:43:39.719Z",
    "assertion": "logged",
    "status": "completed",
    "serial_number": "T8I52J1IKOM",
    "pdc_organization": "Cisco Systems",
    "requested_by": "user1@cisco.com"
  }
}

Note

“serial Number” is serial number of the route processor. You can provide up to 20 serial numbers in a single request.

Interaction with MASA through gRPC

Table 4. Feature History Table

Feature Name

Release Information

Feature Description

Interaction with MASA through gRPC

Release 24.1.1

From this release, you can use the gRPC protocol to interact with MASA APIs in addition to the current HTTP protocols. Through structured serialization of data with gRPC's Protocol Buffers, the communication between services is made more efficient, type-safe, and consistent.

The following MASA APIs are accessible using gRPC protocol in addition to http protocol:

RPC

Description

rpc GetGroup

Returns the domain-certificates (keyed by id), serials, and user/role mappings for that group.

rpc AddUserRole

Assigns a role to a user in a named group. Username is unique to an Org ID.

rpc RemoveUserRole

Removes a role from a user in a named group. Username is unique to an Org ID.

rpc GetUserRole

Returns the roles that the user is assigned in the group. Username is unique to an Org ID. A user can only view roles of another user in the group that it has a role assigned to.

rpc CreateDomainCert

Creates the certificate in the group.

rpc GetDomainCert

Reveals the details of the certificate.

rpc DeleteDomainCert

Deletes the certificate from the database.

rpc GetOwnershipVoucher

Issues an ownership voucher.

For more information on gRPC, see Use gRPC Protocol to Define Network Operations with Data Models in the Programmability Configuration Guide for Cisco 8000 Series Routers.

Workflow to Provision a Router Using Ownership Voucher

The following figure illustrates the complete workflow to provision a Cisco IOS XR router by using the ownership vouchers.