[RFC,2/6] doc: add opal secvar documentation

This patch contains all the relevant documentation for the secure variable
support in OPAL. This may be split and squashed with their relevant
implementations in the future, but kept separate for now.

Notably missing at the moment is the documentation for the SECBOOT PNOR
partition usage, which will be included in a future revision.

Signed-off-by: Eric Richter <erichte@linux.ibm.com>
---
 doc/opal-api/opal-secvar.rst | 199 +++++++++++++++++++++++++++++++++++
 1 file changed, 199 insertions(+)
 create mode 100644 doc/opal-api/opal-secvar.rst

On Fri, Mar 29, 2019 at 9:18 AM Eric Richter <erichte@linux.ibm.com> wrote:
>
> This patch contains all the relevant documentation for the secure variable
> support in OPAL. This may be split and squashed with their relevant
> implementations in the future, but kept separate for now.
>
> Notably missing at the moment is the documentation for the SECBOOT PNOR
> partition usage, which will be included in a future revision.
>
> Signed-off-by: Eric Richter <erichte@linux.ibm.com>
> ---
>  doc/opal-api/opal-secvar.rst | 199 +++++++++++++++++++++++++++++++++++
>  1 file changed, 199 insertions(+)
>  create mode 100644 doc/opal-api/opal-secvar.rst
>
> diff --git a/doc/opal-api/opal-secvar.rst b/doc/opal-api/opal-secvar.rst
> new file mode 100644
> index 00000000..fd66e5e2
> --- /dev/null
> +++ b/doc/opal-api/opal-secvar.rst
> @@ -0,0 +1,199 @@
> +OPAL_SECVAR_GET
> +===============
> +::
> +
> +   #define OPAL_SECVAR_GET                         170
> +
> +``OPAL_SECVAR_GET`` call retrieves a data blob associated with the supplied
> +name and vendor guid.
> +
> +Parameters
> +----------
> +::
> +
> +   uint64_t k_name
> +   uint64_t k_vendor
> +   uint64_t k_attributes
> +   uint64_t k_data_size
> +   uint64_t k_data

Why is everything prefixed with k_ ?

