NLnetLabs-krill/doc/development/release_0_9/api_changes.md

API Changes Introduced in Release 0.9

In this release we removed the concept of 'embedded' CA parents and children, and embedded repositories. As a result some API changes were introduced.

Get RFC 8183 Child Request

The endpoints for getting the RFC Child Request XML and JSON have moved, and are now under 'id':

/api/v1/cas/<name>/child_request.xml  -> /api/v1/cas/<name>/id/child_request.xml
/api/v1/cas/<name>/child_request.json -> /api/v1/cas/<name>/id/child_request.json

Get RFC 8183 Publisher Request

The endpoints for getting the RFC Publisher Request XML and JSON have moved from 'repo', and are now under 'id':

/api/v1/cas/<name>/repo/request.xml  -> /api/v1/cas/<name>/id/publisher_request.xml
/api/v1/cas/<name>/repo/request.json -> /api/v1/cas/<name>/id/publisher_request.json

Add Child POST /cas/{ca_handle}/children

The JSON format no longer supports embedded and no longer include unused fields:

Old:

{
  "handle": "ca",
  "resources": {
    "asn": "AS1",
    "v4": "10.0.0.0/8",
    "v6": "::"
  },
  "auth": {
    "rfc8183": {
      "tag": null,
      "child_handle": "ca",
      "id_cert": "<base64>"
    }
  }
}

New:

{
  "handle": "ca",
  "resources": {
    "asn": "AS1",
    "v4": "10.0.0.0/8",
    "v6": "::"
  },
  "id_cert": "<base64>"
}

Add/Update Parent

There is no separate endpoint anymore for adding a named parent by posting XML to /api/v1/cas/<ca>/parents-xml/<parent-name>.

Instead adding a parent can be done by posting XML or JSON to: /api/v1/cas/<ca>/parents in which case the parent name will be extracted from the XML, or by posting to /api/v1/cas/<ca>/parents/<parent-name> in which case the parent name in the path will override the name in the submitted JSON or XML.

In all cases the server will verify that the parent can be reached, and if so, will add the parent if there was no parent for that name, or update the parent contact details in case there was.

When posting the LOCAL parent name can be included in the path, in which case it overrides the parent handle in submitted XML. If the parent name is included in the path and JSON is submitted, then an error will be returned if the names in the path and the JSON do not match.

Paths:

POST /cas/{ca_handle}/parents
POST /cas/{ca_handle}/parents/{parent_handle}

The JSON body has to include the local name by which the CA will refer to its parent, this is also the name shown to the user in the UI. The local name maps to the handle field in the JSON below. The second component is the contact. Krill used to support an embedded type, but this is no longer supported, so this structure MUST have "type": "rfc6492". We still have this type because we need to support the notion of a (test) Trust Anchor as well. The remainder of this structure maps to the RFC 8183 Parent Response XML, but then in JSON format. Note that the parent_handle is the handle that the parent wants the CA to use in messages sent to it - and it may be different from the local name stored in handle:

{
  "handle": "string",
  "contact": {
    "type": "rfc6492",
    "tag": null,
    "id_cert": "MIIDNDCCAhygAwIBAgIBATANBgkqhkiG9w0BAQsFADAzMTEwLwYDVQQDEyg5NjczMEUwQTg2MkE0RDkyNjQ1NEY5RTgzNzYxMzMzQkI0Qjc0QTVDMB4XDTIxMDMwNDE2MTQwNFoXDTM2MDMwNDE2MTkwNFowMzExMC8GA1UEAxMoOTY3MzBFMEE4NjJBNEQ5MjY0NTRGOUU4Mzc2MTMzM0JCNEI3NEE1QzCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAOCNekDo59PLdJnfiPg9kUycEb3EF17TnnUEKJaCunheH/brWakMumqpBox3H2fn1XY7e2e1SFezp52yqcIggLUOj3K49SvTzdDCCwA2MGuzaDHK6IhOuLKH9D9BqA2FTWVr3PNk77g+Bn1TfKF+G+JMr3jvDMkJAW9+58vnl7UJ/g+H6/lWqWAW1JeA3go9B+qdxC9DA02h+7vXPGhsVeUw688LFBv1fDGlQFX02zx0uNrKQQHddL1aJIM01i5M+N3uWJ5u3wCJRvxAr/P9KNtCO1sTFxR2dE/8W0+rfJWkAnDcgzeDCjznICF1146Thjxir08dYlj5YAeR3c5r5L8CAwEAAaNTMFEwDwYDVR0TAQH/BAUwAwEB/zAdBgNVHQ4EFgQUlnMOCoYqTZJkVPnoN2EzO7S3SlwwHwYDVR0jBBgwFoAUlnMOCoYqTZJkVPnoN2EzO7S3SlwwDQYJKoZIhvcNAQELBQADggEBAGUq4w7nv6Ez4kBdqfgyU0taKHgxIOTKJ6EwsDZj6eVGF6ThrutAonMVUeu1zs5ZW/uYaRWPffHzY8m1wdyrwYVw0HxRWY96vrhOOrVk32J6ip9V9bfFSjZLVnVcBz5V/odB++bJHhMoFNUaoqEGSNleiPotBtOHahlIL1EDEAt7bC5Kk7vEl0VmRJs7Hp1kpdZRJlVy7sLWL082hCJCulG57qL2UbsQ2wmFk+ImJ2RO3GSrNEI4//kHIw7GQFeeROfeb5HvyC/QOCzfBmMc/ipApuyzROSXHsE6CiaM2uWCjHs1NZBu+Za2EoFOhgYN1akeqqo50vRfO3Dd6Bm/rQY=",
    "parent_handle": "ta",
    "child_handle": "testbed",
    "service_uri": "https://localhost:3000/rfc6492/ta"
  }
}

