How to Provision a BYOIP Prefixpublic

Bring your own network prefix of IPv4 addresses to DigitaOcean by creating a signed certificate, updating your Regional Internet Registry (RIR) records, and submitting a signed provisioning request via the DigitalOcean API.

The full process is:

1. Create a private ECC (or RSA) key and use it to sign an X.509 certificate
2. Add the X.509 certificate to your RIR’s public records
3. Create a specially formatted message containing your DigitalOcean account UUID and your IPv4 prefix information
4. Sign the message using the private key you generated
5. Submit a provisioning request via the API with the following information:

• Your IPv4 prefix in CIDR format
• The signature hash you generated in step 4
• The datacenter region (for example: nyc3) to place the IPs in

Follow the detailed instructions below to bring your IPs to DigitalOcean.

Prerequisites

• You must request access to BYOIP by clicking the Request access link at the bottom of the Reserved IPs page in the control panel.

• You must possess direct control and update authority over a block of IPv4 addresses within your RIR. You acknowledge and agree that you have all the necessary rights to use the BYOIP IP address you are provisioning. DigitalOcean is not responsible for any third-party claims related to your use of BYOIP IP addresses on our services.

• The prefix must be registered with one of the following Regional Internet Registries:

  • American Registry for Internet Numbers (ARIN)
  • Réseaux IP Européens Network Coordination Centre (RIPE NCC)
  • Asia Pacific Network Information Centre (APNIC)
  • African Network Information Centre (AFRINIC)
  • Latin America and Caribbean Network Information Centre (LACNIC)

• You must be able to log in to your RIR and update your IPv4 prefix’s public records.

• You need access to UNIX command line tools including doctl, openssl, and rdap.

Generate the X.509 Certificate

First generate an ECC private key using openssl.

openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-384 -out private_key.pem

openssl genpkey -quiet -algorithm RSA -pkeyopt rsa_keygen_bits:4096 -out private_key.pem

The private key is saved as private_key.pem.

Use the private key to create a new X.509 certificate. Filling out the certificate fields is optional.

openssl req -new -x509 -key private_key.pem -days 365 -out x509_certificate.pem

The certificate is saved as x509_certificate.pem. Use the tr utility to remove all newline characters from the X.509 certificate.

cat x509_certificate.pem | tr -d "\n" > encoded_x509_certificate.pem

The final certificate file is encoded_x509_certificate.pem.

Add the X.509 Certificate to Your RIR

Add the X.509 certificate to your IPv4 prefix’s public records under IP Network → Remarks → Description. Find your RIR below for detailed instructions.

APNIC

Go to the APNIC website and log in to your account.

When logged in, find the Resource Manager menu item at the top of the page and navigate to Resource Manager, Internet Resources, then IPv4.

This lists all of your IPv4 resources. Select the prefix you would like to use for BYOIP, then select the subnet.

Scroll down to the bottom of the subnet’s page and add a descr field.

Once you’ve added the descr field, paste the contents of encoded_x509_certificate.pem into the descr text box, then scroll down and click the Update button.

Continue to the Verify the Certificate Records section to check that the update is successful.

ARIN

Go to the ARIN website and log in to your account.

Once logged in to the ARIN account manager, navigate to the Dashboard using the user menu in the upper-right.

In the Dashboard drop-down, go to IP Addresses, then Manage Networks

Click the Net Handle of the subnet you would like to use for BYOIP. This brings you to details about the subnet. Click the Actions drop-down menu and select Modify to edit the subnet.

In the Public Comments text box, paste the contents of the encoded_x509_certificate.pem file, then click Submit.

Continue to the Verify the Certificate Records section to check that the update is successful.

RIPE NCC

Go to the RIPE website and log in to your account.

Once logged in, click on LIR Portal.

In the LIR Portal, click Resources in the left menu.

In My Resources, click on the IPv4 tab.

Find the prefix that you would like to use for BYOIP and click it. This brings you to details about the prefix. Click the Update object button to edit.

Scroll down and find the descr text box. Paste the contents of encoded_x509_certificate.pem into the box, then click Submit.

Continue to the Verify the Certificate Records section to check that the update is successful.

AFRINIC

Log in to your African Network Information Centre account and add your X.509 certificate to the prefix’s RDAP records under the hierarchy IP Network, Remarks, Description.

See the AFRINIC RDAP page for more information about their RDAP service.

Continue to the Verify the Certificate Records section to check that the update is successful.

LACNIC

Log in to your Latin America and Caribbean Network Information Centre account and add your X.509 certificate to the prefix’s RDAP records under the hierarchy IP Network, Remarks, Description.

Continue to the Verify the Certificate Records section to check that the update is successful.

Verify the Certificate Records

Once you’ve added the certificate to your RIR, use the rdap command followed by your IP prefix to verify the RIR setup is complete.

rdap <your_prefix_in_CIDR_notation>

Replace <your_prefix_in_CIDR_notation> with your own prefix in CIDR notation.

This command prints all of your prefix’s RADP information to the console. You should find your certificate under the following hierarchy: IP Network, Remarks, Description.