> +
> +``k_name``
> +   the name of the requested variable as a 16-bit char
> +
> +``k_vendor``
> +   the vendor guid of the requested variable
> +
> +``k_attributes``
> +   optional bitfield reference to be set by OPAL for attributes
> +related to the variable data
> +
> +``k_data_size``
> +   reference to the size of the ``k_data`` buffer. OPAL sets this if
> +the buffer size is insufficient for the requested variable
> +
> +``k_data``
> +   return buffer to store the data blob of the requested variable if
> +a match was found
> +
> +Return Values
> +-------------
> +
> +``OPAL_SUCCESS``
> +   data from the requested variable was copied successfully, or
> +``k_data`` was set to NULL and the ``k_data_size`` was set to the
> +requested variable's size
> +
> +``OPAL_PARAMETER``
> +   ``k_name``, ``k_vendor`` or ``k_data_size`` are invalid buffers,
> +contain invalid values
> +
> +``OPAL_EMPTY``
> +   no variable with the supplied ``k_name`` and ``k_vendor`` was found
> +
> +``OPAL_PARTIAL``
> +   the buffer size provided in ``k_data_size`` is too small for the
> +requested variable
> +
> +``OPAL_HARDWARE``
> +   secure variable support is disabled
> +
> +OPAL_SECVAR_GET_NEXT
> +====================
> +::
> +
> +   #define OPAL_SECVAR_GET_NEXT                        171
> +
> +``OPAL_SECVAR_GET_NEXT`` returns the name and vendor guid of the next
> +variable in the secure variable bank in sequence.
> +
> +Parameters
> +----------
> +::
> +
> +   uint64_t k_name_size
> +   uint64_t k_name
> +   uint64_t k_vendor
> +
> +``k_name_size``
> +   size of the ``k_name`` buffer. OPAL sets this to the size of the
> +next variable in sequence
> +
> +``k_name``
> +   name of the previous variable or empty. The name of the next
> +variable in sequence will be copied to ``k_name``
> +
> +``k_vendor``
> +   vendor guid of the previous variable or empty. The vendor of the
> +next vendor in sequence will be copied to ``k_vendor``
> +
> +Return Values
> +-------------
> +
> +``OPAL_SUCCESS``
> +  the name and vendor of the next variable in sequence was copied
> +successfully
> +
> +``OPAL_PARAMETER``
> +  ``k_name`` or ``k_vendor`` are invalid buffers, or were not found.
> +``k_name_size`` is an invalid value. A variable matching
> +the supplied non-empty ``k_name`` and ``k_vendor`` was not found
> +
> +``OPAL_EMPTY``
> +  end of list reached
> +
> +``OPAL_PARTIAL``
> +  the size specified in ``k_name_size`` is insufficient for the next
> +variable's name size
> +
> +``OPAL_HARDWARE``
> +  secure variable support is disabled
> +
> +OPAL_SECVAR_ENQUEUE
> +===================
> +::
> +
> +   #define OPAL_SECVAR_ENQUEUE                        172
> +
> +``OPAL_SECVAR_ENQUEUE`` call appends the supplied variable data to the
> +queue for processing on next boot.
> +
> +Parameters
> +----------
> +::
> +
> +   uint64_t k_name
> +   uint64_t k_vendor
> +   uint64_t k_attributes
> +   uint64_t k_data_size
> +   uint64_t k_data
> +
> +``k_name``
> +   the name of the submitted variable as a 16-bit char
> +
> +``k_vendor``
> +   the vendor guid of the submitted variable
> +
> +``k_attributes``
> +   bitfield of attributes
> +
> +``k_data_size``
> +   size of the buffer to copy from ``k_data``
> +
> +``k_data``
> +   blob of data to be stored
> +
> +Return Values
> +-------------
> +
> +``OPAL_SUCCESS``
> +   the variable was appended to the update queue bank successfully
> +
> +``OPAL_PARAMETER``
> +   ``k_name``, ``k_vendor`` or ``k_data`` are invalid buffers.
> +``k_name`` is empty. ``k_data_size`` is an invalid value.
> +
> +``OPAL_NO_MEM``
> +   OPAL was unable to allocate memory for the variable
> +
> +``OPAL_UNSUPPORTED``
> +   ``k_data_size`` was set to zero, implying an empty ``k_data`` buffer
> +(may be used for variable deletion in the future)
> +
> +``OPAL_HARDWARE``
> +   secure variable support is disabled
> +
> +OPAL_SECVAR_INFO
> +================
> +::
> +
> +   #define OPAL_SECVAR_INFO                        173
> +
> +``OPAL_SECVAR_INFO`` returns size information about the variable
> +storage. Not currently implemented.
> +
> +Parameters
> +----------
> +::
> +
> +   uint64_t k_attributes
> +   uint64_t k_storage_space
> +   uint64_t k_remaining_space
> +   uint64_t k_max_variable_size
> +
> +``k_attributes``
> +   TODO
> +
> +``k_storage_space``
> +   maximum storage space in bytes
> +
> +``k_remaining_space``
> +   remaining storage space in bytes
> +
> +``k_max_variable_size``
> +   maximum acceptable size for a data blob
> +
> +Return Values
> +-------------
> +
> +``OPAL_UNSUPPORTED``
> +  Runtime service is currently a stub, not currently implemented.
> --
> 2.17.2
>
> _______________________________________________
> Skiboot mailing list
> Skiboot@lists.ozlabs.org
> https://lists.ozlabs.org/listinfo/skiboot

On 3/28/19 8:15 PM, Oliver wrote:
> On Fri, Mar 29, 2019 at 9:18 AM Eric Richter <erichte@linux.ibm.com> wrote:
>>
>> This patch contains all the relevant documentation for the secure variable
>> support in OPAL. This may be split and squashed with their relevant
>> implementations in the future, but kept separate for now.
>>
>> Notably missing at the moment is the documentation for the SECBOOT PNOR
>> partition usage, which will be included in a future revision.
>>
>> Signed-off-by: Eric Richter <erichte@linux.ibm.com>
>> ---
>>   doc/opal-api/opal-secvar.rst | 199 +++++++++++++++++++++++++++++++++++
>>   1 file changed, 199 insertions(+)
>>   create mode 100644 doc/opal-api/opal-secvar.rst
>>
>> diff --git a/doc/opal-api/opal-secvar.rst b/doc/opal-api/opal-secvar.rst
>> new file mode 100644
>> index 00000000..fd66e5e2
>> --- /dev/null
>> +++ b/doc/opal-api/opal-secvar.rst
>> @@ -0,0 +1,199 @@
>> +OPAL_SECVAR_GET
>> +===============
>> +::
>> +
>> +   #define OPAL_SECVAR_GET                         170
>> +
>> +``OPAL_SECVAR_GET`` call retrieves a data blob associated with the supplied
>> +name and vendor guid.
>> +
>> +Parameters
>> +----------
>> +::
>> +
>> +   uint64_t k_name
>> +   uint64_t k_vendor
>> +   uint64_t k_attributes
>> +   uint64_t k_data_size
>> +   uint64_t k_data
> 
> Why is everything prefixed with k_ ?
> 

