mirror of
https://github.com/ibm-s390-linux/s390-tools.git
synced 2026-08-05 02:14:52 +00:00
Steffen Eiden
a8a3e7d49c
Acked-by: Marc Hartmayer <marc@linux.ibm.com> Reviewed-by: Christoph Schlameuss <schlameuss@linux.ibm.com> Signed-off-by: Steffen Eiden <seiden@linux.ibm.com> Signed-off-by: Jan Höppner <hoeppner@linux.ibm.com>
145 lines
4.4 KiB
Groff
145 lines
4.4 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" "2024-12-19" "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] <FILE>
|
|
.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
|
|
<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 <FILE>
|
|
.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.
|
|
[default: '-']
|
|
.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 datai similar to the example for \fFpvsecret\fP. Let's assume there are three more files present .\fFuser_data\fP contains ascii "some example user-data", a private user-signing key e.g. rsa3072 \fFusr_sgn_key.priv.pem\fF, and a certificate containing the corresponding public key to the private rsa3072 key \fFuser_cert.pem\fP.
|
|
.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 \fFSuccesfully verified the request.\fP 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)
|