From fb9648640243febffb3d80b2e1a5d425f16c3ef0 Mon Sep 17 00:00:00 2001 From: Andrew Donkin Date: Fri, 13 Oct 2023 09:43:23 +1300 Subject: [PATCH] PIV love --- ref/cardholders.html | 1 + ref/piv.html | 27 ++++++++++++++------------- swagger/cardholdersApi.yaml | 5 ++++- swagger/pivApi.yaml | 33 +++++++++++++++++++-------------- 4 files changed, 38 insertions(+), 28 deletions(-) diff --git a/ref/cardholders.html b/ref/cardholders.html index a8bc564..76d9d3c 100644 --- a/ref/cardholders.html +++ b/ref/cardholders.html @@ -14415,6 +14415,7 @@

All credential types have a set of card states.

+

If you need this, ask for it using the fields parameter.

diff --git a/ref/piv.html b/ref/piv.html index 7998131..5dde7f3 100644 --- a/ref/piv.html +++ b/ref/piv.html @@ -90,10 +90,10 @@

Finding the PIV card type

When you assign any card to a cardholder, PIV or otherwise, you need to provide the identifier of the card type. It will vary between Command Centre installations, so you cannot use a value from another installation or these examples. It will not change while Command Centre is running but it may change at upgrade, so your application should follow this process at startup.

It takes two queries and a loop:

    -
  1. GET /api,
    2. -
  2. if running 8.00 or earlier, follow the link at features.cardTypes.cardTypes.href (which will be to /api/card_types), or
    3. -
  3. if running 8.10 or later, follow the link at features.cardTypes.assign.href (which will probably be to /api/card_types/assign. Both URLs will work in 8.10, but the advantage of this URL is that your operator can access it with fewer privileges),
    4. -
  4. iterate through the array to find the element with credentialClass: piv, and
    5. +
  5. GET /api.
    6. +
  6. If running 8.00 or earlier, follow the link at features.cardTypes.cardTypes.href (which will be to /api/card_types), or
    7. +
  7. if running 8.10 or later, follow the link at features.cardTypes.assign.href (which will probably be to /api/card_types/assign. Both URLs will work in 8.10, but the advantage of this URL is that your operator can access it at a lower privilege level).
    8. +
  8. Iterate through the array to find the element with credentialClass: piv, and
  9. note its href.

You can accomplish the last two steps with the JSONPath filter

@@ -106,7 +106,7 @@

Finding the URL of a cardholder

See the main cardholder documentation, particularly the section on searching cardholders.

Licensing

-

All of the API calls described here require the RESTCardholders licence. If your site is also licensed to use PIV cards, you can access them via REST.

+

All of the API calls described here require the RESTCardholders licence. If your site is also licensed to use PIV cards, you can access those cards via REST.

Cardholder API changes in 8.10

  • Certificates and biometric data are now available without a customisation. They are too large to send to all REST clients so you must ask for them using the fields parameter.
    • @@ -775,7 +775,7 @@

    In addition to the generic card data the API always returns in the cards section (in the Cardholders API document) of a cardholder detail page, including href, number, issueLevel, type, and status, PIV cards have a pivData structure.

    -

    In version 8.00 and later, credentialClass will be 'piv'.

    +

    In version 8.00 and later you can check for the value piv on credentialClass.

    @@ -786,8 +786,8 @@

-

There is no difference between the href of a PIV card and any other. DELETE it to delete a card. That is the only verb you can use on this URL. GET will always return a 404.

-

Do not specify it when creating a card.

+

This is the same as the href to a card of any other type: you can send an HTTP DELETE to it to delete the card, but that is the only verb that will work. GET will return a 404.

+

Do not specify it when creating a card, since it is the creation process that generates its href.

number: @@ -795,7 +795,7 @@

-

While the card number rules on a PIV card type are different from those on non-PIV card types, card numbers are still strings, and the API will accept them from you and return them to you in the same way.

+

While the card number rules on a PIV or PIV-I card type are different from those on other types, card numbers are still strings, and the API will accept them from you and return them to you in the same way.

PIV card numbers are the FASC-N with hyphens splitting the major components.

PIV-I card numbers are the CHUID's GUID in decimal.

@@ -980,7 +980,8 @@

-

All credential types have a set of card states. PIV cards have two.

+

All credential types have a set of card states. The set assigned to PIV cards contains only two.

+

If you need this, ask for it using the fields parameter.

@@ -1004,7 +1005,7 @@

-

You are after the card type with credential class 'piv'.

+

PIV card types have the credential class 'piv'.

@@ -1045,7 +1046,7 @@

This example, when placed inside the cards array of a POST or the cards.add array of a - PATCH, would create a PIV card credential and assign it to the cardholder created by the POST or identified by the address of the PATCH. Consult those methods for the JSON you need to wrap around this example.

