.\" 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" "1" "2024-12-19" "s390-tools" "UV-Secret Manual"
.nh
.ad l
.SH NAME
pvsecret \- Manage secrets for IBM Secure Execution guests
.SH SYNOPSIS
.nf
.fam C
pvsecret [OPTIONS] <COMMAND>
.fam C
.fi
.SH DESCRIPTION
Use \fBpvsecret\fR to manage secrets for IBM Secure Execution guests.
\fBpvsecret\fR can \fIcreate\fR add-secret requests on any architecture. On
s390x systems, use \fBpvsecret\fR to \fIadd\fR the secrets to the ultravisor
secret store, \fIlist\fR all secrets in the secret store, or \fIlock\fR the
secret store to prevent any modifications in the future.

The ultravisor secret store stores secrets for the IBM Secure Execution guest.
The secret store is cleared on guest reboot.

Create requests only on trusted systems that are not the IBM Secure Execution
guest where you want to inject the secrets. This approach prevents the secrets
from being in cleartext on the guest. For extra safety, do an attestation with
\fBpvattest\fR of your guest beforehand, and include the configuration UID in
the secret request using \fB--cuid\fR. Refer to \fBpvsecret-add\fR(1) for more
information. For all certificates, revocation lists, and host-key documents,
both the PEM and DER input formats are supported.

.SH "PVSECRET COMMANDS"
.PP

\fBpvsecret-create(1)\fR
.RS 4
Create a new add-secret request
.RE

.PP

\fBpvsecret-add(1)\fR
.RS 4
Submit an add-secret request to the Ultravisor (s390x only)
.RE

.PP

\fBpvsecret-lock(1)\fR
.RS 4
Lock the secret-store (s390x only)
.RE

.PP

\fBpvsecret-list(1)\fR
.RS 4
List all ultravisor secrets (s390x only)
.RE

.PP

\fBpvsecret-verify(1)\fR
.RS 4
Verify that an add-secret request is sane
.RE

.PP

\fBpvsecret-retrieve(1)\fR
.RS 4
Retrieve a secret from the UV secret store (s390x only)
.RE

.SH OPTIONS
.PP
\-v, \-\-verbose
.RS 4
Provide more detailed output.
.RE
.RE
.PP
\-q, \-\-quiet
.RS 4
Provide less output.
.RE
.RE
.PP
\-\-version
.RS 4
Print version information and exit.
.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. The program generates two
files. \fFaddsecreq.bin\fP contains the add-secret request. \fEXAMPLE.yaml\fP
contains the non-confidential information about the generated secret. It
contains name and id of the secret.
.PP
.nf
.fam C
	trusted:~$ pvsecret create \-k hkd.crt \-\-cert CA.crt \-\-cert ibmsk.crt \-\-hdr pvimage \-o addsecreq.bin association EXAMPLE
	Successfully generated the request
	Successfully wrote association info to 'EXAMPLE.yaml'
.fam T
.fi
On the SE-guest, \fIadd\fP the secret from request to the secret store.
.PP
.nf
.fam C
	seguest:~$ pvsecret add addsecreq.bin
	Successfully added the secret

.fam T
.fi
On the SE-guest, \fIlist\fP the secrets currently stored.
.PP
.nf
.fam C
	seguest:~$ pvsecret list
	Total number of secrets: 1

	0 Association:
		94ee059335e587e501cc4bf90613e0814f00a7b08bc7c648fd865a2af6a22cc2
.fam T
.fi

On the SE-guest, \fIlock\fP the secret store.
.PP
.nf
.fam C
	seguest:~$ pvsecret lock
	Successfully locked secret store
	seguest:~$ pvsecret add addsecreq.bin
	error: Ultravisor: 'secret store locked' (0x0102)


.fam T
.fi
.SH "SEE ALSO"
.sp
\fBpvsecret-create\fR(1) \fBpvsecret-add\fR(1) \fBpvsecret-lock\fR(1) \fBpvsecret-list\fR(1) \fBpvsecret-verify\fR(1) \fBpvsecret-retrieve\fR(1)