rsa 4.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241
  1. .TH RSA 8
  2. .SH NAME
  3. rsagen, rsafill, asn12rsa, rsa2pub, rsa2ssh, rsa2x509 \- generate and format rsa keys
  4. .SH SYNOPSIS
  5. .PP
  6. .B rsagen
  7. [
  8. .B -b
  9. .I nbits
  10. ]
  11. [
  12. .B -t
  13. .I tag
  14. ]
  15. .PP
  16. .B rsafill
  17. [
  18. .I file
  19. ]
  20. .PP
  21. .B asn12rsa
  22. [
  23. .B -t
  24. .I tag
  25. ]
  26. [
  27. .I file
  28. ]
  29. .PP
  30. .B rsa2pub
  31. [
  32. .I file
  33. ]
  34. .PP
  35. .B rsa2ssh
  36. [
  37. .I file
  38. ]
  39. .PP
  40. .B rsa2x509
  41. [
  42. .B -e
  43. .I expiretime
  44. ]
  45. .I certinfo
  46. [
  47. .I file
  48. ]
  49. .SH DESCRIPTION
  50. Plan 9 represents an RSA key as an attribute-value pair list
  51. prefixed with the string
  52. .BR key ;
  53. this is the generic key format used by
  54. .IR factotum (4).
  55. A full RSA private key has the following attributes:
  56. .TP
  57. .B proto
  58. must be
  59. .B rsa
  60. .TP
  61. .B size
  62. the number of significant bits in
  63. .B n
  64. .TP
  65. .B ek
  66. the encryption exponent
  67. .TP
  68. .B n
  69. the product of
  70. .B !p
  71. and
  72. .B !q
  73. .TP
  74. .B !dk
  75. the decryption exponent
  76. .TP
  77. .B !p
  78. a large prime
  79. .TP
  80. .B !q
  81. another large prime
  82. .TP
  83. .B "!kp\fR, \fL!kq\fR, \fL!c2
  84. parameters derived from the other attributes, cached to speed decryption
  85. .PD
  86. .LP
  87. All the numbers are in hexadecimal except
  88. .I size ,
  89. which is decimal.
  90. An RSA public key omits the attributes beginning with
  91. .L ! .
  92. A key may have other attributes as well (for example, a
  93. .B service
  94. attribute identifying how this key is typically used),
  95. but to these utilities such attributes are merely comments.
  96. .PP
  97. For example, a very small (and thus insecure) private key and corresponding
  98. public key might be:
  99. .IP
  100. .EX
  101. key proto=rsa size=8 ek=7 n=8F !dk=67 !p=B !q=D !kp=3 !kq=7 !c2=6
  102. key proto=rsa size=8 ek=7 n=8F
  103. .EE
  104. .LP
  105. Note that the order of the attributes does not matter.
  106. .PP
  107. .I Rsagen
  108. prints a randomly generated RSA private key
  109. whose
  110. .B n
  111. has exactly
  112. .I nbits
  113. (default 1024)
  114. significant bits.
  115. If
  116. .I tag
  117. is specified, it is printed between
  118. .B key
  119. and
  120. .BR proto=rsa ;
  121. typically,
  122. .I tag
  123. is a sequence of attribute-value comments describing the key.
  124. .PP
  125. .I Rsafill
  126. reads a private key,
  127. recomputes the
  128. .BR !kp ,
  129. .BR !kq ,
  130. and
  131. .BR !c2
  132. attributes if they are missing,
  133. and prints a full key.
  134. .PP
  135. .I Asn12rsa
  136. reads an RSA private key stored as ASN.1
  137. encoded in the binary Distinguished Encoding Rules (DER)
  138. and prints a Plan 9 RSA key,
  139. inserting
  140. .I tag
  141. exactly as
  142. .I rsagen
  143. does.
  144. ASN.1/DER is a popular key format on Unix and Windows;
  145. it is often encoded in text form using the Privacy Enhanced Mail (PEM) format
  146. in a section labeled as an
  147. .RB `` RSA
  148. .B PRIVATE
  149. .BR KEY .''
  150. The command:
  151. .IP
  152. .EX
  153. auth/pemdecode 'RSA PRIVATE KEY' | auth/asn12rsa
  154. .EE
  155. .LP
  156. extracts the key section from a textual ASN.1/DER/PEM key
  157. into binary ASN.1/DER format and then
  158. converts it to a Plan 9 RSA key.
  159. .PP
  160. .I Rsa2pub
  161. reads a Plan 9 RSA public or private key,
  162. removes the private attributes, and prints the resulting public key.
  163. Comment attributes are preserved.
  164. .PP
  165. .I Rsa2ssh
  166. reads a Plan 9 RSA public or private key and prints the public portion
  167. in the format used by SSH: three space-separated decimal numbers
  168. .BR size ,
  169. .BR ek ,
  170. and
  171. .BR n .
  172. For compatibility with external SSH implementations, the public keys in
  173. .B /sys/lib/ssh/keyring
  174. and
  175. .B $home/lib/keyring
  176. are stored in this format.
  177. .PP
  178. .I Rsa2x509
  179. reads a Plan 9 RSA private key and writes a self-signed X.509 certificate
  180. encoded in ASN.1/DER format to standard output.
  181. (Note that ASN.1/DER X.509 certificates are different from ASN.1/DER private keys).
  182. The certificate uses the current time as its start time and expires
  183. .I expiretime
  184. seconds
  185. (default 3 years)
  186. later.
  187. It contains the public half of the key
  188. and includes
  189. .I certinfo
  190. as the issuer/subject string (also known as a ``Distinguished Name'').
  191. This info is typically in the form:
  192. .IP
  193. .EX
  194. C=US ST=NJ L=07974 O=Lucent OU='Bell Labs' CN=G.R.Emlin
  195. .EE
  196. .LP
  197. The X.509 ASN.1/DER format is often encoded in text using a PEM section
  198. labeled as a
  199. .RB `` CERTIFICATE .''
  200. The command:
  201. .IP
  202. .EX
  203. auth/rsa2x509 'C=US OU=''Bell Labs''' file |
  204. auth/pemencode CERTIFICATE
  205. .EE
  206. .LP
  207. generates such a textual certificate.
  208. Applications that serve TLS-encrypted sessions (for example,
  209. .IR httpd (8),
  210. .IR pop3 (8),
  211. and
  212. .IR tlssrv (8))
  213. expect certificates in ASN.1/DER/PEM format.
  214. .SH EXAMPLES
  215. Generate a fresh key and use it to start a TLS-enabled web server:
  216. .IP
  217. .EX
  218. auth/rsagen -t 'service=tls owner=*' >key
  219. auth/rsa2x509 'C=US CN=*.cs.bell-labs.com' key |
  220. auth/pemencode CERTIFICATE >cert
  221. cat key >/mnt/factotum/ctl
  222. ip/httpd/httpd -c cert
  223. .EE
  224. .PP
  225. Generate a fresh key and configure a remote Unix system to
  226. allow use of that key for logins:
  227. .IP
  228. .EX
  229. auth/rsagen -t 'service=ssh' >key
  230. auth/rsa2ssh key | ssh unix 'cat >>.ssh/authorized_keys'
  231. cat key >/mnt/factotum/ctl
  232. ssh unix
  233. .EE
  234. .SH SOURCE
  235. .B /sys/src/cmd/auth
  236. .SH "SEE ALSO
  237. .IR factotum (4),
  238. .IR pem (8),
  239. .IR ssh (1)
  240. .SH BUGS
  241. There are too many key formats.