Get Parent GET /cas/{ca_handle}/parents/{parent_handle}

Returns the parent contact with the type rfc6492 as an embedded field call type.

{
  "type": "rfc6492",
  "tag": null,
  "id_cert": "MIIDNDCCAhygAwIBAgIBATANBgkqhkiG9w0BAQsFADAzMTEwLwYDVQQDEyg5NjczMEUwQTg2MkE0RDkyNjQ1NEY5RTgzNzYxMzMzQkI0Qjc0QTVDMB4XDTIxMDMwNDE2MTQwNFoXDTM2MDMwNDE2MTkwNFowMzExMC8GA1UEAxMoOTY3MzBFMEE4NjJBNEQ5MjY0NTRGOUU4Mzc2MTMzM0JCNEI3NEE1QzCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAOCNekDo59PLdJnfiPg9kUycEb3EF17TnnUEKJaCunheH/brWakMumqpBox3H2fn1XY7e2e1SFezp52yqcIggLUOj3K49SvTzdDCCwA2MGuzaDHK6IhOuLKH9D9BqA2FTWVr3PNk77g+Bn1TfKF+G+JMr3jvDMkJAW9+58vnl7UJ/g+H6/lWqWAW1JeA3go9B+qdxC9DA02h+7vXPGhsVeUw688LFBv1fDGlQFX02zx0uNrKQQHddL1aJIM01i5M+N3uWJ5u3wCJRvxAr/P9KNtCO1sTFxR2dE/8W0+rfJWkAnDcgzeDCjznICF1146Thjxir08dYlj5YAeR3c5r5L8CAwEAAaNTMFEwDwYDVR0TAQH/BAUwAwEB/zAdBgNVHQ4EFgQUlnMOCoYqTZJkVPnoN2EzO7S3SlwwHwYDVR0jBBgwFoAUlnMOCoYqTZJkVPnoN2EzO7S3SlwwDQYJKoZIhvcNAQELBQADggEBAGUq4w7nv6Ez4kBdqfgyU0taKHgxIOTKJ6EwsDZj6eVGF6ThrutAonMVUeu1zs5ZW/uYaRWPffHzY8m1wdyrwYVw0HxRWY96vrhOOrVk32J6ip9V9bfFSjZLVnVcBz5V/odB++bJHhMoFNUaoqEGSNleiPotBtOHahlIL1EDEAt7bC5Kk7vEl0VmRJs7Hp1kpdZRJlVy7sLWL082hCJCulG57qL2UbsQ2wmFk+ImJ2RO3GSrNEI4//kHIw7GQFeeROfeb5HvyC/QOCzfBmMc/ipApuyzROSXHsE6CiaM2uWCjHs1NZBu+Za2EoFOhgYN1akeqqo50vRfO3Dd6Bm/rQY=",
  "parent_handle": "ta",
  "child_handle": "testbed",
  "service_uri": "https://localhost:3000/rfc6492/ta"
}

Show Repository GET /cas/{ca_handle}/repo

Since we no longer support embedded, the JSON format of the show repository API response has changed a bit. The JSON member rfc8181 now appears as repository_response. We still have a JSON member called contact, so that we remain a bit flexible in case we would like to include more information in future, next to which repository is configured.

Old:

{
  "contact": {
    "rfc8181": {
      "tag": null,
      "publisher_handle": "ca",
      "id_cert": "MIID..Vg==",
      "service_uri": "https://localhost:3000/rfc8181/ca",
      "repo_info": {
        "base_uri": "rsync://localhost/repo/ca/",
        "rpki_notify": "https://localhost:3000/rrdp/notificati.xml"
      }
    }
  }
}

New:

{
  "contact": {
    "repository_response": {
      "tag": null,
      "publisher_handle": "ca",
      "id_cert": "MIID..Vg==",
      "service_uri": "https://localhost:3000/rfc8181/ca",
      "repo_info": {
        "base_uri": "rsync://localhost/repo/ca/",
        "rpki_notify": "https://localhost:3000/rrdp/notificati.xml"
      }
    }
  }
}

Add or Update Repository POST /cas/{ca_handle}/repo

To add or update the repository the RFC 8183 Repository Response needs to be submitted, either as XML, or in JSON format. The JSON format no longer supports embedded, so the following is no longer supported:

Old:

{
  "tag": "string",
  "id_cert": "string",
  "child_handle": "string"
}

New:

{
  "repository_response": {
    "tag": null,
    "publisher_handle": "publisher",
    "id_cert": "MIID..6g==",
    "service_uri": "https://repo.example.com/rfc8181/publisher/",
    "repo_info": {
      "base_uri": "rsync://localhost/repo/ca/",
      "rpki_notify": "https://localhost:3000/rrdp/notification.xml"
    }
  }
}