Bad style choice I stuck with to be consistent when writing this. Was 
intended to indicate "kernel" buffers that needed to be casted, however 
is unnecessary.

This document and the runtime services will be fixed in the next version.

>> +
>> +``k_name``
>> +   the name of the requested variable as a 16-bit char
>> +
>> +``k_vendor``
>> +   the vendor guid of the requested variable
>> +
>> +``k_attributes``
>> +   optional bitfield reference to be set by OPAL for attributes
>> +related to the variable data
>> +
>> +``k_data_size``
>> +   reference to the size of the ``k_data`` buffer. OPAL sets this if
>> +the buffer size is insufficient for the requested variable
>> +
>> +``k_data``
>> +   return buffer to store the data blob of the requested variable if
>> +a match was found
>> +
>> +Return Values
>> +-------------
>> +
>> +``OPAL_SUCCESS``
>> +   data from the requested variable was copied successfully, or
>> +``k_data`` was set to NULL and the ``k_data_size`` was set to the
>> +requested variable's size
>> +
>> +``OPAL_PARAMETER``
>> +   ``k_name``, ``k_vendor`` or ``k_data_size`` are invalid buffers,
>> +contain invalid values
>> +
>> +``OPAL_EMPTY``
>> +   no variable with the supplied ``k_name`` and ``k_vendor`` was found
>> +
>> +``OPAL_PARTIAL``
>> +   the buffer size provided in ``k_data_size`` is too small for the
>> +requested variable
>> +
>> +``OPAL_HARDWARE``
>> +   secure variable support is disabled
>> +
>> +OPAL_SECVAR_GET_NEXT
>> +====================
>> +::
>> +
>> +   #define OPAL_SECVAR_GET_NEXT                        171
>> +
>> +``OPAL_SECVAR_GET_NEXT`` returns the name and vendor guid of the next
>> +variable in the secure variable bank in sequence.
>> +
>> +Parameters
>> +----------
>> +::
>> +
>> +   uint64_t k_name_size
>> +   uint64_t k_name
>> +   uint64_t k_vendor
>> +
>> +``k_name_size``
>> +   size of the ``k_name`` buffer. OPAL sets this to the size of the
>> +next variable in sequence
>> +
>> +``k_name``
>> +   name of the previous variable or empty. The name of the next
>> +variable in sequence will be copied to ``k_name``
>> +
>> +``k_vendor``
>> +   vendor guid of the previous variable or empty. The vendor of the
>> +next vendor in sequence will be copied to ``k_vendor``
>> +
>> +Return Values
>> +-------------
>> +
>> +``OPAL_SUCCESS``
>> +  the name and vendor of the next variable in sequence was copied
>> +successfully
>> +
>> +``OPAL_PARAMETER``
>> +  ``k_name`` or ``k_vendor`` are invalid buffers, or were not found.
>> +``k_name_size`` is an invalid value. A variable matching
>> +the supplied non-empty ``k_name`` and ``k_vendor`` was not found
>> +
>> +``OPAL_EMPTY``
>> +  end of list reached
>> +
>> +``OPAL_PARTIAL``
>> +  the size specified in ``k_name_size`` is insufficient for the next
>> +variable's name size
>> +
>> +``OPAL_HARDWARE``
>> +  secure variable support is disabled
>> +
>> +OPAL_SECVAR_ENQUEUE
>> +===================
>> +::
>> +
>> +   #define OPAL_SECVAR_ENQUEUE                        172
>> +
>> +``OPAL_SECVAR_ENQUEUE`` call appends the supplied variable data to the
>> +queue for processing on next boot.
>> +
>> +Parameters
>> +----------
>> +::
>> +
>> +   uint64_t k_name
>> +   uint64_t k_vendor
>> +   uint64_t k_attributes
>> +   uint64_t k_data_size
>> +   uint64_t k_data
>> +
>> +``k_name``
>> +   the name of the submitted variable as a 16-bit char
>> +
>> +``k_vendor``
>> +   the vendor guid of the submitted variable
>> +
>> +``k_attributes``
>> +   bitfield of attributes
>> +
>> +``k_data_size``
>> +   size of the buffer to copy from ``k_data``
>> +
>> +``k_data``
>> +   blob of data to be stored
>> +
>> +Return Values
>> +-------------
>> +
>> +``OPAL_SUCCESS``
>> +   the variable was appended to the update queue bank successfully
>> +
>> +``OPAL_PARAMETER``
>> +   ``k_name``, ``k_vendor`` or ``k_data`` are invalid buffers.
>> +``k_name`` is empty. ``k_data_size`` is an invalid value.
>> +
>> +``OPAL_NO_MEM``
>> +   OPAL was unable to allocate memory for the variable
>> +
>> +``OPAL_UNSUPPORTED``
>> +   ``k_data_size`` was set to zero, implying an empty ``k_data`` buffer
>> +(may be used for variable deletion in the future)
>> +
>> +``OPAL_HARDWARE``
>> +   secure variable support is disabled
>> +
>> +OPAL_SECVAR_INFO
>> +================
>> +::
>> +
>> +   #define OPAL_SECVAR_INFO                        173
>> +
>> +``OPAL_SECVAR_INFO`` returns size information about the variable
>> +storage. Not currently implemented.
>> +
>> +Parameters
>> +----------
>> +::
>> +
>> +   uint64_t k_attributes
>> +   uint64_t k_storage_space
>> +   uint64_t k_remaining_space
>> +   uint64_t k_max_variable_size
>> +
>> +``k_attributes``
>> +   TODO
>> +
>> +``k_storage_space``
>> +   maximum storage space in bytes
>> +
>> +``k_remaining_space``
>> +   remaining storage space in bytes
>> +
>> +``k_max_variable_size``
>> +   maximum acceptable size for a data blob
>> +
>> +Return Values
>> +-------------
>> +
>> +``OPAL_UNSUPPORTED``
>> +  Runtime service is currently a stub, not currently implemented.
>> --
>> 2.17.2
>>
>> _______________________________________________
>> Skiboot mailing list
>> Skiboot@lists.ozlabs.org
>> https://lists.ozlabs.org/listinfo/skiboot
>