+ PATCH, would create a PIV credential and assign it to the cardholder created by the POST or identified by the address of the PATCH. Consult those methods for the JSON you need to wrap around this example.

A PIV-I example would have a different style of FASC-N, and a card number to match.

@@ -1089,7 +1090,7 @@

-

This block contains all the PIV-specific fields. Everything outside this block, including the number, status, and type, is common to all Command Centre cards and credentials.

+

This block contains all the PIV-specific fields. Everything outside this block, including the number, status, and type, is common to all types of Command Centre cards and credentials.

diff --git a/swagger/cardholdersApi.yaml b/swagger/cardholdersApi.yaml index 361d2cb..0289dba 100644 --- a/swagger/cardholdersApi.yaml +++ b/swagger/cardholdersApi.yaml @@ -4693,7 +4693,10 @@ definitions: availableCardStates: type: array items: {type: string, enum: ['Active', 'Disabled (manually)', 'Lost', 'Stolen', 'Damaged']} - description: All credential types have a set of card states. + description: | + All credential types have a set of card states. + + If you need this, ask for it using the `fields` parameter. example: - "Active" - "Disabled (manually)" diff --git a/swagger/pivApi.yaml b/swagger/pivApi.yaml index a81f18f..8a2bcf9 100644 --- a/swagger/pivApi.yaml +++ b/swagger/pivApi.yaml @@ -40,13 +40,13 @@ info: It takes two queries and a loop: - 1. `GET /api`, - 2. if running 8.00 or earlier, follow the link at `features.cardTypes.cardTypes.href` (which + 1. `GET /api`. + 2. If running 8.00 or earlier, follow the link at `features.cardTypes.cardTypes.href` (which will be to `/api/card_types`), or 2. if running 8.10 or later, follow the link at `features.cardTypes.assign.href` (which will probably be to `/api/card_types/assign`. Both URLs will work in 8.10, but the advantage of - this URL is that your operator can access it with fewer privileges), - 3. iterate through the array to find the element with `credentialClass: piv`, and + this URL is that your operator can access it at a lower privilege level). + 3. Iterate through the array to find the element with `credentialClass: piv`, and 4. note its `href`. You can accomplish the last two steps with the JSONPath filter @@ -69,7 +69,7 @@ info: ### Licensing All of the API calls described here require the RESTCardholders licence. If your site is also - licensed to use PIV cards, you can access them via REST. + licensed to use PIV cards, you can access those cards via REST. ### Cardholder API changes in 8.10 @@ -328,7 +328,7 @@ definitions: detail page, including `href`, `number`, `issueLevel`, `type`, and `status`, PIV cards have a `pivData` structure. - In version 8.00 and later, `credentialClass` will be 'piv'. + In version 8.00 and later you can check for the value `piv` on `credentialClass`. properties: href: @@ -336,15 +336,16 @@ definitions: format: url example: "https://localhost:8904/api/cardholders/325/cards/6284082f7ba5eb1" description: | - There is no difference between the href of a PIV card and any other. DELETE it to delete - a card. That is the only verb you can use on this URL. GET will always return a 404. + This is the same as the href to a card of any other type: you can send an HTTP DELETE to + it to delete the card, but that is the only verb that will work. GET will return a 404. - Do not specify it when creating a card. + Do not specify it when creating a card, since it is the creation process that generates + its href. number: type: string example: "3165-4313-245789-098765432113456799" description: | - While the card number rules on a PIV card type are different from those on non-PIV card + While the card number rules on a PIV or PIV-I card type are different from those on other types, card numbers are still strings, and the API will accept them from you and return them to you in the same way. @@ -432,7 +433,11 @@ definitions: availableCardStates: type: array items: {type: string, enum: ['Active', 'Disabled (manually)']} - description: All credential types have a set of card states. PIV cards have two. + description: | + All credential types have a set of card states. The set assigned to PIV cards contains + only two. + + If you need this, ask for it using the `fields` parameter. example: - "Active" - "Disabled (manually)" @@ -440,13 +445,13 @@ definitions: type: string enum: [ "piv", "card", "mobile"] example: piv - description: You are after the card type with credential class 'piv'. + description: PIV card types have the credential class 'piv'. PIV card create example: description: | This example, when placed inside the `cards` array of a [POST](cardholders.html#operation--api-cardholders-post) or the `cards.add` array of a - [PATCH](cardholders.html#operation--api-cardholders--id--patch), would create a PIV card + [PATCH](cardholders.html#operation--api-cardholders--id--patch), would create a PIV credential and assign it to the cardholder created by the POST or identified by the address of the PATCH. Consult those methods for the JSON you need to wrap around this example. @@ -483,7 +488,7 @@ definitions: pivData: description: | This block contains all the PIV-specific fields. Everything outside this block, including - the number, status, and type, is common to all Command Centre cards and credentials. + the number, status, and type, is common to all types of Command Centre cards and credentials. $ref: '#/definitions/PIV card data' PIV card update example: