RSA(2)                                                     RSA(2)

     NAME
          asn1dump, asn1toRSApriv, asn1encodeRSApriv,
          asn1encodeRSApub, decodePEM, rsadecrypt, rsaencrypt,
          rsafill, rsagen, rsaprivalloc, rsaprivfree, rsaprivtopub,
          rsapuballoc, rsapubfree, X509toRSApub, X509rsagen,
          X509rsareq, X509rsaverify, X509rsaverifydigest - RSA
          encryption algorithm

     SYNOPSIS
          #include <u.h>
          #include <libc.h>
          #include <mp.h>
          #include <libsec.h>

          RSApriv* rsagen(int nlen, int elen, int nrep)

          RSApriv* rsafill(mpint *n, mpint *e, mpint *d, mpint *p,
          mpint *q)

          mpint*   rsaencrypt(RSApub *k, mpint *in, mpint *out)

          mpint*   rsadecrypt(RSApriv *k, mpint *in, mpint *out)

          RSApub*  rsapuballoc(void)

          void     rsapubfree(RSApub*)

          RSApriv* rsaprivalloc(void)

          void     rsaprivfree(RSApriv*)

          RSApub*  rsaprivtopub(RSApriv*)

          RSApub*  X509toRSApub(uchar *cert, int ncert, char *name,
          int nname)

          RSApriv* asn1toRSApriv(uchar *priv, int npriv)

          int      asn1encodeRSApriv(RSApriv *k, uchar *buf, int len)

          int      asn1encodeRSApub(RSApub *pk, uchar *buf, int len)

          void     asn1dump(uchar *der, int len)

          uchar*   decodePEM(char *s, char *type, int *len, char
          **new_s)

          uchar*   X509rsagen(RSApriv *priv, char *subj, ulong
          valid[2], int *certlen);

     Page 1                       Plan 9            (printed 10/14/24)

     RSA(2)                                                     RSA(2)

          uchar*   X509rsareq(RSApriv *priv, char *subj, int
          *certlen);

          char*    X509rsaverify(uchar *cert, int ncert, RSApub *pk)

          char*    X509rsaverifydigest(uchar *sig, int siglen, uchar
          *edigest, int edigestlen, RSApub *pk)

     DESCRIPTION
          RSA is a public key encryption algorithm.  The owner of a
          key publishes the public part of the key:

               struct RSApub
               {
                    mpint     *n;  /* modulus */
                    mpint     *ek; /* exp (encryption key) */
               };

          This part can be used for encrypting data (with rsaencrypt)
          to be sent to the owner.  The owner decrypts (with
          rsadecrypt) using his private key:

               struct RSApriv
               {
                    RSApub    pub;
                    mpint     *dk; /* exp (decryption key) */

                    /* precomputed crt values */
                    mpint     *p;
                    mpint     *q;
                    mpint     *kp; /* k mod p-1 */
                    mpint     *kq; /* k mod q-1 */
                    mpint     *c2; /* for converting residues to number */
               };

          Keys are generated using rsagen. Rsagen takes both bit
          length of the modulus, the bit length of the public key
          exponent, and the number of repetitions of the Miller-Rabin
          primality test to run.  If the latter is 0, it does the
          default number of rounds.  Rsagen returns a newly allocated
          structure containing both public and private keys.  Rsafill
          returns a newly allocated private key by recomputing kp, kq,
          and c2. Rsaprivtopub returns a newly allocated copy of the
          public key corresponding to the private key.

          The routines rsaalloc, rsafree, rsapuballoc, rsapubfree,
          rsaprivalloc, and rsaprivfree are provided to aid in user
          provided key I/O.

          Given a binary X.509 cert, the routine X509toRSApub returns
          the public key and, if name is not nil, the CN part of the
          Distinguished Name of the certificate's Subject.  (This is

     Page 2                       Plan 9            (printed 10/14/24)

     RSA(2)                                                     RSA(2)

          conventionally a userid or a host DNS name.)  No verifica-
          tion is done of the certificate signature;  the caller
          should check the fingerprint, sha1(cert), against a table or
          check the certificate by other means.  X.509 certificates
          are often stored in PEM format; use dec64 to convert to
          binary before computing the fingerprint or calling
          X509toRSApub. For the special case of certificates signed by
          a known trusted key (in a single step, without certificate
          chains), X509rsaverify checks the signature on cert. It
          returns nil if successful, else an error string.

          X509rsaverifydigest takes a encoded PKCS #1 signature as
          used in X.509 as sig[siglen] and verifies it against the
          expected cryptographic hash edigest[edigestlen] of the
          signed data; returning nil on success or an error string.

          X509rsagen creates a self-signed X.509 certificate, given an
          RSA keypair priv, a issuer/subject string subj, and the
          starting and ending validity dates, valid. Length of the
          allocated binary certificate is stored in certlen. The sub-
          ject line is conventionally of the form

               C=US ST=NJ L=07922 O=Lucent OU='Bell Labs' CN=Eric

          using the quoting conventions of tokenize in getfields(2).

          Asn1toRSApriv converts an ASN1 formatted RSA private key
          into the corresponding RSApriv structure.

          Asn1encodeRSApriv and asn1encodeRSApub export a RSApriv or
          RSApub structure to ASN1 format.  On success, buf is filled
          and the encoded byte length is returned.  Otherwise -1 is
          returned and error string is set.

          Asn1dump prints an ASN1 object to standard output.

          DecodePEM takes a zero terminated string, s, and decodes the
          PEM (privacy-enhanced mail) formatted section for type
          within it.  If successful, it returns malloced storage con-
          taining the decoded section, which the caller must free, and
          sets *len to its decoded length.  Otherwise nil is returned
          and *len is undefined.  If not nil, new_s is set to the
          first character beyond the type section.

     SOURCE
          /sys/src/libsec

     SEE ALSO
          mp(2), aes(2), blowfish(2), des(2), dsa(2), elgamal(2),
          rc4(2), sechash(2), prime(2), rand(2), rsa(8)

     Page 3                       Plan 9            (printed 10/14/24)