From 70676f658627f263224f6df532646a5aa9e87e57 Mon Sep 17 00:00:00 2001 From: "Kyle J. McKay" Date: Wed, 13 Jan 2021 14:10:54 -0700 Subject: [PATCH] httpspush.html: update with latest OpenSSH information Starting with OpenSSH version 7.8p1 (2018-08-23), the default format for OpenSSH private keys has become a new, specific-to-OpenSSH format. In order to be used for https pushing, the private key must be in a compatible format that can interoperate with the https software. Since OpenSSH version v8.1p1 (2019-10-09), the PKCS8 format (see RFC 5958) can be used. Prior to OpenSSH version v8.1p1, the older PEM format must be used. Add instructions detailing how to inspect the RSA private key and determine whether or not it's in a compatible format and, if not, how to convert it to a compatible format. Signed-off-by: Kyle J. McKay --- html/httpspush.html | 68 ++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 47 insertions(+), 21 deletions(-) diff --git a/html/httpspush.html b/html/httpspush.html index df49ffe..121e891 100644 --- a/html/httpspush.html +++ b/html/httpspush.html @@ -42,10 +42,10 @@ an ancient Git (i.e. prior to version 1.8.5) see the
  • Download your user certificate from the Register user confirmation page or the Update user email/SSH Keys page.
    • -
  • Identify the file containing your private key.
    • +
  • Identify the file containing your private key and make sure it’s in a compatible format.
  • Perform one-time Git global configuration of the @@ifcustom@@root certificate (http.sslCAInfo),@@end@@ user certificate (http.sslCert) and private key (http.sslKey) but only -for URLs starting with "@@base(httpspushurl)@@".
    • +for URLs starting with “@@base(httpspushurl)@@”. @@ -56,7 +56,7 @@ for URLs starting with "@@base(httpspushurl)@@".

    Download the root certificate (more information about it can be found here).

    -

    Assuming the root certificate will be stored in "$HOME/certs" it may be +

    Assuming the root certificate will be stored in “$HOME/certs” it may be downloaded like so:

    @@ -79,7 +79,7 @@ downloaded from the register user confirmation page or the edit
 user page.
    
 
 
    Please note that if you use ssh, you may already have a suitable RSA
-public key stored in the "$HOME/.ssh/id_rsa.pub" file.
    
+public key stored in the “$HOME/.ssh/id_rsa.pub” file.
    
 
 
    If you do not already have a suitable RSA public key (or you want to use
 a different one for this site) you will need to
@@ -88,28 +88,54 @@ the Register user page or the
 Update user email/SSH Keys page.
    
 
 
    A new RSA key (both public and private parts) can be generated using the
-"ssh-keygen -t rsa" command (from OpenSSH) or using a combination of
-the "openssl genrsa" command (from OpenSSL) and the
-"ConvertPubKey"
+“ssh-keygen -t rsa” command (from OpenSSH) or using a combination of
+the “openssl genrsa” command (from OpenSSL) and the
+“ConvertPubKey”
 command (from EZCert).
    
 
 
    Download your https push user certificate and store it in the
-"$HOME/certs" directory.  The downloaded user certificate file will
-have a name like "@@nickname@@_name_user_1.pem" where
-"name" is the user name you registered the public key for (the downloaded
-user certificate file may also have a suffix other than "_1" if
+“$HOME/certs” directory.  The downloaded user certificate file will
+have a name like “@@nickname@@_name_user_1.pem” where
+“name” is the user name you registered the public key for (the downloaded
+user certificate file may also have a suffix other than “_1” if
 you’ve registered more than one public key).
    
 
 
-
    @@ctr()@@. Locate your private key
    
+
    @@ctr()@@. Locate your private key and check its format
    
 
 
    
-
    If you registered "$HOME/.ssh/id_rsa.pub" as your public key then
+
    If you registered “$HOME/.ssh/id_rsa.pub” as your public key then
 your corresponding private key can most likely be found in
-"$HOME/.ssh/id_rsa".
    
+“$HOME/.ssh/id_rsa”.
    
 
 
    If you’re using a different RSA public key, you will need the full
 path to the corresponding private key portion for the next step.
    
+
+
    Check the format of your private key.  If it’s not in the file
+“$HOME/.ssh/id_rsa”, adjust the following
+commands accordingly.  Run this command:
    
+
+
    +head -n 1 "$HOME/.ssh/id_rsa"
+
    
+
+
    If the output is either of these lines:
    
+
    -----BEGIN RSA PRIVATE KEY-----
+-----BEGIN ENCRYPTED PRIVATE KEY-----
    
+
    Then you’re good to go.
    
+
+
    If the output is “-----BEGIN OPENSSH PRIVATE KEY-----” then you must
+convert it to one of the other two formats before it can be used for https pushing.
    
+
+
    If the output of “ssh -V” shows a version of at least 8.1p1 then the recommended
+format to use is “PKCS8” (although you may alternatively use the older “PEM”
+format if desired) and you can convert your private key file like so:
    
+
    ssh-keygen -p -m PKCS8 -f "$HOME/.ssh/id_rsa"
    
+
+
    If the output of “ssh -V” shows a version prior to 8.1p1 then you must use the
+“PEM” format and you can convert your private key file like so:
    
+
    ssh-keygen -p -m PEM -f "$HOME/.ssh/id_rsa"
    
+
 
    
 
 
    @@ctr()@@. Perform Git global configuration
    
@@ -119,11 +145,11 @@ path to the corresponding private key portion for the next step.
    
 (version 1.8.5 or later).  If you’re dealing with an ancient Git see the
 alternate instructions.
    
 
-
    Assuming @@ifcustom@@the root certificate has been downloaded and stored in "$HOME/certs",@@end@@
-the user certificate has been downloaded and stored in "$HOME/certs" and
-the private key is located in "$HOME/.ssh/id_rsa", the following will
-configure Git’s @@ifcustom@@"http.sslCAInfo", @@end@@"http.sslCert" and "http.sslKey"
-settings but only for URLs starting with "@@base(httpspushurl)@@":
    
+
    Assuming @@ifcustom@@the root certificate has been downloaded and stored in “$HOME/certs”,@@end@@
+the user certificate has been downloaded and stored in “$HOME/certs” and
+the private key is located in “$HOME/.ssh/id_rsa”, the following will
+configure Git’s @@ifcustom@@“http.sslCAInfo”, @@end@@“http.sslCert” and “http.sslKey”
+settings but only for URLs starting with “@@base(httpspushurl)@@”:
    
 
 
     @@ifcustom@@git config --global http.@@base(httpspushurl)@@.sslCAInfo \
@@ -149,7 +175,7 @@ git config --global http.@@base(httpspushurl)@@.sslCertPasswordProtected true
 
    
 
 
    OS X Note: Users of OS X 10.9 and later (including 10.10 etc.) please
-be advised that the system’s curl library ("/usr/lib/libcurl.4.dylib")
+be advised that the system’s curl library (“/usr/lib/libcurl.4.dylib”)
 has problems handling client certificates.  If you’re using a version of
 Git that uses that version of the curl library (Git uses libcurl to talk https),
@@ -250,7 +276,7 @@ error since your user most likely does not have permission to push to the
 
    Password Caching
    
 
 
    
-
    In the above examples, if the $HOME/.ssh/id_rsa private key is password
+
    In the above examples, if the “$HOME/.ssh/id_rsa” private key is password
 protected, then it’s desirable to set http.sslCertPasswordProtected
 to true like so:
    
 
-- 
2.11.4.GIT