Eric Richter <erichte@linux.ibm.com> writes:
> This patch contains all the relevant documentation for the secure variable
> support in OPAL. This may be split and squashed with their relevant
> implementations in the future, but kept separate for now.
>
> Notably missing at the moment is the documentation for the SECBOOT PNOR
> partition usage, which will be included in a future revision.

Several thousand internet points for writing any documentation at all :)

>
> Signed-off-by: Eric Richter <erichte@linux.ibm.com>
> ---
>  doc/opal-api/opal-secvar.rst | 199 +++++++++++++++++++++++++++++++++++
>  1 file changed, 199 insertions(+)
>  create mode 100644 doc/opal-api/opal-secvar.rst
>
> diff --git a/doc/opal-api/opal-secvar.rst b/doc/opal-api/opal-secvar.rst
> new file mode 100644
> index 00000000..fd66e5e2
> --- /dev/null
> +++ b/doc/opal-api/opal-secvar.rst

An overview of the API would probably fit in well here, I think I am
getting most of the "How does this work" based on our previous
discussions rather than docs.

> @@ -0,0 +1,199 @@
> +OPAL_SECVAR_GET
> +===============
> +::
> +
> +   #define OPAL_SECVAR_GET                         170
> +
> +``OPAL_SECVAR_GET`` call retrieves a data blob associated with the supplied
> +name and vendor guid.
> +
> +Parameters
> +----------
> +::
> +
> +   uint64_t k_name
> +   uint64_t k_vendor
> +   uint64_t k_attributes
> +   uint64_t k_data_size
> +   uint64_t k_data

These should have types and not just uint64_t

> +
> +``k_name``
> +   the name of the requested variable as a 16-bit char

UCS-2 or UTF-16?

> +
> +``k_vendor``
> +   the vendor guid of the requested variable

GUID should probably be defined somewhere.

> +
> +``k_attributes``
> +   optional bitfield reference to be set by OPAL for attributes
> +related to the variable data
> +
> +``k_data_size``
> +   reference to the size of the ``k_data`` buffer. OPAL sets this if
> +the buffer size is insufficient for the requested variable
> +
> +``k_data``
> +   return buffer to store the data blob of the requested variable if
> +a match was found

is a NULL permitted? as in, finding out how big the variable is by
passing NULL for addr and getting the data size back?

> +
> +Return Values
> +-------------
> +
> +``OPAL_SUCCESS``
> +   data from the requested variable was copied successfully, or
> +``k_data`` was set to NULL and the ``k_data_size`` was set to the
> +requested variable's size
> +
> +``OPAL_PARAMETER``
> +   ``k_name``, ``k_vendor`` or ``k_data_size`` are invalid buffers,
> +contain invalid values
> +
> +``OPAL_EMPTY``
> +   no variable with the supplied ``k_name`` and ``k_vendor`` was found
> +
> +``OPAL_PARTIAL``
> +   the buffer size provided in ``k_data_size`` is too small for the
> +requested variable
> +
> +``OPAL_HARDWARE``
> +   secure variable support is disabled

