From: Michael R Sweet Date: Tue, 6 May 2025 01:00:00 +0000 (-0400) Subject: Update cups-oauth and cups-x509 man pages. X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=84c43f486b80c55753248cdd233ded0941e31ab4;p=thirdparty%2Fcups.git Update cups-oauth and cups-x509 man pages. --- diff --git a/doc/help/man-cups-oauth.html b/doc/help/man-cups-oauth.html index f95acb591a..22f324def9 100644 --- a/doc/help/man-cups-oauth.html +++ b/doc/help/man-cups-oauth.html @@ -106,35 +106,35 @@ Specifies the OAuth/OpenID authorization server URL.

-s SCOPE(S)
Specifies a space-delimited list of scope names to use when authorizing access. -The default is to request authorization for all supported scopes. +The default is to request authorization for all supported OpenID scopes.

-

Commands

-

Authorize

+

Sub-Commands

+

Authorize

Starts an authorization workflow with the default web browser. If a resource URI is specified, the authorization is specific to that resource. The access token is send to the standard output on success.

-

Clear

+

Clear

Clears any authorization for the specified resource or for all resources if no resource URI is supplied.

-

Get-Access-Token

+

Get-Access-Token

Output the current, unexpired access token, if any, to the standard output.

-

Get-Client-Id

+

Get-Client-Id

Output the client ID string, if any, to the standard output.

-

Get-Metadata

+

Get-Metadata

Get the OAuth/OpenID authorization server metadata and send it to the standard output. If a name is specified, the output is just the value for the specified metadata.

-

Get-User-Id

+

Get-User-Id

Get the OpenID user ID information and send it to the standard output. If a name is specified, the output is just the named claim from the user ID.

-

Set-Access-Token

+

Set-Access-Token

Set the access token (which is sometimes also called an API key) for the specified resource or for all resources.

-

Set-Client-Data

+

Set-Client-Data

Set the client ID string and secret for an OAuth/OpenID authorization server.

Environment Variables

@@ -150,8 +150,18 @@ environment variable sets the default OAuth/OpenID scopes as a space-delimited l

CUPS uses a redirect URI of "http://127.0.0.1/" for all authorization on the local system.

Examples

-

TBD +

Register a client ID and secret for the OAuth server at "https://oauth.example.com/":

+ 
     cups-oauth -a https://oauth.example.com/ set-client-data CLIENT-ID CLIENT-SECRET
+
+

Save an access token (sometimes called an application or API key) for the OAuth server at "https://oauth.example.com/": +

+ 
     cups-oauth -a https://oauth.example.com/ set-access-token TOKEN
+
+

Authorize against the OAuth server at "https://oauth.example.com/" using your web browser: +

+ 
     cups-oauth -a https://oauth.example.com/ authorize
+

See Also

cups(1) diff --git a/doc/help/man-cups-x509.html b/doc/help/man-cups-x509.html index 8d0017cc22..987080fffe 100644 --- a/doc/help/man-cups-x509.html +++ b/doc/help/man-cups-x509.html @@ -58,7 +58,7 @@ -u USAGE ] -COMMAND +SUB-COMMAND [ARGUMENT(S)]

Description

@@ -124,32 +124,46 @@ Specify the usage for the certificate as a comma-delimited list of uses. The supported uses are "digitalSignature", "nonRepudiation", "keyEncipherment", "dataEncipherment", "keyAgreement", "keyCertSign", "cRLSign", "encipherOnly", and "decipherOnly". The preset "default-ca" specifies those uses required for a Certificate Authority, and the preset "default-tls" specifies those uses required for TLS.

-

Commands

-

Ca Common-Name

+

Sub-Commands

+

Ca Common-Name

Sign a certificate request for the specified common name.

-

Cacert Common-Name

+

Cacert Common-Name

Create a CA certificate for the specified common name.

-

Cert Common-Name

+

Cert Common-Name

Create a certificate for the specified common name.

-

Client Uri

+

Client Uri

Connect to the specified URI and validate the server's certificate.

-

Csr Common-Name

+

Csr Common-Name

Create a certificate signing request for the specified common name.

-

Server Common-Name[:Port]

+

Server Common-Name[:Port]

Run a HTTPS test server that echos back the resource path for every GET request. If PORT is not specified, uses a port number from 8000 to 8999.

-

Show Common-Name

+

Show Common-Name

Shows any stored credentials for the specified common name.

Examples

-

TBD +

Create a certificate signing request for a 384-bit ECDSA certificate for "server.example.com":

+ 
     cups-x509 csr -t ecdsa-p384 server.example.com
+
+

Install the certificate you get back from the CA for "server.example.com": +