Generate the Signature Hash

In this step, you create a signed message hash that verifies you control both your DigitalOcean account and your prefix.

First use doctl to list all of your DigitalOcean teams and their UUIDs.

doctl account get -o json

This outputs JSON with your account information:

{
  "droplet_limit": 500,
  "floating_ip_limit": 250,
  "reserved_ip_limit": 250,
  "volume_limit": 5000,
  "email": "[email protected]",
  "name": "Sammy",
  "uuid": "412c39ba-****-****-*****-a7f9776ed4e4",
  "email_verified": true,
  "status": "active",
  "team": {
    "name": "Sammy Engineering",
    "uuid": "2dba95607b7fcee***************ad0643f357"
  }
}

Find the uuid of the team you wish to use, then use the uuid to create the message for signing:

echo -n "DO|<team_uuid>|<your_prefix_in_CIDR_notation>" > message.txt

Substitute the following information:

• <team_uuid>: the team UUID found in the previous step
• <your_prefix_in_CIDR_notation>: your IP prefix in CIDR notation

The full message is output to the file message.txt.

Now sign the message using the private key you generated in the first step.

openssl dgst -sign private_key.pem -keyform pem -sha256 -out signature_file.txt message.txt

Finally, base64 encode the signature.

cat signature_file.txt | openssl base64 | tr -- '+=/' '-_~' | tr -d "\n" > encoded_signature_file.txt

The next step explains how to submit encoded_signature_file.txt to DigitalOcean to complete your provisioning request.

Submit Your Provisioning Request

During the public preview, BYOIP provisioning requests must be submitted using doctl or the DigitalOcean API.

Submit Your Provisioning Request Using the CLI

Use the doctl compute byoip-prefix create command to send the provisioning request:

doctl compute byoip-prefix create \
  --prefix <your_prefix_in_CIDR_notation> \
  --region <your_region> \
  --signature "$(cat encoded_signature_file.txt)"

This example uses cat to pull the signature value from encoded_signature_file.txt. Update <your_prefix_in_CIDR_notation> and <your_region> to match the details of your prefix and your desired region.

The command responds with an id for your BYOIP prefix. Use this ID to query the status of your provisioning request, or to deprovision the prefix.

Submit Your Provisioning Request Using the API

The BYOIP provisioning API call is a POST request to https://api.digitalocean.com/v2/byoip_prefixes with a JSON payload similar to the following:

{
  "prefix":"<your_prefix_in_CIDR_notation>",
  "region":"<your_region>",
  "signature":"<your_signature_from_encoded_signature_file>"
}

The following curl command calls the provisioning endpoint:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"prefix":"<your_prefix_in_CIDR_notation>","region":"<your_region>","signature":"<your_signature_from_encoded_signature_file>"}' \
  "https://api.digitalocean.com/v2/byoip_prefixes"

Update <your_prefix_in_CIDR_notation>, <your_region>, and <your_signature_from_encoded_signature_file> to match the details of your prefix, desired region, and signature.

The API responds with an id for your byoip_prefix:

{"byoip_prefix":{"id":"95ad6673-a359-400d-8095-9f6589746d78"}}

Use this ID to query the status of your provisioning request, or to deprovision the prefix.

Get the Status of a Provisioning Request

After submitting your BYOIP provisioning request, your prefix is listed in the Networking section of the control panel under the Reserved IPs tab. BYOIP prefixes have a status of Provisioning while still provisioning, and Active when they are ready to be used.

You can also use the doctl CLI or DigitalOcean API to get the status of your prefix.

Get the Status of a Provisioning Request Using the CLI

Use doctl compute byoip-prefix get and the ID of your prefix to get its current status:

doctl compute byoip-prefix get <your_prefix_id>

Update <your_prefix_id> with the ID returned when you created the provisioning request. The command returns a table with information about the provisioning request, including a Status column which is in_progress until the process is complete.

Get the Status of a Provisioning Request Using the API

Send a GET request to the /v2/byoip_prefixes/<your_prefix_id> endpoint:

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/byoip_prefixes/<your_prefix_id>"

Update <your_prefix_id> with the ID returned when you created the provisioning request. The API returns a JSON object with information about the provisioning request, including a status key which is in_progress until the process is complete.

How To Use BYOIP Addresses

BYOIP addresses are assigned, reassigned, and unassigned using the existing reserved IP interface and APIs. Read the reserved IP docs on reassigning and unassigning to get started.

You cannot delete BYOIP addresses, but you can deprovision the entire prefix. See How to Deprovision BYOIP Addresses.

Network Operations Communication Expectations

DigitalOcean contacts you via your Solutions Architect should our network operations team detect any anomaly (like an RPKI issue or route hijack) regarding the announcement of your BYOIP prefixes to the Internet.

Failure to remediate the issue within one business day from its start – irrespective of your responsiveness – results in termination of BYOIP service for the prefix in question. Termination of BYOIP service means a complete withdrawal of the BYOIP prefix from AS14061’s advertisements to the internet.