Virtual Private Networks (SVTI and EzVPN)

The REST API client can use the default IOS isakmp profile and IOS ipsec policy. If the defaults are not used, the REST API client must define an IKE policy and/or IPSec policy before configuring the IPSec site-to-site VPN.

Workflows

Create an IPSEC VPN Tunnel

1.blank.gif Create a keyring. The keyring can be shared by more than one tunnels.

POST /api/v1/vpn-svc/ike/keyrings

Create an IKE Keyring

2.blank.gif (Optional) Create the IKE policy (can use one of the default policies). The IKE policy can be shared by more than one tunnel.

POST /api/v1/vpn-svc/ike/policies

Create an IKE Policy

3.blank.gif Create IPSEC policy (it include transform set and ipsec profile, they can be shared by many tunnels).

POST /api/v1/vpn-svc/ipsec/policies

Create an IPSec Policy

4.blank.gif Create IPSEC VPN tunnel endpoint ( it will reference ike/ipsec policy or profile, this will create a tunnel interface).

POST /api/v1/vpn-svc/site-to-site

Create a Site-to-Site VPN Tunnel

Resource Summary for IPSec VPN

 

HTTP Method
Resource
URL (BaseURL)
GET
POST
PUT
DELETE

IPSec VPN site-to-site

/api/v1/vpn-svc/site-to-site

Y

Y

N

N

IPSec VPN site-to-site interface

/api/v1/vpn-svc/site-to-site/{vpn-interface-id}

Y

N

Y

Y

VPN site-to-site interface state

/api/v1/vpn-svc/site-to-site/{vpn-interface-id}/state

Y

N

Y

N

DMVPN Hub

/api/v1/vpn-svc/dmvpn/hub

Y

Y

N

N

/api/v1/vpn-svc/dmvpn/hub/{vpn-id}

Y

N

Y

Y

Keyrings

/api/v1/vpn-svc/ike/keyrings

Y

Y

N

N

Keyring ID

/api/v1/vpn-svc/ike/keyrings/{keyring-id}

Y

N

Y

Y

IKE policies

/api/v1/vpn-svc/ike/policies

N

N

N

N

/api/v1/vpn-svc/ike/policies/{policy-id}

N

N

N

N

IKE Keep Alive

/api/v1/vpn-svc/ike/keepalive

Y

N

Y

Y

IKEv2 Policy

/api/v1/vpn-svc/ikev2/policy

Y

Y

N

N

/api/v1/vpn-svc/ikev2/policy/{resource-id}

Y

N

Y

Y

IKEv2 Keyring

/api/v1/vpn-svc/ikev2/keyring

Y

N

N

N

/api/v1/vpn-svc/ikev2/keyring/(resource-id}

Y

N

N

Y

IKEv2 Keyring Peer

/api/v1/vpn-svc/ikev2/keyring/(resource-id}/add-peer

N

Y

N

N

/api/v1/vpn-svc/ikev2/keyring/(resource-id}/add-peer/{peer-name}

N

N

Y

Y

IKEv2 Profile

/api/v1/vpn-svc/ikev2/profile

Y

Y

N

N

/api/v1/vpn-svc/ikev2/profile/{resource-id}

Y

N

Y

Y

IPSec policies

/api/v1/vpn-svc/ipsec/policies

Y

Y

N

N

/api/v1/vpn-svc/ipsec/policies/{policy-id}

Y

N

Y

Y

Active sessions

/api/v1/vpn-svc/site-to-site/active/sessions

Y

N

N

N

Site-to-site statistics

/api/v1/vpn-svc/site-to-site/statistics

Y

N

N

N

IKE Crypto Key Ring Resource

History

 

Release
Modification

IOS XE 3.10

Introduced for the CSR1000V platform

IOS XE 3.14

Introduced for ASR1001-X and ASR1002-X platforms

Properties

 

Property
Type
Required for POST and PUT
Description

kind

string

Not applicable

Must be object#ike-keyring.

keyring-id

string

Mandatory

IKE key ring name. This cannot be changed once it is configured.

pre-shared-key-list

array

Mandatory

List of pre-shared-key information. This is equivalent to the IOS “crypto keyring” with one or more (key, remote-address) pairs.

key

string

Mandatory

Pre-shared-key value

peer-address

string

Mandatory

Host name or IP address in CIDR format x.x.x.x/nn

JSON Representation for REST API IKE Profile (IOS Crypto Keyring)

{
"kind" : "object#ike-keyring",
"keyring-id": "{string}",
"pre-shared-key-list":
[
{
"key": "{string}",
"peer-address": "{string}"
}
]
}

Retrieve an IKE Keyring

Resource URI

 

Verb
URI

GET

/api/v1/vpn-svc/ike/keyrings/{keyring-id}

Example

JSON Request

GET /api/v1/vpn-svc/ike/keyrings/myKeyring
Accept: application/json

JSON Response

200 OK
 
Content-type: application/json
 
{
"kind": "object#ike-policy"
"keyring-id": "myKeyring",
"pre-shared-key-list":
[
{
"key": "cisco123",
"peer-address": "pepsi-1"
}
]
}

Retrieve All IKE Keyrings

Resource URI

 

Verb
URI

GET

/api/v1/vpn-svc/ike/keyrings

Properties for Retrieve All

 

Property
Type
Required for POST and PUT
Description

kind

string

Not applicable

Object#ike-keying

items

array

Mandatory

List of IKE keyring objects.

JSON Representation

{
"kind": "collection#ike-keyring",
"items": [
{ IKE keyring JSON object } *
]
}

Example

JSON Request

GET /api/v1/vpn-svc/ike/keyrings
Accept: application/json