+ 
     cups-x509 install server.example.com server.example.com.crt
+
+

Run a test server for "server.exmaple.com" on port 8080: +

+ 
     cups-x509 server SERVER-NAME:8080
+
+

Test a HTTPS client connection to "www.example.com" with validation: +

+ 
     cups-x509 client --require-ca https://www.example.com/
+

See Also

cups(1) diff --git a/man/cups-oauth.1 b/man/cups-oauth.1 index 7a7c0941aa..b2f34485bc 100644 --- a/man/cups-oauth.1 +++ b/man/cups-oauth.1 @@ -6,7 +6,7 @@ .\" Licensed under Apache License v2.0. See the file "LICENSE" for more .\" information. .\" -.TH cups-oauth 1 "CUPS" "2025-03-04" "OpenPrinting" +.TH cups-oauth 1 "CUPS" "2025-05-05" "OpenPrinting" .SH NAME cups-oauth \- interact with an oauth/openid authorization server .SH SYNOPSIS @@ -104,8 +104,8 @@ Specifies the OAuth/OpenID authorization server URL. .TP 5 \fB\-s \fISCOPE(S)\fR Specifies a space-delimited list of scope names to use when authorizing access. -The default is to request authorization for all supported scopes. -.SH COMMANDS +The default is to request authorization for all supported OpenID scopes. +.SH SUB-COMMANDS .SS authorize Starts an authorization workflow with the default web browser. If a resource URI is specified, the authorization is specific to that resource. @@ -137,7 +137,18 @@ environment variable sets the default OAuth/OpenID scopes as a space-delimited l .SH NOTES CUPS uses a redirect URI of "http://127.0.0.1/" for all authorization on the local system. .SH EXAMPLES -TBD +Register a client ID and secret for the OAuth server at "https://oauth.example.com/": +.nf + cups-oauth -a https://oauth.example.com/ set-client-data CLIENT-ID CLIENT-SECRET +.fi +Save an access token (sometimes called an application or API key) for the OAuth server at "https://oauth.example.com/": +.nf + cups-oauth -a https://oauth.example.com/ set-access-token TOKEN +.fi +Authorize against the OAuth server at "https://oauth.example.com/" using your web browser: +.nf + cups-oauth -a https://oauth.example.com/ authorize +.fi .SH SEE ALSO .BR cups (1) .SH COPYRIGHT diff --git a/man/cups-x509.1 b/man/cups-x509.1 index 2f42ab71b3..2695804c39 100644 --- a/man/cups-x509.1 +++ b/man/cups-x509.1 @@ -6,7 +6,7 @@ .\" Licensed under Apache License v2.0. See the file "LICENSE" for more .\" information. .\" -.TH cups-x509 1 "CUPS" "2025-03-04" "OpenPrinting" +.TH cups-x509 1 "CUPS" "2025-05-05" "OpenPrinting" .SH NAME cups-x509 \- description .SH SYNOPSIS @@ -58,7 +58,7 @@ cups-x509 \- description .B \-u .I USAGE ] -.I COMMAND +.I SUB-COMMAND .I [ARGUMENT(S)] .SH DESCRIPTION The @@ -121,7 +121,7 @@ Specify the certificate type - "rsa-2048" for 2048-bit RSA, "rsa-3072" for 3072- Specify the usage for the certificate as a comma-delimited list of uses. The supported uses are "digitalSignature", "nonRepudiation", "keyEncipherment", "dataEncipherment", "keyAgreement", "keyCertSign", "cRLSign", "encipherOnly", and "decipherOnly". The preset "default-ca" specifies those uses required for a Certificate Authority, and the preset "default-tls" specifies those uses required for TLS. -.SH COMMANDS +.SH SUB-COMMANDS .SS ca COMMON-NAME Sign a certificate request for the specified common name. .SS cacert COMMON-NAME @@ -138,7 +138,22 @@ If PORT is not specified, uses a port number from 8000 to 8999. .SS show COMMON-NAME Shows any stored credentials for the specified common name. .SH EXAMPLES -TBD +Create a certificate signing request for a 384-bit ECDSA certificate for "server.example.com": +.nf + cups-x509 csr -t ecdsa-p384 server.example.com +.fi +Install the certificate you get back from the CA for "server.example.com": +.nf + cups-x509 install server.example.com server.example.com.crt +.fi +Run a test server for "server.exmaple.com" on port 8080: +.nf + cups-x509 server SERVER-NAME:8080 +.fi +Test a HTTPS client connection to "www.example.com" with validation: +.nf + cups-x509 client --require-ca https://www.example.com/ +.fi .SH SEE ALSO .BR cups (1) .SH COPYRIGHT