mirror of
https://github.com/ibm-s390-linux/s390-tools.git
synced 2026-08-05 02:14:52 +00:00
Steffen Eiden
b6a4d7a6c1
Signed-off-by: Steffen Eiden <seiden@linux.ibm.com> Signed-off-by: Jan Höppner <hoeppner@linux.ibm.com>
167 lines
4.6 KiB
Groff
167 lines
4.6 KiB
Groff
.\" Copyright 2023, 2024 IBM Corp.
|
|
.\" s390-tools is free software; you can redistribute it and/or modify
|
|
.\" it under the terms of the MIT license. See LICENSE for details.
|
|
.\"
|
|
|
|
.TH "PVSECRET-VERIFY" "1" "2026-05-21" "s390-tools" "UV\-Secret Manual"
|
|
.nh
|
|
.ad l
|
|
.SH NAME
|
|
pvsecret-verify \- Verify that an add-secret request is sane
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.fam C
|
|
pvsecret verify [OPTIONS] [INPUT] [OUTPUT]
|
|
.fam C
|
|
.fi
|
|
.SH DESCRIPTION
|
|
.PP
|
|
Verifies that the given request is an Add\-Secret request by testing for some
|
|
values to be present. If the request contains signed user\-data, the signature
|
|
is verified with the provided key. Outputs the arbitrary user\-data. All data in
|
|
the request is in big endian.
|
|
.PP
|
|
\fIverify\fP checks the following:
|
|
.RS
|
|
.IP \[bu] 2
|
|
The first 6 bytes of the request are equal to: \fB6173 7263 624d | asrcbM\fP
|
|
.IP \[bu] 2
|
|
The sizes in the request header are sane and do not point out of the
|
|
file
|
|
.IP \[bu] 2
|
|
The request version is supported by the binary
|
|
.IP \[bu] 2
|
|
If user\-data contains a signature, verify the signature using a public
|
|
key
|
|
.RE
|
|
.PP
|
|
The content of bytes 6&7 of the request define which kind
|
|
of user\-data the request contains.
|
|
.IP \fB0x0000\fP 8
|
|
no user\-data (512 bytes zero)
|
|
.IP \fB0x0001\fP 8
|
|
512 bytes user\-data
|
|
.IP \fB0x0002\fP 8
|
|
265 bytes user\-data| 139 bytes ecdsa signature | 5 bytes reserved | 2 bytes
|
|
signature size | ...
|
|
.IP \fB0x0003\fP 8
|
|
256 bytes user\-data | 256 bytes rsa2048 signature
|
|
.IP \fB0x0004\fP 8
|
|
128 bytes user\-data | 384 bytes rsa3072 signature
|
|
.PP
|
|
The actual user\-data may be less than the capacity. If less data was provided
|
|
during \fIcreate\fP zeros are appended.
|
|
.
|
|
For type 2\-4 The signature is calculated as follows:
|
|
.RS
|
|
.IP "1." 3
|
|
The request is generated with the user\-data in place and zeros for the
|
|
signature data.
|
|
.IP "2." 3
|
|
The signature is calculated for the request. The signature signs the
|
|
authenticated data and the encrypted data, but not the request tag. I.e. the
|
|
signature signs the whole request but the last 16 bytes and with the signature
|
|
bytes set to zero.
|
|
.IP "3." 3
|
|
The signature is inserted to its location in the request.
|
|
.IP "4." 3
|
|
The request GCM tag is calculated.
|
|
.PP
|
|
.RE
|
|
|
|
The verification process works as follows:
|
|
.RS
|
|
.IP "1." 3
|
|
copy the signature to a buffer
|
|
.IP "2." 3
|
|
overwrite the signature with zeros
|
|
.IP "3." 3
|
|
verify the signature of the request but the last 16 bytes
|
|
.RE
|
|
|
|
.SH OPTIONS
|
|
.PP
|
|
<INPUT>
|
|
.RS 4
|
|
Specify the request to be checked.
|
|
.RE
|
|
.RE
|
|
.PP
|
|
<OUTPUT>
|
|
.RS 4
|
|
Store the result in FILE If the request contained abirtary user\-data the output
|
|
contains this user\-data with padded zeros if available.
|
|
.RE
|
|
.RE
|
|
|
|
.PP
|
|
\-i, \-\-input <FILE>
|
|
.RS 4
|
|
Specify the request to be checked.
|
|
.RE
|
|
.RE
|
|
.PP
|
|
\-\-user\-cert <FILE>
|
|
.RS 4
|
|
Certificate containing a public key used to verify the user data signature.
|
|
Specifies a public key used to verify the user\-data signature. The file must be
|
|
a X509 certificate in DSA or PEM format. The certificate must hold the public
|
|
EC, RSA 2048, or RSA 3072 key corresponding to the private user\-key used during
|
|
`create`. No chain of trust is established. Ensuring that the certificate can be
|
|
trusted is the responsibility of the user. The EC key must use the NIST/SECG
|
|
curve over a 521 bit prime field (secp521r1).
|
|
.RE
|
|
.RE
|
|
.PP
|
|
\-o, \-\-output <OUTPUT>
|
|
.RS 4
|
|
Store the result in FILE If the request contained abirtary user\-data the output
|
|
contains this user\-data with padded zeros if available.
|
|
.RE
|
|
.RE
|
|
.PP
|
|
\-h, \-\-help
|
|
.RS 4
|
|
Print help (see a summary with \fB\-h\fR).
|
|
.RE
|
|
.RE
|
|
|
|
.SH EXAMPLES
|
|
.PP
|
|
Create the add\-secret request on a trusted system with signed user data similar
|
|
to the example for \fBpvsecret\fR. Let's assume there are three more files
|
|
present. \fIuser_data\fR contains ascii "some example user\-data", a private
|
|
user\-signing key e.g. rsa3072 \fIusr_sgn_key.priv.pem\fR, and a certificate
|
|
containing the corresponding public key to the private rsa3072 key
|
|
\fIuser_cert.pem\fR.
|
|
.PP
|
|
.RS
|
|
.IP trusted:~$ 12
|
|
pvsecret create \-k hkd.crt \-\-cert CA.crt \-\-cert ibmsk.crt \-\-hdr pvimage
|
|
\-o addsecreq.bin \-\-user\-data user_data \-\-user\-sign\-key
|
|
usr_sgn_key.priv.pem association EXAMPLE
|
|
.RE
|
|
.RS
|
|
Successfully generated the request
|
|
.br
|
|
Successfully wrote association info to 'EXAMPLE.yaml'
|
|
.RE
|
|
|
|
For example, on the SE\-guest, perform \fIverify\fP on the request to verify the
|
|
user\-signature and the saneness of the request. On success, The user\-data is
|
|
printed to stdout (if \fI\-\-output\fP was not specified) and \fBSuccesfully
|
|
verified the request.\fR is printed to stderr.
|
|
.PP
|
|
.RS
|
|
.IP seguest:~$ 12
|
|
pvsecret verify \-\-user\-cert user_cert.pem \-o addsecreq.bin
|
|
.RE
|
|
.RS
|
|
some example user\-data
|
|
.br
|
|
Successfully verified the request
|
|
.RE
|
|
.SH "SEE ALSO"
|
|
.sp
|
|
\fBpvsecret\fR(1)
|