JSON Response

200 OK
 
Content-type: application/json
 
{
"kind": "collection#ike-keyring",
"items": [
{
"kind": "object#ike-keyring",
"keyring-id": "myIkeKeyring",
"pre-shared-key-list":
[
{
"key": "cisco123",
"peer-address": "pepsi-1"
}
]
},
{
"kind": "object#ike-keyring",
"keyring-id": "myOtherIkeKeyring",
"pre-shared-key-list":
[
{
"key": "mag33ks",
"peer-address": "marketing"
}
]
}
}

Update an IKE Keyring

Resource URI

 

Verb
URI

PUT

/api/v1/vpn-svc/ike/keyrings/{keyring-id}

Example: Request to Add Another Key and Peer-address

JSON Request

PUT /api/v1/vpn-svc/ike/myIkeKeyring
 
Content-type: application/json
Accept: application/json
 
{
"keyring-id": "myIkeKeyring",
"pre-shared-key-list":
[
{"key": "cisco123", "peer-address": "pepsi-1"},
{"key": "root123", "peer-address": "coke"}
]
}

JSON Response

201 Created
Location: http://http/host/api/v1/vpn-svc/ike/myIkeKeyring

Delete an IKE Keyring

Resource URI

 

Verb
URI

DELETE

/api/v1/vpn-svc/ike/keyrings/{keyring-id}

Example

JSON Request

DELETE /api/v1/vpn-svc/ike/profiles/myIkeKeyring
Accept: application/json

JSON Response

204 No Content

Create an IKE Keyring

Resource URI

 

Verb
URI

POST

/api/v1/vpn-svc/ike/keyrings

Example

JSON Request

POST /api/v1/vpn-svc/ike/keyrings
 
Content-type: application/json
Accept: application/json
 
{
"keyring-name": "myIkeKeyring",
"pre-shared-key-list":
[
{
"key": "XnX1B0I9Z4CWNCGzeEhlNuTFxWBD1vng",
"peer-address": "10.0.149.217/32"
}
]
}

JSON Response

201 Created
Location: http://host/api/v1/vpn-svc/ike/keyrings/myIkeKeyring

IKE Policy Resource

An IKE policy resource must be created before creating a VPN site-to-site tunnel. The policy is a global configuration and can be applied to more than one VPN tunnel.

History

 

Release
Modification

IOS XE 3.10

Introduced for the CSR1000V platform

IOS XE 3.14

Introduced for ASR1001-X and ASR1002-X platforms

Properties

 

Property
Type
Required for POST and PUT
Description

kind

string

Not applicable

Must be object#ike-policy.

priority-id

string

Mandatory

This is the ISAKMP policy priority number, so it must be a number in IKEv1 (it is different for ikev2).

version

string

Optional

IKE version. Only “v1” is supported.

local-auth-method

string

Optional

“pre-share” for pre-shared key (default). “rsa-sig” and “rsa-encr” are not supported.

encryption

string

Optional

Values are

  • “3des”- triple DES
  • “aes”: AES - Advanced Encryption Standard.
  • “des”: DES - Data Encryption Standard (56 bit keys)

hash

string

Optional
  • md5: Message Digest 5
  • sha: Secure Hash Standard

There is a default.

dhGroup

number

Optional
  • 1 Diffie-Hellman group 1 (768 bit)
  • 2 Diffie-Hellman group 2 (1024 bit)
  • 5 Diffie-Hellman group 5 (1536 bit)

There is a default.

lifetime

number

Optional

<60-86400> lifetime in seconds. There is a default.

JSON Representation for REST API IKE Policy (IOS ISAKMP Policy)

{
"kind" : "object#ike-policy",
"priority-id": "{string}",
"version": "{string}",
"local-auth-method": "{string}",
"encryption": "{string}",
"hash": "{string}",
"dhGroup": {number},
"lifetime":{number}
}

Retrieve an IKE Policy

Resource URI

 

Verb
URI

GET

api/v1/vpn-svc/ike/policies/{policy-id}

Example

JSON Request

GET /api/v1/vpn-svc/ike/policies/2
Accept: application/json

JSON Response

200 OK
 
Content-type: application/json
 
{
"kind": "object#ike-policy"
"priority-id": "2",
"version": "v1",
"local-auth-method": "pre-share",
"encryption": "aes128",
"hash": "sha",
"dhGroup": 2,
"lifetime": 600
}

Retrieve All IKE Policies

Resource URI

 

Verb
URI

GET

/api/v1/vpn-svc/ike/policies

Properties for Retrieve All

 

Property
Type
Required for POST and PUT
Description

kind

string

Not applicable

Must be “collection#ike-policy”

items

array

 

List of IKE policy objects.

JSON Representation

{
"kind": "collection#ike-policy",
"items": [
{ IKE policy JSON object } *
]
}

Example

JSON Request

GET /api/v1/vpn-svc/ike/policies
Accept: application/json

JSON Response

200 OK
 
Content-type: application/json
 
{
"kind": "collection#ike-policy",
"items": [
{
"kind": "object#ike-policy",
"priority-id": "2",
"version": "v1",
"local-auth-method": "pre-share",
"encryption": "3des",
"hash": "sha",
"dhGroup": 2,
"lifetime": 600
},
{
"kind": "object#ike-policy",
"priority-id": "3",
"version": "v1",
"local-auth-method": "pre-share",
"encryption": "3des",
"hash": "md5",
"dhGroup": 2,
"lifetime": 600
}
}

Update an IKE Policy

Resource URI

 

Verb
URI

PUT

/api/v1/vpn-svc/ike/policies/{policy-id}

Example: Modifying the Protection-suite Encryption from 3DES to AES128

JSON Request

PUT /api/v1/vpn-svc/ike/2
 
Content-type: application/json
Accept: application/json
 
{
"priority-id": "2",
"version": "v1",
"local-auth-method": "pre-share",
"encryption": "aes128",
"hash": "sha",
"dhGroup": 2,
"lifetime": 600
}

JSON Response

201 Created
Location: http://http/host/api/v1/vpn-svc/ike/2

Delete an IKE Policy

Resource URI

 

Verb
URI

DELETE

/api/v1/vpn-svc/ike/policies/{policy-id}

Example

JSON Request

DELETE /api/v1/vpn-svc/ike/policies/2
Accept: application/json

JSON Response

204 No Content

Create an IKE Policy

Resource URI

 

Verb
URI

POST

/api/v1/vpn-svc/ike/policies

Example

JSON Request

POST /api/v1/vpn-svc/ike/policies
 
Content-type: application/json
Accept: application/json
 
{
"priority-id": "2",
"version": "v1",
"local-auth-method": "pre-share",
"encryption": "3des",
"hash": "sha",
"dhGroup": 2,
"lifetime": 600
}

JSON Response

201 Created
Location: http://host/api/v1/vpn-svc/ike/policies/2

IKE Keepalive Resource

The IKE Keepalive is a single global Resource. DELETE on this resource removes the IKE Keepalive configuration on the router. GET on this resource will return 404 Not Found when IKE Keepalive is not configured.

History

 

Release
Modification

IOS XE 3.11

Introduced for the CSR1000V platform

IOS XE 3.14

Introduced for ASR1001-X and ASR1002-X platforms

Properties

 

Property
Type
Required for POST and PUT
Description

kind

string

Not applicable

Object type: “object#ike-keepalive”

interval

number

Mandatory

Keepalive interval time (10 - 3600)

retry

number

Mandatory

Retry time (2 - 60), default 2 seconds

periodic

boolean

Mandatory

Keepalive mode, TRUE is periodic, FALSE is on-demand which is the default

JSON Representation for IKE Keepalive

{

"kind ": "object#ike-keepalive",

"interval ": {number},

"retry ": {number},

"periodic ": {boolean}

}

 

Retrieve IKE Keepalive

Resource URI

 

Verb
URI

GET

/api/v1/vpn-svc/ike/keepalive

Example

JSON Request

 

GET /api/v1/vpn-svc/ike/keepalive

Accept: application/json

 

JSON Response

200 OK

Content-Type: application/json

 

{

"kind ": "object#ike-keepalive",

"interval ": 30,

"retry ": 2,

"periodic ": false

}

 

Modify IKE Keepalive

Resource URI

 

Verb
URI

PUT

/api/v1/vpn-svc/ike/keepalive

Example

JSON Request

 

PUT /api/v1/vpn-svc/ike/keepalive

Content-Type: application/json

 

{

"interval ": 30,

"retry ": 10,

"periodic ": true

}

 

 

JSON Response

204 No Content

Delete IKE Keepalive

Resource URI

 

Verb
URI

DELETE

/api/v1/vpn-svc/ike/keepalive

Example

JSON Request

 

DELETE /api/v1/vpn-svc/ike/keepalive

 

JSON Response

204 No Content

 

 

IPSec Policy Resource

An IPSec policy resource must be created before creating a VPN site-to-site tunnel. The policy is a global configuration and can be applied to more than one VPN tunnel.

History

 

Release
Modification

IOS XE 3.10

Introduced for the CSR1000V platform

IOS XE 3.14

Introduced for ASR1001-X and ASR1002-X platforms

Properties

 

Property
Type
Required for POST and PUT
Description

kind

string

Not applicable

Object#ipsec-policy

policy-id

string

Mandatory

IPSec policy name

protection-suite

 

Mandatory

Optional as there is a default protection suite (IOS transform-set).

esp-encryption

string

Mandatory

(sub-property of protection-suite)

ESP encryption transform. There is a default.

  • esp-3des: ESP transform using 3DES(EDE) cipher (168 bits)
  • esp-aes: ESP transform using AES cipher. Default.
  • esp-des: ESP transform using DES cipher (56 bits)
  • esp-null: ESP transform w/o cipher
  • esp-seal: ESP transform using SEAL cipher (160 bits)

esp-authentication

string

Optional

(sub-property of protection-suite)

ESP authentication transform.

  • esp-md5-hmac: ESP transform using HMAC-MD5 auth
  • esp-sha-hmac: ESP transform using HMAC-SHA auth. Default.

ah

string

Optional

(sub-property of protection-suite)

AH transform:

  • ah-md5-hmac: AH-HMAC-MD5 transform
  • ah-sha-hmac: AH-HMAC-SHA transform

anti-replay-window-size

string

Optional

“Disable” or one of these numbers

  • 1024: Window size of 1024
  • 128: Window size of 128
  • 256: Window size of 256
  • 512: Window size of 512
  • 64: Window size of 64 (default).

lifetime-sec

lifetime-kb

idle-time

number

number

number

Optional

Optional

Optional

Default of 3600 seconds.

Default is 4608000.

IPSec idle timer in seconds.

pfs

string

Optional

Default is Disable. If enable, specifies DH group. Optional.

  • group1: D-H Group1 (768-bit modp)
  • group14: D-H Group14 (2048-bit modp)
  • group15: D-H Group15 (3072-bit modp)
  • group16: D-H Group16 (4096-bit modp)
  • group19: D-H Group19 (256-bit ecp)
  • group2: D-H Group2 (1024-bit modp)
  • group20: D-H Group20 (384-bit ecp)
  • group24: D-H Group24 (2048-bit modp, 256 bit subgroup)
  • group5: D-H Group5 (1536-bit modp)

JSON Representation

{
"kind": "object#ipsec-policy",
"policy-id": "{string}",
"protection-suite":
{
"esp-encryption": "{string}",
"esp-authentication": "{string}",
"ah": "{string}"
},
"anti-replay-window-size": "{string}",
"lifetime-sec": {number},
"lifetime-kb": {number},
"idle-time": {number},
"pfs": "{string}"
}

Retrieve an IPSec Policy

Resource URI

 

Verb
URI

GET

/api/v1/vpn-svc/ipsec/policies/{policy-id}

Example

JSON Request

GET /api/v1/vpn-svc/ipsec/policies/myIpsecPolicy
Accept: application/json

JSON Response

200 OK
 
Content-type: application/json
 
{
"kind": "object#ipsec-policy",
"policy-id": "myIpsecPolicy",
"protection-suite":
{
"esp-encryption": "esp-3des",
"esp-authentication": "esp-sha-hmac"
},
"anti-replay-window-size": 64,
"lifetime-sec": 3600,
"lifetime-kb": 4068000,
"idle-time": 10000000,
"pfs": "disable"
}

Retrieve All IPSec Policies

Resource URI

 

Verb
URI

GET

/api/v1/vpn-svc/ipsec/policies

Properties for Retrieve All

 

Property
Type
Required for POST and PUT
Description

kind

string

Not applicable

Must be “collection#ipsec-policy”

Items

array

Mandatory

List of IPSec policy objects.

JSON Representation

{
"kind": "collection#ipsec-policy",
"items": [
{ IPSec policy JSON object } *
]
}

Example

JSON Request

GET /api/v1/vpn-svc/ipsec/policies
Accept: application/json

JSON Response

200 OK
 
Content-type: application/json
Accept: application/json
 
{
"kind": "collection#ipsec-policy",
"items": [
{
"kind": "object#ipsec-policy",
"policy-id": "myIpsecPolicy",
"protection-suite":
{
"esp-encryption": "esp-aes",
"esp-authentication": "esp-md5-hmac",
"ah": "ah-md5-hmac"
},
"mode": "tunnel",
"anti-replay-window-size": 512,
"lifetime-sec: 1000,
"lifetime-kb: 1000000,
"idle-time: 10000,
"pfs": "group1"
},
{
"kind": "object#ipsec-policy",
"policy-id": "testPolicy",
"protection-suite":
{
"esp-encryption": "esp-aes"
},
"mode": "tunnel",
"anti-replay-window-size": "512",
"lifetime-sec: 1000,
"lifetime-kb: 4608000,
"idle-time: 10000,
"pfs": "group1"
},
]
}

Modify an IPSec Policy

Resource URI

 

Verb
URI

PUT

/api/v1/vpn-svc/ipsec/policies/{policy-id}

Example

JSON Request

PUT /api/v1/vpn-svc/ipsec/policies/myIpsecPolicy
 
Content-type: application/json
Accept: application/json
 
 
{
"policy-id": "myIpsecPolicy",
"protection-suite":
{
"esp-encryption": "esp-3des",
"esp-authentication": "esp-sha-hmac"
},
"anti-replay-window-size": 64,
"lifetime-sec": 3600,
"lifetime-kb": 4068000,
"idle-time": 10000000,
"pfs": "disable"
}
 

JSON Response

204 No Content

Delete an IPSec Policy

Resource URI

 

Verb
URI

DELETE

/api/v1/vpn-svc/ipsec/policies/{policy-id}

Example

JSON Request

DELETE /api/v1/vpn-svc/ipsec/policies/myIpsecPolicy
Accept: application/json

JSON Response

204 No Content

Create an IPSec Policy

Resource URI

 

Verb
URI

POST

/api/v1/vpn-svc/ipsec/policies

Example

JSON Request

POST /api/v1/vpn-svc/ipsec/policies
 
Content-type: application/json
Accept: application/json
 
{
"policy-id": "myIpsecPolicy",
"protection-suite":
{
"esp-encryption": "esp-aes",
"esp-authentication": "esp-md5-hmac",
"ah": "ah-md5-hmac"
},
"mode": "tunnel",
"anti-replay-window-size": 512,
"lifetime-sec": 1000,
"lifetime-kb": 1000000,
"idle-time": 10000,
"pfs": "group1"
}

JSON Response

201 Created
 
Location: http://host/api/v1/vpn-svc/ipsec/policies/myIpsecPolicy

Site-to-Site Tunnel

History

 

Release
Modification

IOS XE 3.10

Introduced for the CSR1000V platform

IOS XE 3.11

For the local-device property, added the option of entering an interface name instead of an IP address.

IOS XE 3.12

Added ike-profile and mtu properties.

IOS XE 3.14

Introduced for ASR1001-X and ASR1002-X platforms

Properties

 

Property
Type
Required for POST and PUT
Description

vpn-interface-name

string

Mandatory

A unique name of the form “tunnel<number>”. For example, “tunnel1”.

ike-profile

string

Optional

IKE profile name

mtu

number

Optional

MTU of the VPN tunnel

Range: 68 to 9192

vpn-type

string

Mandatory

Must be “site-to-site”.

ip-version

string

Mandatory

“ipv4” or “ipv6”. The default is IPv4. Optional.

ipsec-policy-id

string

Optional

IPSec policy name.

local-device

  • ip-address
  • tunnel-ip-address

string

Mandatory

The local device

  • Tunnel interface's IP address. It can be in CIDR format x.x.x.x/nn or an interface name. When it is an interface name, it is an IP unnumbered interface name.
  • Required for svti and dvti. name or IP address in x.x.x.x format.

remote-device

  • tunnel-ip-address

string

Mandatory

Remote peer IP address in x.x.x.x format.

JSON Representation

{
"kind": "object#vpn-site-to-site"
"vpn-type": "site-to-site",
"vpn-interface-name": "{string}",
"ike-profile" : "{string}",
"mtu": {number},
"ip-version": "{string}",
"ipsec-policy-id": "{string}",
"local-device": {
"ip-address": "{string}",
"tunnel-ip-address": "{string}"
},
"remote-device": {
"tunnel-ip-address": "{string}",
}
}
 

Retrieve a Site-to-Site VPN Tunnel

Resource URI

 

Verb
URI

GET

/api/v1/vpn-svc/site-to-site/{vpn-id}

Example

JSON Request

GET /api/v1/vpn-svc/site-to-site/tunnel100
Accept: application/json

JSON Response

200 OK
 
Content-type: application/json
 
{
"kind": "object#vpn-site-to-site",
"vpn-interface-name": "tunnel100",
"vpn-type": "site-to-site",
"ip-version": "ipv4",
"ipsec-policy-id": "myIpsecPolicy",
"local-device":
{
"ip-address": "10.0.51.203/24",
"tunnel-ip-address": "10.0.149.203"
},
"remote-device":
{
"tunnel-ip-address": "10.0.149.217"
}
}

Retrieve All Site-to-Site VPN Tunnels

Resource URI

 

Verb
URI

GET

/api/v1/vpn-svc/site-to-site

Properties for Retrieve All

 

Property
Type
Required for POST and PUT
Description

kind

string

Not applicable

Must be “collection#vpn-site-to-site”.

items

array

Not applicable

List of VPN objects.

JSON Representation

{
"kind": "collection#vpn-site-to-site",
"items":
[
{vpn site-to-site json object}+
]
}

Example

JSON Request

GET /api/v1/vpn-svc/site-to-site
Accept: application/json
 

JSON Response

200 OK
 
Content-type: application/json
 
{
"kind": "collection#vpn-site-to-site",
"items": [
{
"kind": "object#vpn-site-to-site",
"vpn-type": "site-to-site",
"vpn--name": "tunnel100",
"ike-profile": "ike-profile-1",
"mtu": 1400,
"ip-version": "ipv4",
"ipsec-policy-id": "myIpsecPolicy",
"local-device": {
"ip-address": "10.0.51.203/24",
"tunnel-ip-address": "10.0.149.203",
},
"remote-device": {
"tunnelIpAddress": "10.0.149.217"
}
},
{
"kind": "object#vpn-site-to-site",
"vpn-type": "site-to-site",
"vpn--name": "tunnel33",
"ike-profile": "ike-profile-1",
"mtu": 1400,
"ip-version": "ipv4",
"ipsec-policy-id": "ciscoIpsecPolicy",
"local-device": {
"ip-address": "100.0.51.203/24",
"tunnel-ip-address": "100.0.149.203",
},
"remote-device": {
"tunnelIpAddress": "100.0.149.217"
}
}
]
}

Create a Site-to-Site VPN Tunnel

Resource URI

 

Verb
URI

POST

/api/v1/vpn-svc/site-to-site

Example

This POST example relates to the VPN tunnel example given in Retrieve All Site-to-Site VPN Tunnels.

JSON Request

POST /api/v1/vpn-svc/site-to-site
 
Content-type: application/json
Accept: application/json
 
{
"vpn-type": "site-to-site",
"vpn-interface-name": "tunnel100",
"ike-profile": "ike-profile-1",
"mtu": 1400,
"ip-version": "ipv4",
"ipsec-policy-id": "myIpsecPolicy",
"local-device": {
"ip-address": "10.0.51.203/24",
"tunnel-ip-address": "10.0.149.203"
},
"remote-device": {
"tunnel-ip-address": "10.0.149.217"
}
}

JSON Response

204 No Content
 
Location: http://host/api/v1/vpn-svc/site-to-site/tunnel100

Modify a Site-to-Site VPN

Resource URI

 

Verb
URI

PUT

/api/v1/vpn-svc/site-to-site/{vpn--id}

Example: Modifying the Remote Tunnel IP Address

JSON Request

PUT /api/v1/vpn-svc/site-to-site/tunnel100
 
Content-type: application/json
Accept: application/json
 
{
"vpn-interface-name": "tunnel100",
"vpn-type": "site-to-site",
"ip-version": "ipv4",
"ipsec-policy-id": "myIpsecPolicy",
"local-device": {
"ip-address": "10.0.51.203/24",
"tunnel-ip-address": "10.0.149.203",
},
"remote-device": {
"tunnel-ip-address": "10.0.149.218"
}
}

JSON Response

204 No Content

HTTP DELETE a VPN Site-to-Site Tunnel

Resource URI

 

Verb
URI

DELETE

/api/v1/vpn-svc/site-to-site/{vpn-id}

Example

JSON Request

DELETE /api/v1/vpn-svc/site-to-site/tunnel100
Accept: application/json

JSON Response

204 No Content
 

 

Change State of a Tunnel Interface

Use this resource to configure or retrieve the state of a tunnel interface.

History

 

Release
Modification

IOS XE 3.13

Introduced for the CSR1000V platform

IOS XE 3.14

Introduced for ASR1001-X and ASR1002-X platforms

Properties

 

Property
Type
Required for POST and PUT
Description

kind

string

Optional

object#vpn-site-to-site-state

vpn-interface-name

string

Optional

VPN interface name

Example: Tunnel100

enabled

Boolean

Mandatory

False = shut the tunnel interface

True = no shut the tunnel interface

line-protocol-state

string

Optional

Used only in GET API, not in PUT.

Possible values: "up" or "down"

JSON Representation

{
"kind" : "object#vpn-site-to-site-state",
"vpn-interface-name" : "{string}",
"line-protocol-state": "{string}",
"enabled" : {Boolean}
}
 

Configure Tunnel Interface State

Resource URI

 

Verb
URI

PUT

/api/v1/vpn-svc/site-to-site/{vpn-interface-id}/state

Example

JSON Request

PUT /api/v1/vpn-svc/site-to-site/tunnel100/state
Content-Type: application/json
 
{
"vpn-interface-name" : "tunnel100",
"enabled" : false
}
 

JSON Response

204 No Content
 

Retrieve Tunnel Interface State

Resource URI

 

Verb
URI

GET

/api/v1/vpn-svc/site-to-site/{vpn-interface-id}/state

Example

JSON Request

GET /api/v1/vpn-svc/site-to-site/tunnel100/state
 

JSON Response

200 ok
 
Content-type: application/json
 
{
"kind" : "object#vpn-site-to-site-state",
"vpn-interface-name" : "tunnel100",
"line-protocol-state": "down",
"enabled" : false
}
 

VPN Active Sessions Collection Resource

History

 

Release
Modification

IOS XE 3.10

Introduced for the CSR1000V platform

IOS XE 3.14

Introduced for ASR1001-X and ASR1002-X platforms

Properties

 

Property
Type
Required for POST and PUT
Description

kind

string

Not applicable

Must be collection#vpn-active-session

items

array

Not applicable

List of vpn-active-session JSON object

vpn-type

string

Not applicable

Must be “site-to-site”.

vpn-interface-name

string

Not applicable

Unique number identifying the VPN tunnel.

status

string

Not applicable

See the next table for a description of the possible tunnel states.

local-address

ipaddress

Not applicable

Tunnel source IP address in x.x.x.x format.

remote-address

string

Not applicable

Tunnel destination IP address in x.x.x.x format.

ike-remaining-lifetime

number

Not applicable

IKE SA remaining lifetime in HH:MM:SS format.

ipsec-tx-remaining-
lifetime-kb

number

Not applicable

IPSec outbound SA remaining lifetime in KB.

ipsec-rx-remaining-
lifetime-kb

number

Not applicable

IPSec inbound SA remaining lifetime in KB.

ipsec-tx-remaining-
lifetime-sec

number

Not applicable

IPSec outbound SA remaining lifetime in seconds.

ipsec-rx-remaining-
lifetime-sec

number

Not applicable

IPSec inbound SA remaining lifetime in seconds.

JSON Representation

{
"kind": "collection#vpn-active-session",
"items": [
{
"kind": "object#vpn-active-session",
"vpn-type": "site-to-site",
"vpn-interface-name": "{string}",
"status": "{string}",
"local-address": "{ipaddress}",
"remote-address": "{ipaddress}",
"ike-remaining-lifetime": "hh:mm:ss",
"ipsec-tx-remaining-lifetime-in-KB": {number},
"ipsec-rx-remaining-lifetime-in-KB": {number},
"ipsec-tx-remaining-lifetime-in-sec": {number},
"ipsec-rx-remaining-lifetime-in-sec": {number}
}
]
}

Tunnel States

The following table lists the tunnel states.

 

IKE SA
IPSec SA
Tunnel Status

Exist, Active

Exist (flow exists)

UP-ACTIVE

Exist, active

None (flow exists)

UP-IDLE

Exist, inactive

Exist (flow exists)

UP-NO-IKE

Exist, inactive

None (flow exists)

DOWN-NEGOTIATING

Exist, inactive

None (no flow)

DOWN-NEGOTIATING

None

Exist (flow exists)

UP-NO-IKE

None

None (flow exists)

DOWN

None

None (no flow)

DOWN

Retrieve VPN Active Sessions

Resource URI

 

Verb
URI

GET

/api/v1/vpn-svc/site-to-site/active/sessions

Example

JSON Request

GET /api/v1/vpn-svc/site-to-site/active/sessions
Accept: application/json

JSON Response

200 OK
 
Content-type: application/json
 
{
"kind": "collection#vpn-active-session",
"items": [
{
"kind": "object#vpn-active-session",
"vpn-interface-name": "tunnel100",
"vpn-type": "site-to-site",
"status": "UP-ACTIVE",
"local-address": "10.1.1.4",
"remote-address": "10.1.1.3",
"ike-remaining-lifetime": "22:03:24",
"ipsec-tx-remaining-lifetime-in-KB": 4605665,
"ipsec-rx-remaining-lifetime-in-KB": 4605400,
"ipsec-tx-remaining-lifetime-in-sec": 2949,
"ipsec-rx-remaining-lifetime-in-sec": 2949
}
]
}

Retrieve All VPN Active Session Statistics

Resource URI

 

Verb
URI

GET

/api/v1/vpn-svc/site-to-site/active/sessions

Properties for Retrieve All

 

Property
Type
Required for POST and PUT
Description

kind

string

Not applicable

Must be “collection#vpn-statistics”.

items

array

Not applicable

List of object#vpn-statistics

vpn-type

string

Not applicable

Must be “site-to-site” in IOS-XE 3.10

vpn-interface-name

string

Not applicable

The IOS tunnel number in “tunnel<number>” format, such as “tunnel2”.

local-address

ipaddress

Not applicable

Tunnel source IP address in x.x.x.x format.

remote-address

ipaddress

Not applicable

Tunnel destination IP address in x.x.x.x format.

encapsulated

number

Not applicable

Number of encapsulated packets.

decapsulated

number

Not applicable

Number of decapsulated packets.

encrypted

number

Not applicable

Number of encrypted packets.

decrypted

number

Not applicable

Number of decrypted packets.

send-errors

number

Not applicable

Number of transmit error packets.

receive-errors

number

Not applicable

Number of receive error packets.

JSON Representation

{
"kind": "collection#vpn-statistics",
"items": [
{
"kind": "object#vpn-statistics",
"vpn-type": "site-to-site",
"vpn-interface-name": "{string}",
"local-address": "{ipaddress}",
"remote-address": "{ipaddress}",
"encapsulated": {number},
"decapsulated": {number},
"encrypted": {number},
"decrypted": {number},
"send-errors": {number},
"receive-errors": {number}
}
]

}

Example

JSON Request

GET /api/v1/vpn-svc/site-to-site/statistics
Accept: application/json

JSON Response

200 OK
 
Content-type: application/json
{
"kind": "collection#vpn-statistics",
"items": [
{
"kind": "object#vpn-statistics",
"vpn-type": "site-to-site",
"vpn-interface-name": "tunnel100",
"local-address": "10.10.10.1",
"remote-address": "13.13.13.1",
"encapsulated": 7767918,
"decapsulated": 7760812,
"encrypted": 7767918,
"decrypted": 7760812,
"send-errors": 0,
"receive-errors": 0
}
]
}
 

Remote Access VPN Server

To create the EzVPN server, the following objects need to be defined (other than the ike-policy, keyring and ipsec-profile that is already defined for P2P tunneling).

  • IP local address pool
  • Client-config-profile (this configuration is pushed to remote client once it connects)
  • Vtemplate (a dynamic tunnel is cloned once a remote client connects)
  • IKE profile (classifies who belongs to the group, and what policy to apply)

EzVPN Server

The CSR1000v supports the Easy VPN (EzVPN) server only. To create the EzVPN server, the following objects need to be defined (other than the ike-policy, keyring and ipsec-profile that is already defined for:

  • P2P tunneling).
  • IP local address pool
  • Client-config-profile (this configuration is pushed to remote client once it connects)
  • Vtemplate (a dynamic tunnel is cloned once a remote client connects)
  • IKE profile (classifies who belongs to the group, and what policy to apply)

Workflows

Create an EzVPN Server

1.blank.gif Create a keyring.

POST /api/v1/vpn-svc/ike/keyrings

See Create an IKE Keyring.

2.blank.gif (Optional) Create an IKE policy.

POST /api/v1/vpn-svc/ike/policies

See Create an IKE Policy.

3.blank.gif Create an IPSEC profile.

Include transform-set and ipsec profile.

POST /api/v1/vpn-svc/ipsec/policies

See Create an IPSec Policy.

4.blank.gif Create a local-pool. The local-pool is used to assign an address to the remote user.

POST /api/v1/vpn-svc/ezvpn/pools

See Create an IP Local Pool.

5.blank.gif (Required) Create a client-config-profile.

See EzVPN Client Config Profile.

6.blank.gif (Required) Create an IKE profile (cannot be a shared profile).

See IKE Profile.

7.blank.gif Configure the EzVPN server. This is the remote access endpoint. The server will refer to the IKE/IPSEC policy or profile. The server will create a virtual-template interface, which will be cloned by the DVTI interface during remote login.

See EzVPN Server Interface.

Resource Summary for EzVPN

 

Resource
URL
HTTP Methods

GET

POST

PUT

DELETE

Local pool

/api/v1/globle/local-pool/

Y

Y

Y

Y

Ike-profile

/api/v1/vpn-svc/ike/ike-profile/{ike-profile-id}

Y

N

Y

Y

all ike-profile

/api/v1/vpn-svc/ike/ike-profiles

Y

Y

N

N

Client-config profile

/api/v1/vpn-svc/ezvpn/client-config-profiles

Y

Y

Y

Y

EzVPN server

/api/v1/vpn-svc/ezvpn/ezvpn-servers

Y

Y

N

N

EzVPN server

/api/v1/vpn-svc/ezvpn/ezvpn-servers/{ezvpn-id}

Y

N

Y

Y

IP Local Pool

History

 

Release
Modification

IOS XE 3.11

Introduced for the CSR1000V platform

IOS XE 3.14

Introduced for ASR1001-X and ASR1002-X platforms

Properties

 

Property
Type
Required for POST and PUT
Description

pool-name

string

Mandatory

Pool name

ip-version

string

Optional

IPv4 format

start_address

string

Mandatory

Starting address

end_address

string

Mandatory

Ending address

JSON Representation for the IP Local Pool Command

{
"description" : "IP local pool",
"type":"object",
"properties":
{
"pool-name":{"type": "string"},
"ip-version":{"type":"string"},
"start-address":{"type":"string"},
"end-address":{"type":"string"},
}
}
 

Create an IP Local Pool

Example

JSON Request
POST /api/v1/vpn-svc/ezvpn/pools
Content-Type: application/json
 
{
"name":"pool1",
"start-address": "10.1.1.1",
"end-address":"10.1.1.255"
}
 

JSON Response

201 Created
Location: https://host/api/v1/vpn-svc/ezvpn/pools/pool1
 

Retrieve an IP Local Pool

Example

JSON Request
GET /api/v1/vpn-svc/ezvpn/pools/pool1
Accept: application/json
 

JSON Response

200 OK
Content-Type: application/json
 
{
"kind" : "object#local-pool",
"name" : "pool1",
"version" : "ipv4",
"start-address" : "10.1.1.1"
"end-address " : "10.1.1.255"
}
 

Delete an IP Local Pool

Example

JSON Request
DELETE /api/v1/ezvpn/pools/pool1
 

JSON Response

204 No Content

IKE Profile

History

 

Release
Modification

IOS XE 3.11

Introduced for the CSR1000V platform

IOS XE 3.14

Introduced for ASR1001-X and ASR1002-X platforms

JSON Representation for the ike-profile Resource

{
"description": "IKE profile",
"type": "object",
"properties":
{
"ike-profile-name": {"type": "string"},
"keyring": {"type": "string", "optional": true},
"identity":
{
"type": "object",
"category": {"type": "string",
"enum": ["group", "address", "host", "host domain",
"user", "user domain"]}
"value": {"type": "string"}
}
"authentication-list": {"type": "string", "optinal": true},
"authorization-list": {"type": "string", "optional": true},
"accounting": {"type": "string", "optional": true},
"client-group": {"type": "string", "optional": true},
"client-address":
{
"type": "string", "optional": true,
"enum": ["push", "on-demand", "both"]
},
"initiate-mode-aggressive": { "type": "boolean", "optional": true},
"keep-alive":
{
"type": "object", "optional": true,
"interval": {"type": "number", "min": 10, "max": 3600},
"retry": {"type": "number", "min": 2, "max": 60}
}
"vtemplate-if-name": {"type": "string", "optional": true},
}
}

EzVPN Client Config Profile

History

 

Release
Modification

IOS XE 3.11

Introduced for the CSR1000V platform

IOS XE 3.14

Introduced for ASR1001-X and ASR1002-X platforms

JSON Representation for ezvpn-client-config-profile Resource

{
"description": "client-config-profile",
"type": "object",
"properties":
{
"profile-name": {"type": "string"},
"pre-shared-key": {"type": "string"},
"dns-server":
{
"type": "object", "optional": true,
"primary": {
"type": "string", "format": "ip-address"},
"secondary": {
"type": "string", "format": "ip-address", "optional": true}
}
"nbms-wins-server":
{
"type": "object", "optional": true,
"primary": {
"type": "string", "format": "ip-address"},
"secondary": {
"type": "string", "format": "ip-address", "optional": true}
}
"split-tunnel-acl": {"type": "string", "optional": true},
"domain": {"type": "string", "optional": true},
"address-pool":
{
"type": "object",
"pool-name": {"type": "string"},
"prefix-len": {"type": "number"},
}
"client-banner": {"type": "string", "optional": true, "maxlength": 500},
}
}
 

EzVPN Server Interface

The virtual-template interface requirement allows a dynamic VTI interface to be cloned and provides the user with the ability to configure additional IOS features, such as a firewall, to EzVPN tunnels.

History

 

Release
Modification

IOS XE 3.11

Introduced for the CSR1000V platform

IOS XE 3.14

Introduced for ASR1001-X and ASR1002-X platforms

Properties

 

Property
Type
Required for POST and PUT
Description

description

string

Mandatory

Descriptive string for the EzVPN server.

vpn-type

string

Mandatory

"ezvpn"

vpn-interface-name

string

Mandatory

vtemplate name. If it does not exist, the system will create one.

ip-version

sting

Mandatory

IPv4

ike-profile-id

string

Mandatory

The ike-profile the server is going to use to negotiate with remote, it should include client-config file to push to remote.

ipsec-policy-id

string

Optional

IPSEC policy name

local-device

object

Mandatory

IP address of the vtemplate and IP address of the tunnel source.

ip-address

string

Mandatory

(sub-property of local-device)

Interface name or IP address of the vtemplate.

tunnel-ip-address

string

Mandatory

(sub-property of local-device)

Interface name (preferable) or IP address of the tunnel source.

JSON Representation for EzVPN-server Resource

{
"description":"string",
"vpn-type":"ezvpn",
"vpn-interface-name":"string",
"ip-version":"string",
"ike-profile-id":"string",
"ipsec-policy-id":"string",
"local-device":
{
"ip-address": "string",
"tunnel-ip-address":"string",
}
}
 

Create EzVPN Server Interface

Example

JSON Request

POST /api/v1/vpn-svc/ezvpn/servers
Content-Type: application/json
 
{ "vpn-type": "ezvpn",
"vpn-interface-name": "Virtual-Template11",
"ipsec-policy-id": "profile101",
"ike-profile-id": "ezvpn",
"local-device":
{
"ip-address": "loopback0",
"tunnel-ip-address": "gigabitethernet1"
}
}
 

JSON Response

201 Created
Location: https://host/api/v1/vpn-svc/ezvpn/servers/Virtual-Template11
 

Retrieve EzVPN Server Interface

Example

JSON Request

GET /api/v1/vpn-svc/ezvpn/servers/virtual-Template1
 
Accept: application/json

JSON Response

200 OK
Content-Type: application/json
 
{ "kind": "object#ezvpn-server",
"ip-version":"ipv4",
"vpn-type": "ezvpn",
"vpn-interface-name": "Virtual-Template11",
"ipsec-policy-id": "profile101",
"ike-profile-id": "ezvpn",
"local-device":
{
"ip-address" : "loopback0",
"tunnel-ip-address": "gigabitethernet1"
}
}
 

Delete EzVPN Server Interface

Example

JSON Request

DELETE /api/v1/vpn-svc/ezvpn/servers/Virtual-Template1

JSON Response

204 No Content