Skip to content

Commit

Permalink
PIV love
Browse files Browse the repository at this point in the history
  • Loading branch information
@AndrewDonkin-Gallagher
AndrewDonkin-Gallagher committed Oct 12, 2023
1 parent 29b7c10 commit fb96486
Show file tree
Hide file tree
Showing 4 changed files with 38 additions and 28 deletions.
1 change: 1 addition & 0 deletions ref/cardholders.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14415,6 +14415,7 @@ <h2 class="panel-title">
</dt>
<dd>
<p>All credential types have a set of card states.</p>
<p>If you need this, ask for it using the <code>fields</code> parameter.</p>
</dd>
<dt class="json-inner-schema">
<section class="json-schema-array-items">
Expand Down
27 changes: 14 additions & 13 deletions ref/piv.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -90,10 +90,10 @@ <h3 id="finding-the-piv-card-type">Finding the PIV card type</h3>
<p>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.</p>
<p>It takes two queries and a loop:</p>
<ol>
<li><code>GET /api</code>,</li>
<li>if running 8.00 or earlier, follow the link at <code>features.cardTypes.cardTypes.href</code> (which will be to <code>/api/card_types</code>), or</li>
<li>if running 8.10 or later, follow the link at <code>features.cardTypes.assign.href</code> (which will probably be to <code>/api/card_types/assign</code>. Both URLs will work in 8.10, but the advantage of this URL is that your operator can access it with fewer privileges),</li>
<li>iterate through the array to find the element with <code>credentialClass: piv</code>, and</li>
<li><code>GET /api</code>.</li>
<li>If running 8.00 or earlier, follow the link at <code>features.cardTypes.cardTypes.href</code> (which will be to <code>/api/card_types</code>), or</li>
<li>if running 8.10 or later, follow the link at <code>features.cardTypes.assign.href</code> (which will probably be to <code>/api/card_types/assign</code>. 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).</li>
<li>Iterate through the array to find the element with <code>credentialClass: piv</code>, and</li>
<li>note its <code>href</code>.</li>
</ol>
<p>You can accomplish the last two steps with the JSONPath filter</p>
Expand All @@ -106,7 +106,7 @@ <h3 id="finding-the-url-of-a-cardholder">Finding the URL of a cardholder</h3>
<p>See the main cardholder documentation, particularly the section on
<a href="cardholders.html#operation--api-cardholders-get">searching cardholders</a>.</p>
<h3 id="licensing">Licensing</h3>
<p>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.</p>
<p>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.</p>
<h3 id="cardholder-api-changes-in-810">Cardholder API changes in 8.10</h3>
<ul>
<li>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 <code>fields</code> parameter.</li>
Expand Down Expand Up @@ -775,7 +775,7 @@ <h2 class="panel-title">
<section class="json-schema-description">
<p>In addition to the generic card data the API always returns in the cards section (in the
<a href="cardholders.html#definition-Cardholder-card">Cardholders API document</a>) of a cardholder detail page, including <code>href</code>, <code>number</code>, <code>issueLevel</code>, <code>type</code>, and <code>status</code>, PIV cards have a <code>pivData</code> structure.</p>
<p>In version 8.00 and later, <code>credentialClass</code> will be &#39;piv&#39;.</p>
<p>In version 8.00 and later you can check for the value <code>piv</code> on <code>credentialClass</code>.</p>
</section>
<section class="json-schema-properties">
<dl>
Expand All @@ -786,16 +786,16 @@ <h2 class="panel-title">
<span class="json-property-range" title="Value limits"></span>
</dt>
<dd>
<p>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.</p>
<p>Do not specify it when creating a card.</p>
<p>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.</p>
<p>Do not specify it when creating a card, since it is the creation process that generates its href.</p>
</dd>
<dt data-property-name="number" class="has-description">
<span class="json-property-name">number:</span>
<span class="json-property-type">string</span>
<span class="json-property-range" title="Value limits"></span>
</dt>
<dd>
<p>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.</p>
<p>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.</p>
<p>PIV card numbers are the FASC-N with hyphens splitting the major components.</p>
<p>PIV-I card numbers are the CHUID&#39;s GUID in decimal.</p>
</dd>
Expand Down Expand Up @@ -980,7 +980,8 @@ <h2 class="panel-title">
<span class="json-property-range" title="Value limits"></span>
</dt>
<dd>
<p>All credential types have a set of card states. PIV cards have two.</p>
<p>All credential types have a set of card states. The set assigned to PIV cards contains only two.</p>
<p>If you need this, ask for it using the <code>fields</code> parameter.</p>
</dd>
<dt class="json-inner-schema">
<section class="json-schema-array-items">
Expand All @@ -1004,7 +1005,7 @@ <h2 class="panel-title">
<span class="json-property-range" title="Value limits"></span>
</dt>
<dd>
<p>You are after the card type with credential class &#39;piv&#39;.</p>
<p>PIV card types have the credential class &#39;piv&#39;.</p>
</dd>
</dl>
</section>
Expand Down Expand Up @@ -1045,7 +1046,7 @@ <h2 class="panel-title">
<section class="json-schema-description">
<p>This example, when placed inside the <code>cards</code> array of a
<a href="cardholders.html#operation--api-cardholders-post">POST</a> or the <code>cards.add</code> array of a
<a href="cardholders.html#operation--api-cardholders--id--patch">PATCH</a>, 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.</p>
<a href="cardholders.html#operation--api-cardholders--id--patch">PATCH</a>, 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.</p>
<p>A PIV-I example would have a different style of FASC-N, and a card number to match.</p>
</section>
<section class="json-schema-properties">
Expand Down Expand Up @@ -1089,7 +1090,7 @@ <h2 class="panel-title">
<span class="json-property-range" title="Value limits"></span>
</dt>
<dd>
<p>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.</p>
<p>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.</p>
</dd>
</dl>
</section>
Expand Down
5 changes: 4 additions & 1 deletion swagger/cardholdersApi.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)"
Expand Down
33 changes: 19 additions & 14 deletions swagger/pivApi.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -328,23 +328,24 @@ 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:
type: string
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.
Expand Down Expand Up @@ -432,21 +433,25 @@ 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)"
credentialClass:
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.
Expand Down Expand Up @@ -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:
Expand Down

0 comments on commit fb96486

Please sign in to comment.