What about
#define OPAL_UNSUPPORTED        -7
instead?

> +
> +OPAL_SECVAR_GET_NEXT
> +====================
> +::
> +
> +   #define OPAL_SECVAR_GET_NEXT                        171
> +
> +``OPAL_SECVAR_GET_NEXT`` returns the name and vendor guid of the next
> +variable in the secure variable bank in sequence.
> +
> +Parameters
> +----------
> +::
> +
> +   uint64_t k_name_size
> +   uint64_t k_name
> +   uint64_t k_vendor
> +
> +``k_name_size``
> +   size of the ``k_name`` buffer. OPAL sets this to the size of the
> +next variable in sequence
> +
> +``k_name``
> +   name of the previous variable or empty. The name of the next
> +variable in sequence will be copied to ``k_name``
> +
> +``k_vendor``
> +   vendor guid of the previous variable or empty. The vendor of the
> +next vendor in sequence will be copied to ``k_vendor``
> +
> +Return Values
> +-------------
> +
> +``OPAL_SUCCESS``
> +  the name and vendor of the next variable in sequence was copied
> +successfully
> +
> +``OPAL_PARAMETER``
> +  ``k_name`` or ``k_vendor`` are invalid buffers, or were not found.
> +``k_name_size`` is an invalid value. A variable matching
> +the supplied non-empty ``k_name`` and ``k_vendor`` was not found
> +
> +``OPAL_EMPTY``
> +  end of list reached
> +
> +``OPAL_PARTIAL``
> +  the size specified in ``k_name_size`` is insufficient for the next
> +variable's name size
> +
> +``OPAL_HARDWARE``
> +  secure variable support is disabled
> +
> +OPAL_SECVAR_ENQUEUE
> +===================
> +::
> +
> +   #define OPAL_SECVAR_ENQUEUE                        172
> +
> +``OPAL_SECVAR_ENQUEUE`` call appends the supplied variable data to the
> +queue for processing on next boot.
> +
> +Parameters
> +----------
> +::
> +
> +   uint64_t k_name
> +   uint64_t k_vendor
> +   uint64_t k_attributes
> +   uint64_t k_data_size
> +   uint64_t k_data
> +
> +``k_name``
> +   the name of the submitted variable as a 16-bit char
> +
> +``k_vendor``
> +   the vendor guid of the submitted variable
> +
> +``k_attributes``
> +   bitfield of attributes
> +
> +``k_data_size``
> +   size of the buffer to copy from ``k_data``
> +
> +``k_data``
> +   blob of data to be stored
> +
> +Return Values
> +-------------
> +
> +``OPAL_SUCCESS``
> +   the variable was appended to the update queue bank successfully
> +
> +``OPAL_PARAMETER``
> +   ``k_name``, ``k_vendor`` or ``k_data`` are invalid buffers.
> +``k_name`` is empty. ``k_data_size`` is an invalid value.
> +
> +``OPAL_NO_MEM``
> +   OPAL was unable to allocate memory for the variable
> +
> +``OPAL_UNSUPPORTED``
> +   ``k_data_size`` was set to zero, implying an empty ``k_data`` buffer
> +(may be used for variable deletion in the future)
> +
> +``OPAL_HARDWARE``
> +   secure variable support is disabled
> +
> +OPAL_SECVAR_INFO
> +================
> +::
> +
> +   #define OPAL_SECVAR_INFO                        173
> +
> +``OPAL_SECVAR_INFO`` returns size information about the variable
> +storage. Not currently implemented.
> +
> +Parameters
> +----------
> +::
> +
> +   uint64_t k_attributes
> +   uint64_t k_storage_space
> +   uint64_t k_remaining_space
> +   uint64_t k_max_variable_size
> +
> +``k_attributes``
> +   TODO
> +
> +``k_storage_space``
> +   maximum storage space in bytes
> +
> +``k_remaining_space``
> +   remaining storage space in bytes
> +
> +``k_max_variable_size``
> +   maximum acceptable size for a data blob
> +
> +Return Values
> +-------------
> +
> +``OPAL_UNSUPPORTED``
> +  Runtime service is currently a stub, not currently implemented.
> -- 
> 2.17.2
>
> _______________________________________________
> Skiboot mailing list
> Skiboot@lists.ozlabs.org
> https://lists.ozlabs.org/listinfo/skiboot
>