git.sr.ht/~pingoo/stdx@v0.0.0-20240218134121-094174641f6e/otp/doc.go (about)

     1  /**
     2   *  Copyright 2014 Paul Querna
     3   *
     4   *  Licensed under the Apache License, Version 2.0 (the "License");
     5   *  you may not use this file except in compliance with the License.
     6   *  You may obtain a copy of the License at
     7   *
     8   *      http://www.apache.org/licenses/LICENSE-2.0
     9   *
    10   *  Unless required by applicable law or agreed to in writing, software
    11   *  distributed under the License is distributed on an "AS IS" BASIS,
    12   *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13   *  See the License for the specific language governing permissions and
    14   *  limitations under the License.
    15   *
    16   */
    17  
    18  // Package otp implements both HOTP and TOTP based
    19  // one time passcodes in a Google Authenticator compatible manner.
    20  //
    21  // When adding a TOTP for a user, you must store the "secret" value
    22  // persistently. It is recommend to store the secret in an encrypted field in your
    23  // datastore.  Due to how TOTP works, it is not possible to store a hash
    24  // for the secret value like you would a password.
    25  //
    26  // To enroll a user, you must first generate an OTP for them.  Google
    27  // Authenticator supports using a QR code as an enrollment method:
    28  //
    29  //	import (
    30  //		"git.sr.ht/~pingoo/stdx/otp/totp"
    31  //
    32  //		"bytes"
    33  //		"image/png"
    34  //	)
    35  //
    36  //	key, err := totp.Generate(totp.GenerateOpts{
    37  //			Issuer: "Example.com",
    38  //			AccountName: "alice@example.com",
    39  //	})
    40  //
    41  //	// Convert TOTP key into a QR code encoded as a PNG image.
    42  //	var buf bytes.Buffer
    43  //	img, err := key.Image(200, 200)
    44  //	png.Encode(&buf, img)
    45  //
    46  //	// display the QR code to the user.
    47  //	display(buf.Bytes())
    48  //
    49  //	// Now Validate that the user's successfully added the passcode.
    50  //	passcode := promptForPasscode()
    51  //	valid := totp.Validate(passcode, key.Secret())
    52  //
    53  //	if valid {
    54  //		// User successfully used their TOTP, save it to your backend!
    55  //		storeSecret("alice@example.com", key.Secret())
    56  //	}
    57  //
    58  // Validating a TOTP passcode is very easy, just prompt the user for a passcode
    59  // and retrieve the associated user's previously stored secret.
    60  //
    61  //	import "git.sr.ht/~pingoo/stdx/otp/totp"
    62  //
    63  //	passcode := promptForPasscode()
    64  //	secret := getSecret("alice@example.com")
    65  //
    66  //	valid := totp.Validate(passcode, secret)
    67  //
    68  //	if valid {
    69  //		// Success! continue login process.
    70  //	}
    71  package otp